pi-ccg: Instructions file for Claude Code

CCG for Pi CLI

Last Updated: 2026-08-25 (v3.2.8)

当前架构为 Pi-only。历史变更见 CHANGELOG.md。

项目定位

CCG 为 Pi CLI 提供动态、有上限的智能开发工作流。Pi 是唯一 supervisor，不再由 Claude 主控，也不再通过 Codex/Gemini wrapper 充当固定外部角色。

标准流程：

ccg-project-scout
→ ccg-planner
→ supervisor contract relay + START approval
→ Pi 动态 builder fanout（N frontend + M backend，按 component/profile/wave）
→ builder FINISH handoff
→ ccg-test-runner
→ ccg-reviewer
→ componentId 定向修复（最多 2 轮）

六个 Pi role templates

Role template	责任
ccg-project-scout	只读项目/组件发现
ccg-planner	组件拆分、文件边界、ownership、依赖、waves、测试计划
ccg-backend-builder	通用后端、服务、API、数据与基础设施组件
ccg-frontend-builder	通用前端组件；Web、管理后台、小程序/微信等通过 componentProfile 区分
ccg-test-runner	测试、typecheck、lint、build
ccg-reviewer	独立正确性、质量、安全审查

ccg-miniprogram-builder 已退休，不属于当前 active runtime。小程序/微信只作为 frontend componentProfile，由通用 ccg-frontend-builder 实例处理。

模型映射：

frontendModel → generic ccg-frontend-builder instances
backendModel  → generic ccg-backend-builder instances
reviewModel   → ccg-reviewer + ccg-test-runner
scout/planner → Pi subagents.defaultModel

动态 fanout 上限

effectiveDevParallelism = min(
  devAgentCap,
  globalConcurrencyLimit,
  parallel.concurrency,
  parallel.maxTasks
)

requiredSpawns = 2 + (N_frontend + M_backend) + 1 + 1

默认：

devAgentCap = 4
globalConcurrencyLimit = 4
maxSpawnsPerSession = 24
maxSubagentDepth = 1

所有 CCG agents 使用 defaultContext: fresh；supervisor 以 context: "fresh" 调用。跨 run 的 plan/build/test context 必须内联进 task string，不能依赖另一个 run 的相对 reads。

Supervisor 协调规则

• ccg-planner 输出稳定 componentId、component/profile、文件 ownership、依赖 waves、测试计划和修复路由。
• Pi supervisor 在 builder 写入前 relay contract，并等待 supervisor START approval。
• Pi 按 wave 派生 builder 实例；同一 wave 的有效并发不得超过 caps。
• 每个 builder 只修改自己 ownership 范围内的文件；跨组件变更必须回报 supervisor。
• 每个 builder 完成时必须返回 FINISH handoff，包含 componentId、变更文件、验证、假设和风险。
• test-runner/reviewer 的失败必须携带 componentId，供 Pi 定向回派 owning builder。
• componentId 定向修复最多两轮。