Pace

/pace — Athena PACE Orchestration (v9.6.2)

概念

PACE = Path + Agenda + Constraint + Exit. 一句话: 按路径分流, 状态机推进, 规范注入, 退出可验证.

6 路径 (按复杂度递增)

flowchart LR
    A[用户输入] --> R{路由判断}
    R -->|typo/config/1-line| H[Hotfix]
    R -->|bug| B[Bugfix]
    R -->|小改动 ≤30min| Q[Quick]
    R -->|新功能| F[Feature]
    R -->|结构性改动| Re[Refactor]
    R -->|系统级| S[System]

6 stage (状态机)

stateDiagram-v2
    [*] --> plan
    plan --> design : System 路径
    plan --> impl : Quick/Feature/Refactor 路径
    design --> impl
    impl --> review
    review --> polish : Refactor/System 路径 且 VERDICT ∈ {PASS, CONCERNS}
    review --> ship : Quick/Feature/Bugfix 路径 且 VERDICT = PASS
    review --> impl : VERDICT ∈ {REWORK, FAIL}
    polish --> ship
    ship --> [*]

    note right of polish
        v9.6.2 新增
        仅 Refactor/System
        清理临时代码
        完善注释
        检查冗余/低效/过度设计
    end note

stage × path 矩阵 (哪个 stage 在哪个路径)

stage × subagent 矩阵 (CC 端)

stage × rules 注入矩阵

注入方式: stage 切换时, 主 agent 显式 Read ~/.claude/rules/<file>.md 后进入下一步.

stage × 工具矩阵 (v9.6.2 新, 关键补丁)

每个 stage 进入时, 主 agent 首先读 .ai_state/_index.md.tools_available, 然后按下表选工具. 注意: 工具的可用性由 athena-init 探测填入 _index.md, 不要假设.

工具决策步骤 (主 agent 进入每个 stage 时)

1. Read .ai_state/_index.md
2. 解析 tools_available 字段
3. 按当前 stage 的优先级表, 选第一个可用的工具
4. 若工具不可用 (例如 context7_cli=false 且需要 ctx7) → 降级到下一优先级
5. 若全部不可用 → 主 agent 自己处理 (无 fan-out, 无外包)

何时主动告知用户

• 检测到 tools_available 中某关键工具 false, 但任务能从该工具受益 → 主 agent 提示用户 "建议安装 X, 一行命令: ..."
• 任务从 antigravity 受益但 ag_callable=false → 提示 "建议安装 agy: curl -fsSL https://antigravity.google/cli/install.sh | bash"
• 任务从 context7 受益但 context7_cli=false → 提示 "建议安装: npm i -g @upstash/context7-mcp"

关键 invariants

1. 每个 path 的 stage 序列固定 (上面矩阵决定)
2. review VERDICT = FAIL → 不能进 polish 或 ship, 必须回 impl
3. Refactor/System 强制 polish (delivery-gate hook 拦截, 缺 cleanup-pass-N.md 直接 exit 2)
4. stage 字段实时同步到 _index.md.stage (每次切换都 Write)
5. frontmatter 字段 _index.md:
   • version: "9.6.2"
   • path: 6 路径之一
   • stage: 6 stage 之一
   • current_sprint: 数字 (default 1)
   • pointers.latest_cleanup: details/cleanup-pass-N.md (Refactor/System 后填)
   • fingerprint: 由 index-updater hook 维护
   • counts: { features, reviews, cleanups }

完整工作流: System 路径示例

# Step 1: 路由确认
路径 = System (跨模块改动 + 数据层影响)
stage = plan

# Step 2: plan stage
主 agent 写 design.md 需求段
stage 切换 plan → design

# Step 3: design stage
主 agent spawn Task subagent_type: generator (但作为 "architect" 角色使用)
    or
CC 端模拟 architect: 主 agent 自己产出 File Structure Plan + 风险 + 验收
注入: ~/.claude/rules/coding-standards.md + ui-guidelines.md
stage 切换 design → impl

# Step 4: impl stage
主 agent spawn Task subagent_type: generator (TDD)
注入: coding-standards + ui-guidelines + security-checklist
所有 Task GREEN → stage 切换 impl → review

# Step 5: review stage (review_pass1)
主 agent spawn Task subagent_type: reviewer (findings)
主 agent spawn Task subagent_type: evaluator (VERDICT)
注入: 全部 5 个 rules
若 VERDICT = PASS / CONCERNS → stage 切换 review → polish

# Step 6: polish stage (System 路径强制)
主 agent 加载 /polish skill
执行 5 检查项 → 写 cleanup-pass-{sprint}.md
注入: doc-style + coding-standards
stage 切换 polish → ship

# Step 7: ship stage
主 agent 跑 lint + test
主 agent git add + git commit (按 git-conventions)
注入: git-conventions
stage = ship 完成 → delivery-gate hook 放行

与 Codex 端的对应

CX 端等价矩阵在 ~/.agents/skills/pace/SKILL.md (cx 版), 用 spawn_agent 调用对应 .toml subagent. 详见 cx 端文档.

例外与降级

• 若 _index.md.skip_polish = true (项目级 opt-out): polish stage 跳过, 写空 cleanup-pass.md 标 "skipped: explicit opt-out"
• 若 spawn subagent 失败 ≥ 3 次: 主 agent 降级到自己执行 (不再 spawn), 但仍按规则注入
• 若 review VERDICT = FAIL: 回 impl, 重新走 impl → review 循环, 不进 polish/ship