ccgx-workflow 1.0.0

package/templates/commands/plan.md

@@ -0,0 +1,373 @@
+---
+description: '多模型协作规划 - 上下文检索 + 双模型分析 → 生成 Step-by-step 实施计划'
+argument-hint: "<规划任务> [--role=architect|critic|implementer|tester|writer]"
+---
+
+# Plan - 多模型协作规划
+
+$ARGUMENTS
+
+---
+
+## Role-based routing（v4.1 specialist matrix）
+
+可选参数 `--role=<name>` 在 v4.0 的 backend/frontend layer 路由之上叠加 **role 维度**，自动选择更精准的 prompt 文件。**未传 `--role` 时按现状路由（{{BACKEND_PRIMARY}}/{{FRONTEND_PRIMARY}}），完全保留 v4.0 行为兼容**——无破坏性变更。
+
+**Role × Layer 路由矩阵**：
+
+| Role × Layer  | architect      | critic              | implementer | tester        | writer          |
+| ------------- | -------------- | ------------------- | ----------- | ------------- | --------------- |
+| **backend**   | codex (architect.md) | codex (reviewer.md, adversarial) | codex (architect.md) | codex (tester.md) | claude（主线）  |
+| **frontend**  | gemini (architect.md) | gemini (reviewer.md, adversarial) | gemini (architect.md) | gemini (tester.md) | gemini (analyzer.md) |
+| **fullstack** | codex+gemini (architect.md) | both debate (reviewer.md, adversarial) | runner 决（per-file） | runner 决（per-file） | claude（主线） |
+
+**判定流程**：
+
+1. **解析 layer**：根据 $ARGUMENTS 涉及文件类型推断 `backend` / `frontend` / `fullstack`（与 v4.0 现有逻辑一致）。
+2. **解析 role**：从 $ARGUMENTS 提取 `--role=<name>`（5 个合法值：`architect` / `critic` / `implementer` / `tester` / `writer`），不存在或非法值 → fallback v4.0 模型路由。
+3. **选 prompt 文件**：按矩阵查 `(role, layer)` 单元格 → ROLE_FILE 路径。
+4. **adversarial 标记**：role=critic 时，prompt 段额外注入 "deliberately hunt for flaws / contradict majority view" 指令，触发敌对审查模式。
+5. **runner 决**：fullstack × {implementer, tester} 时，per-file 选 codex 或 gemini（同 v4.0 phase-runner Type 路由逻辑）。
+
+**示例**：
+
+- `/ccg:plan 设计 OAuth2 流程 --role=architect` → 后端，调用 `~/.claude/.ccg/prompts/codex/architect.md`
+- `/ccg:plan 检查 H5 适配方案 --role=critic` → 前端，调用 `~/.claude/.ccg/prompts/gemini/reviewer.md` + adversarial 框架
+- `/ccg:plan 全栈支付改造 --role=critic` → fullstack debate，并行 codex+gemini 两边都跑 reviewer.md + adversarial
+- `/ccg:plan 生成发版说明 --role=writer` → 主线 Claude 直接处理，不 spawn 外部模型
+
+**单一真相源**：完整矩阵以 `src/utils/specialist-router.ts` 为准，单测 `src/utils/__tests__/specialistMatrix.test.ts` 锁定行为。
+
+---
+
+## 核心协议
+
+- **语言协议**：与工具/模型交互用**英语**，与用户交互用**中文**
+- **强制并行**：后端/前端模型调用必须使用 `run_in_background: true`（包含单模型调用，避免阻塞主线程）
+- **代码主权**：外部模型对文件系统**零写入权限**，所有修改由 Claude 执行
+- **止损机制**：当前阶段输出通过验证前，不进入下一阶段
+- **仅规划**：本命令允许读取上下文与写入 `.claude/plan/*` 计划文件，但**禁止修改产品代码**
+
+---
+
+## 调用通道路由（v4.1 Phase 20，CCG codeagent 退役）
+
+CCG v4.1 把 6 核心命令的"双模型并行"通道从 `Bash(codeagent-wrapper)` **默认切换**为 plugin spawn。判定流程：
+
+1. **优先 plugin spawn 路径**（默认）：用户已装 `codex@openai-codex` 和 `gemini@google-gemini` plugin → 用 `Agent(subagent_type="codex:codex-rescue")` + `Agent(subagent_type="gemini:gemini-rescue")` 并行 spawn，主线只接 plugin 自家 ≤200 token 摘要协议（`STATUS: ... / FINDINGS: ... / NOTES: ...`）。
+2. **降级 codeagent-wrapper 路径**（v4.0 BC fallback）：plugin 未装 → fallback 到 `Bash(~/.claude/bin/codeagent-wrapper --backend ... resume ... <<'EOF' ... EOF)`，与 v4.0 行为完全一致。
+
+**判断方法**：preflight 用 `Bash` 跑 `ls ~/.claude/plugins/ 2>/dev/null | grep -E '^codex@'` 与 `... | grep -E '^gemini@'` 各一次。匹配到对应行 → plugin 已装。两个 plugin 独立判定，可分别 mix-and-match（仅 codex plugin 装了 → backend 走 plugin、frontend 走 codeagent）。
+
+**单一真相源**：plugin 检测逻辑 helper 见 `src/utils/plugin-detection.ts`（导出 `detectPlugin` / `detectPluginAvailability` / `bothPluginsInstalled`）。命令模板把判定结果渲染到执行计划，`Agent(...)` 调用与 `Bash(...)` 调用的具体语法见下面"多模型调用规范"段。
+
+**为什么默认 plugin**：v4.0.1 nested-spawn 测试证明 plugin advisor 摘要协议（≤200 token）压制了 codeagent stdout 全文回灌主线的痛点，主线 context 增量从 +5%/调用 降到 +1.5%/调用。详见 `.ccg-research/07-multimodel-collaboration-rethink.md`。
+
+⚠️ **重要**：本命令本身不在 subagent context 内（主线命令），**可以**调 `Agent(...)` 工具——这跟 `phase-runner` 等 subagent 的"引擎层禁止嵌套 spawn Agent"约束不冲突。
+
+---
+
+## 多模型调用规范
+
+**工作目录**：
+- `{{WORKDIR}}`：**必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断
+- 如果用户通过 `/add-dir` 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
+- 如果无法确定，用 `AskUserQuestion` 询问用户选择目标工作区
+
+**调用语法**（v4.1 Phase 20 双通道）：
+
+**通道 A — plugin spawn（默认）**：
+
+```
+Agent({
+  subagent_type: "<codex:codex-rescue|gemini:gemini-rescue>",
+  description: "Plan analysis: <backend|frontend>",
+  prompt: `ROLE_FILE: <角色提示词路径>
+
+<TASK>
+需求：<增强后的需求>
+上下文：<检索到的项目上下文>
+</TASK>
+
+OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
+Return ≤200 token structured summary (plugin-native protocol).
+`
+})
+```
+
+并行**两个 Agent 在同一 message 内同时 spawn**，主线接 plugin 摘要后无需 `TaskOutput` 轮询。
+
+**通道 B — codeagent-wrapper fallback**（plugin 未装时降级，并行用 `run_in_background: true`）：
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend <{{BACKEND_PRIMARY}}|{{FRONTEND_PRIMARY}}> {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'
+ROLE_FILE: <角色提示词路径>
+<TASK>
+需求：<增强后的需求>
+上下文：<检索到的项目上下文>
+</TASK>
+OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "简短描述"
+})
+```
+
+> ⚠️ 通道 B 走 `codeagent-wrapper`（Node 脚本 `templates/scripts/invoke-model.mjs`），v4.1 已标 **deprecated**，将在 v5.0 移除。建议用户安装 codex/gemini plugin 享受 v4.1 主线 context 优化。
+
+**角色提示词**：
+
+| 阶段 | 后端 | 前端 |
+|------|-------|--------|
+| 分析 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md` |
+| 规划 | `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md` | `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md` |
+
+**会话复用**：每次调用返回 `SESSION_ID: xxx`（通常由 wrapper 输出），**必须保存**以供后续 `/ccg:execute` 使用。
+
+**事件驱动等待（v4.5.2 起）**：spawn 后主线说明 task-id 然后 **turn end**，引擎自动 `<task-notification>` 触发新 turn 处理结果。**不调 TaskOutput**。
+
+⛔ **禁止**：调 `TaskOutput({block: true, timeout: 600000})` 旧 freeze poll 模式 / Kill task。
+
+⚠️ **失败处理**：notification status=failed / exit ≠ 0 / parse 失败 → v1.7.87 标准 2-retry / 5s / 3-attempts；3 次全失败才降级单模型。
+
+---
+
+## 执行工作流
+
+**规划任务**：$ARGUMENTS
+
+### 🔍 Phase 1：上下文全量检索
+
+`[模式：研究]`
+
+#### 1.1 Prompt 增强（必须首先执行）
+
+**Prompt 增强**（按 `/ccg:enhance` 的逻辑执行）：分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准），**用增强结果替代原始 $ARGUMENTS** 用于后续所有阶段。
+
+#### 1.2 上下文检索
+
+**调用 `{{MCP_SEARCH_TOOL}}` 工具**：
+
+```
+{{MCP_SEARCH_TOOL}}({
+  query: "<基于增强后需求构建的语义查询>",
+  project_root_path: "{{WORKDIR}}"
+})
+```
+
+- 使用自然语言构建语义查询（Where/What/How）
+- **禁止基于假设回答**
+- 若 MCP 不可用：回退到 Glob + Grep 进行文件发现与关键符号定位
+
+#### 1.3 完整性检查
+
+- 必须获取相关类、函数、变量的**完整定义与签名**
+- 若上下文不足，触发**递归检索**
+- 优先输出：入口文件 + 行号 + 关键符号名；必要时补充最小代码片段（仅用于消除歧义）
+
+#### 1.4 需求对齐
+
+- 若需求仍有模糊空间，**必须**向用户输出引导性问题列表
+- 直至需求边界清晰（无遗漏、无冗余）
+
+### 💡 Phase 2：多模型协作分析
+
+`[模式：分析]`
+
+#### 2.1 分发输入
+
+**并行调用** {{BACKEND_PRIMARY}} 和 {{FRONTEND_PRIMARY}}（`run_in_background: true`）：
+
+将**原始需求**（不带预设观点）分发给两个模型：
+
+1. **{{BACKEND_PRIMARY}} 后端分析**：
+   - ROLE_FILE: `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/analyzer.md`
+   - 关注：技术可行性、架构影响、性能考量、潜在风险
+   - OUTPUT: 多角度解决方案 + 优劣势分析
+
+2. **{{FRONTEND_PRIMARY}} 前端分析**：
+   - ROLE_FILE: `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/analyzer.md`
+   - 关注：UI/UX 影响、用户体验、视觉设计
+   - OUTPUT: 多角度解决方案 + 优劣势分析
+
+事件驱动等待 (v4.5.2)：spawn 完两个 Bash bg 后主线 turn end，等 task-notification 自动唤醒。**📌 保存 SESSION_ID**（`CODEX_SESSION` 和 `GEMINI_SESSION`）。
+
+#### 2.2 交叉验证
+
+整合各方思路，进行迭代优化：
+
+1. **识别一致观点**（强信号）
+2. **识别分歧点**（需权衡）
+3. **互补优势**：后端逻辑以 {{BACKEND_PRIMARY}} 为准，前端设计以 {{FRONTEND_PRIMARY}} 为准
+4. **逻辑推演**：消除方案中的逻辑漏洞
+
+#### 2.3（可选但推荐）双模型产出“计划草案”
+
+为降低 Claude 合成计划的遗漏风险，可并行让两个模型输出“计划草案”（仍然**不允许**修改文件）：
+
+1. **{{BACKEND_PRIMARY}} 计划草案**（后端权威）：
+   - ROLE_FILE: `~/.claude/.ccg/prompts/{{BACKEND_PRIMARY}}/architect.md`
+   - OUTPUT: Step-by-step plan + pseudo-code（重点：数据流/边界条件/错误处理/测试策略）
+
+2. **{{FRONTEND_PRIMARY}} 计划草案**（前端权威）：
+   - ROLE_FILE: `~/.claude/.ccg/prompts/{{FRONTEND_PRIMARY}}/architect.md`
+   - OUTPUT: Step-by-step plan + pseudo-code（重点：信息架构/交互/可访问性/视觉一致性）
+
+用 `TaskOutput` 等待两个模型的完整结果，并记录其建议的关键差异点。
+
+#### 2.4 生成实施计划（Claude 最终版）
+
+综合双方分析，生成 **Step-by-step 实施计划**：
+
+```markdown
+## 📋 实施计划：<任务名称>
+
+### 任务类型
+- [ ] 前端 (→ {{FRONTEND_PRIMARY}})
+- [ ] 后端 (→ {{BACKEND_PRIMARY}})
+- [ ] 全栈 (→ 并行)
+
+### 技术方案
+<综合双模型分析的最优方案>
+
+### 实施步骤
+1. <步骤 1> - 预期产物
+2. <步骤 2> - 预期产物
+...
+
+### 关键文件
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| path/to/file.ts:L10-L50 | 修改 | 描述 |
+
+### 风险与缓解
+| 风险 | 缓解措施 |
+|------|----------|
+
+### SESSION_ID（供 /ccg:execute 使用）
+- CODEX_SESSION: <session_id>
+- GEMINI_SESSION: <session_id>
+```
+
+### 🛡 Phase 2.5：自动 plan-checker 校验（5 维度 + max-3-loop，CCG v4.0 Phase 6）
+
+写出 `.claude/plan/<功能名>.md` 后、向用户交付前，**必须**自动 spawn `plan-checker` agent 做 5 维度强校验：
+
+```
+Agent({
+  subagent_type: "plan-checker",
+  description: "Validate plan (Dim 1/2/5/7b/10)",
+  prompt: "请对 .claude/plan/<功能名>.md 做 5 维度强校验：\n- Dim 1: Requirement Coverage（roadmap requirement 是否在 plan frontmatter 声明）\n- Dim 2: Task Completeness（每 task 含 Files/Action/Verify/Done）\n- Dim 5: Scope Sanity（≤3 tasks）\n- Dim 7b: Scope Reduction（关键词扫描 + 原始需求交叉）\n- Dim 10: CLAUDE.md Compliance（不违反项目 CLAUDE.md 禁用模式）\n输出 Plan Checker Report 并给出 ✅ 放行 / ❌ 退回 verdict。"
+})
+```
+
+**max-3-loop 收敛环**：
+
+```
+loop_count = 0
+while loop_count < 3:
+    result = spawn plan-checker
+    if not result.hasBlocker:
+        break  # ✅ 放行，进入交付
+    # 退回——回 Phase 2.4 修订计划（仅针对 BLOCKER 的反馈，不要顺手改其他段）
+    重新生成 .claude/plan/<功能名>.md
+    loop_count += 1
+
+if loop_count == 3 and result.hasBlocker:
+    AskUserQuestion:
+        prompt:  "plan-checker 3 轮仍存在 BLOCKER，请选择："
+        options: ["force: 忽略 BLOCKER 强制交付（高风险）", "guide: 提供具体指导让规划再试一次", "abort: 放弃当前规划"]
+```
+
+只有 plan-checker ✅ 放行（或用户选 force）后才进入计划交付。
+
+### ⛔ Phase 3 结束：计划交付（非执行）
+
+**`/ccg:plan` 的职责到此结束，必须执行以下动作**：
+
+1. 向用户展示完整实施计划（含伪代码）+ plan-checker 报告摘要（BLOCKER/WARNING 数量 + verdict）
+2. 将计划保存至 `.claude/plan/<功能名>.md`（功能名从需求中提取，如 `user-auth`、`payment-module` 等）
+3. **写 phase-scoped CONTEXT.md**（v4.0 Phase 2 状态机）：把本次 plan 的冻结决策固化到 `.context/<phase>/CONTEXT.md`，下游 `/ccg:execute` 与 `/ccg:team-exec` 仅读此文件的 YAML frontmatter 即可获得全部决策（< 200 tokens / phase）。**目录约定**：`<phase>` 取计划文件主名（如 `user-auth`），用 `sanitizePhase()` 规范化非法字符。
+
+   **CONTEXT.md 必含 frontmatter 字段（机器可读契约）**：
+   ```yaml
+   ---
+   phase: user-auth
+   plan: .claude/plan/user-auth.md
+   goal: <一句话目标>
+   decisions: [<决策1>, <决策2>, ...]
+   constraints: [<约束1>, <约束2>, ...]
+   files: [<关键文件1>, <关键文件2>, ...]
+   created_at: <ISO8601 时间>
+   ---
+   ```
+
+   写入由主线 `Bash` 调用完成（节点脚本 / 直接 Write 工具均可），路径 = `<WORKDIR>/.context/<phase>/CONTEXT.md`，目录不存在自动创建。**写完立即进入下一步，不阻塞**。
+
+4. 以**加粗文本**输出提示（必须使用实际保存的文件路径）：
+
+   ---
+   **📋 计划已生成并保存至 `.claude/plan/实际功能名.md`**
+
+   **请审查上述计划，您可以：**
+   - 🔧 **修改计划**：告诉我需要调整的部分，我会更新计划
+   - ▶️ **执行计划**：复制以下命令到新会话执行
+
+   ```
+   /ccg:execute .claude/plan/实际功能名.md
+   ```
+   ---
+
+   **⚠️ 注意**：上面的 `实际功能名.md` 必须替换为你实际保存的文件名！
+
+5. **立即终止当前回复**（Stop here. No more tool calls.）
+
+**⚠️ 绝对禁止**：
+- ❌ 问用户 "Y/N" 然后自动执行（执行是 `/ccg:execute` 的职责）
+- ❌ 对产品代码进行任何写操作
+- ❌ 自动调用 `/ccg:execute` 或任何实施动作
+- ❌ 在用户未明确要求修改时继续触发模型调用
+
+---
+
+## 计划保存
+
+规划完成后，将计划保存至：
+
+- **首次规划**：`.claude/plan/<功能名>.md`
+- **迭代版本**：`.claude/plan/<功能名>-v2.md`、`.claude/plan/<功能名>-v3.md`...
+
+计划文件写入应在向用户展示计划前完成。
+
+---
+
+## 计划修改流程
+
+如果用户要求修改计划：
+
+1. 根据用户反馈调整计划内容
+2. 更新 `.claude/plan/<功能名>.md` 文件
+3. 重新展示修改后的计划
+4. 再次提示用户审查或执行
+
+---
+
+## 后续步骤
+
+用户审查满意后，**手动**执行：
+
+```bash
+/ccg:execute .claude/plan/<功能名>.md
+```
+
+---
+
+## 关键规则
+
+1. **仅规划不实施** – 本命令不执行任何代码变更
+2. **不问 Y/N** – 只展示计划，让用户决定下一步
+3. **信任规则** – 后端以 {{BACKEND_PRIMARY}} 为准，前端以 {{FRONTEND_PRIMARY}} 为准
+4. 外部模型对文件系统**零写入权限**
+5. **SESSION_ID 交接** – 计划末尾必须包含 `CODEX_SESSION` / `GEMINI_SESSION`（供 `/ccg:execute resume <SESSION_ID>` 使用）

