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.
| Gate | Protocol | When |
|---|
spec-approval | SPIR | After spec is written |
plan-approval | SPIR | After plan is written |
pr | SPIR, TICK, AIR | After 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 ...)
Language-agnostic checks (porch.checks override)
Protocol check commands default to the npm toolchain (npm run build, npm test, etc.) baked into each protocol.json. A non-Node project (Python/uv, Go, Rust) will BLOCK at the first implement-phase check because npm can never pass there — even when the code is green under its real test runner.
You do NOT need to fork protocol.json. Override check commands per-name in .codev/config.json under porch.checks. Each entry takes command (replace), cwd (replace), and/or skip: true. This covers both phase checks and the phase_completion predicates (build_succeeds / tests_pass).
// .codev/config.json — Python/uv example
{
"porch": {
"checks": {
"build": { "command": "uv build" },
"test": { "command": "uv run pytest" },
"build_succeeds": { "command": "uv build" },
"tests_pass": { "command": "uv run pytest" },
"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 (phase_completion predicates take no timeout), e.g. "tests": { "command": "uv run pytest", "timeout_ms": 900000 } for a long suite. On timeout porch kills the check's whole process tree.
Keys are the check names from the protocol: build / test / e2e_tests live in phases; build_succeeds / tests_pass live in phase_completion. An override key that matches no check in the protocol prints a warning. Shipped by Spec #550.
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.