Skip to content
cccskills
FreePublished on GitHub

porch

Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, and BUGFIX protocols via a state machine. ALWAYS check this skill before running any `porch` command. Use when you need to check project status, approve gates, signal phase completion, or manage protocol state. Also use when a builder asks about gate approvals or phase transitions.

The English summary is being prepared. Showing the original description.

cluesmith/codev290 stars(GitHub 290 + cccskills 0)

Run score Not tested

See how to install

Files included (1)

  • SKILL.md3.3 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

porch - Protocol Orchestrator

Porch manages the state machine behind development protocols. It tracks phases, gates, consultations, and transitions.

Commands

porch status [id]              Show current project state and phase
porch run [id]                 Run the protocol loop (strict mode)
porch next [id]                Get next tasks as JSON
porch done [id]                Signal current phase is complete
porch check [id]               Run checks for current phase
porch gate [id]                Request human approval at a gate
porch approve <id> <gate> --a-human-explicitly-approved-this
porch rollback <id> <phase>    Rewind to an earlier phase
porch init <protocol> <id> <name>   Initialize a new project

Project ID auto-detects from worktree path when inside a builder worktree.

Gate approvals

Gates are human-only approval checkpoints. The --a-human-explicitly-approved-this flag is required — it exists to prevent AI agents from auto-approving.

GateProtocolWhen
spec-approvalSPIRAfter spec is written
plan-approvalSPIRAfter plan is written
prSPIR, AIRAfter PR is created
porch approve 42 spec-approval --a-human-explicitly-approved-this
porch approve 42 plan-approval --a-human-explicitly-approved-this
porch approve 42 pr --a-human-explicitly-approved-this

ASPIR and BUGFIX have no spec/plan gates — they run autonomously through those phases.

Checking pending gates

porch pending                  # List all gates waiting for approval
porch pending --all            # Include stale records on finished/advanced projects (hidden by default)

Critical rules

  • Builders must NEVER call porch approve — only humans approve gates
  • Never edit status.yaml directly — porch manages all state
  • Builders signal completion with porch done, not porch approve
  • porch run is for strict mode only — soft mode builders follow the protocol document manually
  • When running porch approve from the architect, use a subshell if you need worktree context: (cd /path/to/worktree && porch approve ...)

Check overrides and timeouts (porch.checks)

Override a protocol check per name in .codev/config.json under porch.checks instead of forking protocol.json. Each entry takes command (replace), cwd (replace), timeout_ms (replace), and/or skip: true:

{
  "porch": {
    "checks": {
      "tests":     { "command": "uv run pytest", "timeout_ms": 900000 },
      "e2e_tests": { "skip": true }
    }
  }
}

A phase check is killed after 5 minutes unless it sets timeout_ms — in protocol.json or in its porch.checks override. On timeout porch kills the check's whole process tree.

State storage

Project state lives in codev/projects/<id>-<name>/status.yaml, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

afx

Free

Agent Farm CLI — the tool for spawning builders, managing Tower, workspaces, and cron tasks. ALWAYS consult this skill BEFORE running any `afx` command to get the exact syntax. This prevents wasting time guessing flags that don't exist. Use this whenever you need to spawn a builder, check status, send messages, clean up worktrees, manage Tower, or run cron tasks. If you're about to type `afx` followed by anything, check here first.

The English summary is being prepared. Showing the original description.

cluesmith/codev290Updated Oct 24, 2026

arch-init

Free

Adopt an architect identity and recover its state from codev/state/<name>.md. Use when an architect terminal needs to (re)establish which architect it is — after a restart, context loss, or session handoff — or when the user says "/arch-init", "you are the X architect", or "recover your architect state". Identity resolves via `afx whoami` (an explicit name argument overrides); if neither resolves, ask the human — never guess.

The English summary is being prepared. Showing the original description.

cluesmith/codev290Updated Oct 24, 2026

arch-save

Free

Save an architect's state, clear its context, and re-init automatically — the packaged save→clear→re-init refresh cycle. Use when the owner directs a context refresh, or says "/arch-save", "save and clear", "refresh your context". Runs on the owner's direction; an architect does not invoke it autonomously mid-task. Counterpart to /arch-init, which recovers the state this writes.

The English summary is being prepared. Showing the original description.

cluesmith/codev290Updated Oct 24, 2026

builder-refresh

Free

Refresh a builder's own context at a protocol boundary — save working state, verify it, clear, and re-orient. Use when porch emits a context-refresh task, or the builder is told to "refresh your context" / "run a self-refresh". A builder does not invoke this autonomously mid-task; porch chooses the moment. Counterpart to the architect's /arch-save.

The English summary is being prepared. Showing the original description.

cluesmith/codev290Updated Oct 24, 2026

codev

Free

Codev project management CLI — init, adopt, bootstrap-docs, update, and doctor commands. Check this skill before running any `codev` command (except `consult`, `porch`, or `afx` which have their own skills). Use when setting up new projects, adding codev to existing repos, updating framework files, or diagnosing missing dependencies.

The English summary is being prepared. Showing the original description.

cluesmith/codev290Updated Oct 24, 2026

consult

Free

AI consultation CLI — query Gemini, Codex, or Claude for reviews and analysis. ALWAYS check this skill before running any `consult` command. Use when reviewing specs, plans, implementations, or PRs with external models, running parallel 3-way reviews (cmap), or checking consultation stats. The `-m` model flag is always required except for `consult stats`.

The English summary is being prepared. Showing the original description.

cluesmith/codev290Updated Oct 24, 2026

See all skills by cluesmith

Report a problem with this skill