coding-workflow

5 阶段编码工作流编排（spec → plan → dev → test → pr），自动 Gate Pipeline + Workflow 驱动 Review-Gate + Test-Fix Loop + Retrospect + Compact。

功能

• Gate Pipeline：可配置的 gate 链，按 phase 配置执行（review-gate → phase-gate）
• Workflow 驱动 Review-Gate：Phase 1/2/3 通过 Workflow Extension 的 agent()/parallel() 执行循环审查 + 自动修复
• Test-Fix Loop：Phase 4 的 core/noncore 串行测试修复循环（最多 10 轮 + 增量策略）
• 降级策略：Workflow Extension 缺失时自动降级到 runSingleAgent 串行执行
• Goal 自动注入：Phase 2 硬编码 L1 任务，Phase 3 从 plan.md 动态构建
• Retrospect 上下文注入：gate 通过后 steer 包含关键交付物摘要
• Compact：阶段切换时自动压缩上下文
• 配套 skills：内置 xyz-harness 全套技能（brainstorming、writing-plans、phase-dev、phase-test 等）
• 配套 agents：11 个专用 agent（reviewer / fix-worker / coordinator）

安装

# npm 方式（正式）
pi install npm:@zhushanwen/pi-coding-workflow

# 可选：workflow extension（启用并行审查能力）
pi install npm:@zhushanwen/pi-workflow

使用

通过 coding-workflow-gate 和 coding-workflow-phase-start 工具由 AI 自动调度，或手动使用命令：

| 命令 | 说明 | |------|------| | /coding-workflow | 启动工作流 | | /coding-workflow-status | 查看当前状态 | | /coding-workflow-abort | 中止工作流 |

Gate Pipeline 架构

每个 phase 声明自己的 gate 链配置：

| Phase | Gates | 说明 | |-------|-------|------| | 1 (Spec) | review-gate → phase-gate | Workflow 循环审查 spec.md | | 2 (Plan) | review-gate → phase-gate | L1 单 agent / L2 串行双 agent | | 3 (Dev) | review-gate → phase-gate | 三阶段：conformance → simulated-data → review-fix loop | | 4 (Test) | test-fix-loop → phase-gate | core → noncore 串行，各 10 轮 | | 5 (PR) | phase-gate | 仅脚本检查 |

Review-Gate Workflow（Phase 1/2/3）

通过 pi.__workflowRun 启动 .pi/workflows/phase{N}-review-gate.js：

• Phase 1：单 agent 循环审查 spec.md，最多 3 轮
• Phase 2：L1 单 agent / L2 串行双 agent（plan + BL review），最多 3 轮
• Phase 3：三阶段嵌套（conformance → simulated-data → 5 reviewer 并行 + fix-worker）

Test-Fix Loop（Phase 4）

通过 pi.__workflowRun 启动 .pi/workflows/phase4-test-fix-loop.js：

• 核心 case 先执行（最多 10 轮），全部 passed 后执行非核心 case
• 增量策略：第 2 轮起只重跑 fixed + depends_on 下游
• Stagnation 检查：连续 3 轮 failed 不降 → 强制退出

文件结构

coding-workflow/
├── index.ts                # 入口 — 工具、命令、事件注册
├── lib/
│   ├── gates/              # Gate Pipeline 抽象
│   │   ├── gate.ts         # Gate/GateContext/GateResult 接口
│   │   ├── review-gate.ts  # Review-Gate（workflow 驱动 + 降级）
│   │   ├── phase-gate.ts   # Phase-Gate（脚本检查）
│   │   └── test-fix-loop.ts # Test-Fix Loop Gate（workflow 驱动 + 降级）
│   ├── gate-runner.ts      # 门控脚本执行
│   ├── helpers.ts          # PhaseConfig + 辅助函数
│   ├── process-manager.ts  # 子进程管理
│   ├── review-dispatcher.ts# Anti-fraud review + Retrospect steer（含上下文注入）
│   ├── review-gate-impl.ts # runSingleAgent 降级实现
│   ├── skill-resolver.ts   # Skill 发现
│   ├── subagent.ts         # Subagent 工具封装
│   └── render-helpers.ts   # TUI 渲染
├── agents/                 # 专用 agent（reviewer / fix-worker / coordinator）
├── skills/                 # xyz-harness 全套 skills
├── scripts/
│   └── gate-check.py       # 门控检查 Python 脚本
└── commands/               # 命令模板

Agent 文件

| Agent | Phase | 职责 | |-------|-------|------| | spec-requirements-reviewer | 1 | 审查 spec.md 完整性、一致性、清晰度 | | plan-requirements-reviewer | 2 | 审查 plan.md 可行性、交付物完整性（L1/L2 共用） | | plan-bl-requirements-reviewer | 2 | L2 业务逻辑覆盖度审查 | | spec-plan-conformance-reviewer | 3 | 规格符合性 + 业务逻辑审查 | | simulated-data-generator | 3 | 生成 JSON fixture 模拟数据 | | fallow-reviewer | 3 | 包装 fallow CLI 的代码质量审查 | | review-sync-fix-worker | 3 | 汇总 reviewer + 判断退出 + 按文件分组 | | file-fix-subagent | 3 | 串行修复同一文件的所有 must_fix | | test-execute-coordinator | 4 | 构造 test-execute JSON、分派 Wave | | test-fix-worker | 4 | 分析失败 + 修复 + 更新状态 | | test-case-subagent | 4 | 执行测试 case、更新结果 |

降级策略

Workflow Extension（@zhushanwen/pi-workflow）是可选依赖：

| 状态 | Review-Gate | Test-Fix Loop | |------|------------|---------------| | 已安装 | pi.__workflowRun 驱动 workflow 脚本 | pi.__workflowRun 驱动 workflow 脚本 | | 未安装 | runSingleAgent 串行审查 | runSingleAgent 串行测试修复 |