package/templates/commands/result.md

@@ -0,0 +1,106 @@
+---
+description: '取后台任务最终结果：读取 .context/jobs/<id>/result.md，输出 ≤ 200 token 摘要（v4.0 异步三件套）'
+argument-hint: "<job-id>"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Result - 取后台任务最终结果
+
+`/ccg:status` 看到 job 进入 `done` / `failed` / `canceled` 后，用本命令把 `.context/jobs/<id>/result.md` 内容拉回主线。
+
+result.md 的写入是后台子任务（codex:codex-rescue / phase-runner）退出前的最后动作，约定 ≤ 200 token，包含：
+
+```
+STATUS: completed | partial | failed | canceled
+COMMIT: <sha7> | none
+TESTS: <pass>/<total> passed (delta +<n> from <baseline>)
+TYPECHECK: pass | fail
+HANDOFF_TAKEN: [git_commit, test_run, ...]
+CONTEXT_DELTA: <一句话>
+NOTES: <一行>
+```
+
+## 使用方法
+
+```bash
+/ccg:result <job-id>          # 取该 job 的最终摘要
+```
+
+## 工作流程
+
+### Step 1：校验 job 状态
+
+1. Read `.context/jobs/<job-id>/state.json`
+2. 不存在 → 输出 "Job not found: <id>，run /ccg:status to list all jobs"，退出
+3. `status` ∈ `{queued, running}` → 输出：
+
+   ```
+   ⏳ Job <id> still <status>
+   Run /ccg:status <id> --wait --timeout-ms 60000 to wait, or /ccg:cancel <id> to abort.
+   ```
+
+   并退出（不强制等待）
+
+4. `status` ∈ `{done, failed, canceled}` → 进入 Step 2
+
+### Step 2：读取 result.md
+
+1. Read `.context/jobs/<job-id>/result.md`
+2. 不存在但 status 已是终态 → 输出：
+
+   ```
+   ⚠ Job <id> reached <status> but result.md is missing.
+   Possible cause: child task crashed before writing result. Inspect .context/jobs/<id>/state.json for last summary.
+   Last state summary: <state.summary>
+   ```
+
+3. 存在 → 进入 Step 3
+
+### Step 3：输出摘要 + 元信息
+
+1. 优先**直接打印** result.md 原文（已是 ≤ 200 token，无需 Claude 重新摘要）
+2. 末尾追加来自 state.json 的元信息：
+
+   ```
+   ──── Job metadata ────
+   Job-ID       : <id>
+   Kind         : <kind>
+   Phase        : <phase_id or '-'>
+   Started      : <started_at>
+   Ended        : <last_update>  (status=<status>)
+   Duration     : <last_update - started_at> 计算后人类可读
+   ```
+
+3. 若 status=failed/canceled，附加建议：
+   - failed → "建议：/ccg:status <id> 查看 state.summary，或重跑产生该 job 的命令"
+   - canceled → "已用户主动取消，若需重启请重新触发原命令"
+
+## 严格约束
+
+- ✅ **只读**——绝不修改任何文件
+- ✅ 不调用 LLM 二次摘要——result.md 已经压到 200 token，再压会丢失信号
+- ✅ 缺 result.md 时给出 actionable 提示（last_summary / 重跑建议）
+- ❌ 不在 status=running 时阻塞等待——这是 `/ccg:status --wait` 的职责
+- ❌ 不修改 state.json（即使 result.md 缺失）
+
+## 与其他命令的协作
+
+```
+/ccg:autonomous → spawn phase-runner job
+                ↓
+            writes .context/jobs/<id>/state.json (running)
+                ↓ (any time)
+            user: /ccg:status              ← 看进度
+            user: /ccg:status <id> --wait  ← 阻塞等终态
+                ↓ (eventually)
+            child writes result.md + state.json (done)
+                ↓
+            user: /ccg:result <id>         ← 取 200 token 摘要
+```
+
+## 实现锚点
+
+- `src/utils/jobs.ts` 的 `getJob / readJobResult` 是后端真相源
+- result.md 的 200 token 约定与 phase-runner 主线返回摘要约定一致（见 `templates/commands/agents/phase-runner.md` Phase G）