porch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

porch - Protocol Orchestrator

porch - 协议编排器

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

Porch负责管理开发协议背后的状态机，跟踪阶段、关卡、咨询和过渡流程。

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.

porch status [id]              显示当前项目状态和阶段
porch run [id]                 运行协议循环（严格模式）
porch next [id]                以JSON格式获取下一阶段任务
porch done [id]                标记当前阶段完成
porch check [id]               运行当前阶段的检查项
porch gate [id]                在关卡处请求人工批准
porch approve <id> <gate> --a-human-explicitly-approved-this
porch rollback <id> <phase>    回退到更早的阶段
porch init <protocol> <id> <name>   初始化新项目

当处于构建人员工作树中时，项目ID会自动从工作树路径检测获取。

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, AIR	After PR is created

bash

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.

关卡是仅允许人工操作的批准检查点。必须使用

--a-human-explicitly-approved-this

标志——该标志的存在是为了防止AI Agent自动批准。

关卡	协议	触发时机
`spec-approval`	SPIR	完成规格文档编写后
`plan-approval`	SPIR	完成计划文档编写后
`pr`	SPIR, AIR	创建PR后

bash

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和BUGFIX没有规格/计划关卡——它们会自主完成这些阶段。

Checking pending gates

检查待处理关卡

bash

porch pending                  # List all gates waiting for approval

bash

porch pending                  # 列出所有等待批准的关卡

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 ...)
```

构建人员绝对不能调用
porch approve
——仅允许人工批准关卡
切勿直接编辑
status.yaml
——所有状态由porch管理
构建人员使用
```
porch done
```
标记阶段完成，而非
```
porch approve
```
```
porch run
```
仅适用于严格模式——宽松模式下构建人员需手动遵循协议文档
当从架构师端运行
```
porch approve
```
时，若需要工作树上下文，请使用子shell：
```
(cd /path/to/worktree && porch approve ...)
```

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.

项目状态存储在

codev/projects/<id>-<name>/status.yaml

中，由porch自动管理。状态文件会跟踪当前阶段、关卡状态、咨询结果和时间戳。