ccgx-workflow 1.0.0

package/templates/commands/spec-init.md

@@ -0,0 +1,101 @@
+---
+description: '初始化 OpenSpec (OPSX) 环境 + 验证多模型 MCP 工具'
+---
+<!-- CCG:SPEC:INIT:START -->
+**Core Philosophy**
+- OPSX provides the specification framework; CCG adds multi-model collaboration.
+- This phase ensures all tools are ready before any development work begins.
+- Fail fast: detect missing dependencies early rather than mid-workflow.
+
+**Guardrails**
+- Detect OS (Linux/macOS/Windows) and adapt commands accordingly.
+- Do not proceed to next step until current step completes successfully.
+- Provide clear, actionable error messages when a step fails.
+- Respect user's existing configurations; avoid overwriting without confirmation.
+
+**Steps**
+1. **Detect Operating System**
+   - Identify OS using `uname -s` (Unix) or environment variables (Windows).
+   - Inform user which OS was detected.
+
+2. **Check and Install OpenSpec (OPSX)**
+   - **IMPORTANT**: OpenSpec CLI command is `openspec`, NOT `opsx`
+   - Verify if OpenSpec is available:
+     ```bash
+     npx @fission-ai/openspec --version
+     ```
+   - If not found, install globally:
+     ```bash
+     npm install -g @fission-ai/openspec@latest
+     ```
+   - After installation, verify again:
+     ```bash
+     openspec --version
+     ```
+   - If `openspec` command not found after global install, use `npx`:
+     ```bash
+     npx @fission-ai/openspec --version
+     ```
+   - **Note**: Always use `openspec` (not `opsx`) for CLI commands.
+
+3. **Initialize OPSX for Current Project**
+   - **重要**：所有命令必须在当前工作目录下执行，禁止 `cd` 到其他路径。如不确定当前目录，先执行 `pwd` 确认。
+   - Check if already initialized:
+     ```bash
+     ls -la openspec/ .claude/skills/openspec-* 2>/dev/null || echo "Not initialized"
+     ```
+   - If not initialized, run interactive setup (v1.2+ auto-detects AI tools):
+     ```bash
+     npx @fission-ai/openspec init
+     ```
+   - **Profile Selection** (v1.2+):
+     - `core` profile (default): 4 essential workflows (`propose`, `explore`, `apply`, `archive`)
+     - `custom` profile: Pick any subset of workflows
+     - To change profile later: `openspec config profile`
+   - Verify initialization:
+     - Check `openspec/` directory exists
+     - Check `.claude/skills/` contains `openspec-*` skills
+     - Check `.claude/commands/opsx/` contains OPSX commands
+   - Report any errors with remediation steps.
+
+4. **Validate Multi-Model MCP Tools**
+   - Check `codeagent-wrapper` availability: `~/.claude/bin/codeagent-wrapper --version`
+   - **工作目录**：`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区，先确定任务相关的工作区。
+   - Test {{BACKEND_PRIMARY}} backend:
+     ```bash
+     echo "echo test" | ~/.claude/bin/codeagent-wrapper --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- "{{WORKDIR}}"
+     ```
+   - Test {{FRONTEND_PRIMARY}} backend:
+     ```bash
+     echo "echo test" | ~/.claude/bin/codeagent-wrapper --backend {{FRONTEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- "{{WORKDIR}}"
+     ```
+   - For each unavailable tool, display warning with installation instructions.
+
+5. **Summary Report**
+   Display status table:
+   ```
+   Component                 Status
+   ─────────────────────────────────
+   OpenSpec (OPSX) CLI       ✓/✗
+   Project initialized       ✓/✗
+   OPSX Skills               ✓/✗
+   codeagent-wrapper         ✓/✗
+   {{BACKEND_PRIMARY}} backend             ✓/✗
+   {{FRONTEND_PRIMARY}} backend            ✓/✗
+   ```
+
+   **Next Steps (Use CCG Encapsulated Commands)**
+   1. Start Research: `/ccg:spec-research "description"`
+   2. Plan & Design: `/ccg:spec-plan`
+   3. Implement: `/ccg:spec-impl` (Includes auto-review & archive)
+
+   **Standalone Tools (Available Anytime)**
+   - Code Review: `/ccg:spec-review` (Independent dual-model review)
+
+**Reference**
+- OpenSpec (OPSX) CLI: `npx @fission-ai/openspec --help`
+- Profile Management: `openspec config profile`
+- CCG Workflow: `npx ccg-workflow`
+- 后端/前端模型 MCP: Bundled with codeagent-wrapper
+- Node.js >= 18.x required for OpenSpec
+<!-- CCG:SPEC:INIT:END -->

package/templates/commands/spec-plan.md

@@ -0,0 +1,210 @@
+---
+description: '多模型分析 → 消除歧义 → 零决策可执行计划'
+---
+<!-- CCG:SPEC:PLAN:START -->
+**Core Philosophy**
+- The goal is to eliminate ALL decision points—implementation should be pure mechanical execution.
+- Every ambiguity must be resolved into explicit constraints before proceeding.
+- Multi-model collaboration surfaces blind spots and conflicting assumptions.
+- Every requirement must have Property-Based Testing (PBT) properties—focus on invariants.
+
+**Guardrails**
+- Do not proceed to implementation until every ambiguity is resolved.
+- Multi-model collaboration is **mandatory**: use both {{BACKEND_PRIMARY}} and {{FRONTEND_PRIMARY}}.
+- If constraints cannot be fully specified, escalate to user or return to research phase.
+- Refer to `openspec/config.yaml` for project conventions.
+- **USER GUIDANCE RULE**: When suggesting next steps to the user, ALWAYS use CCG commands (`/ccg:spec-research`, `/ccg:spec-plan`, `/ccg:spec-impl`, `/ccg:spec-review`). NEVER suggest `/opsx:*` commands to the user. If OpenSpec CLI returns error messages referencing OPSX skills, translate them to CCG equivalents.
+- **TASKS FORMAT RULE**: When generating or modifying `tasks.md`, ALL tasks MUST use checkbox format (`- [ ] X.Y description`). Heading+bullet format will cause OpenSpec CLI to parse 0 tasks and block the workflow.
+- **PHASE BOUNDARY**: This phase ONLY generates OPSX artifacts (specs.md, design.md, tasks.md). Do NOT modify any source code. Do NOT proceed to implementation. After artifacts are generated, STOP and inform the user: "Plan complete. Run `/ccg:spec-impl` to start implementation."
+
+**Steps**
+1. **Select Change**
+   - Run `openspec list --json` to display Active Changes.
+   - Confirm with user which change ID to refine.
+   - Run `openspec status --change "<change_id>" --json` to review current state.
+
+2. **Multi-Model Implementation Analysis (PARALLEL)**
+   - **CRITICAL**: You MUST launch BOTH {{BACKEND_PRIMARY}} AND {{FRONTEND_PRIMARY}} in a SINGLE message with TWO Bash tool calls.
+   - **DO NOT** call one model first and wait. Launch BOTH simultaneously with `run_in_background: true`.
+   - **工作目录**：`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区，先确定任务相关的工作区。
+
+   **Step 2.1**: In ONE message, make TWO parallel Bash calls:
+
+   **FIRST Bash call ({{BACKEND_PRIMARY}})**:
+   ```
+   Bash({
+     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nAnalyze change <change_id> from backend perspective:\n- Implementation approach\n- Technical risks\n- Alternative architectures\n- Edge cases and failure modes\nOUTPUT: JSON with analysis\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "{{BACKEND_PRIMARY}}: backend analysis"
+   })
+   ```
+
+   **SECOND Bash call ({{FRONTEND_PRIMARY}}) - IN THE SAME MESSAGE**:
+   ```
+   Bash({
+     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{FRONTEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nAnalyze change <change_id> from frontend/integration perspective:\n- Maintainability assessment\n- Scalability considerations\n- Integration conflicts\nOUTPUT: JSON with analysis\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "{{FRONTEND_PRIMARY}}: frontend analysis"
+   })
+   ```
+
+   **Step 2.2 (v4.5.2 事件驱动)**: spawn 两个 Bash bg 后说明 task-id 然后 **turn end**。引擎在每个 task 完成时自动发 `<task-notification>`，主线在通知触发的新 turn 处理结果。**不调 TaskOutput**。两个 task 都收到通知后才进 step 2.3。
+
+   ⛔ **禁止**：调 `TaskOutput({block: true, timeout: 600000})` (旧 freeze poll 模式) / Kill task。
+   ⚠️ **失败处理**：notification status=failed / exit ≠ 0 / parse 失败 → v1.7.87 标准 2-retry / 5s / 3-attempts；3 次全失败才降级单模型。
+
+   - Synthesize responses and present consolidated options to user.
+
+3. **Uncertainty Elimination Audit**
+   - **{{BACKEND_PRIMARY}}**: "Review proposal for unspecified decision points. List each as: [AMBIGUITY] → [REQUIRED CONSTRAINT]"
+   - **{{FRONTEND_PRIMARY}}**: "Identify implicit assumptions. Specify: [ASSUMPTION] → [EXPLICIT CONSTRAINT NEEDED]"
+
+   **Anti-Pattern Detection** (flag and reject):
+   - Information collection without decision boundaries
+   - Technical comparisons without selection criteria
+   - Deferred decisions marked "to be determined during implementation"
+
+   **Target Pattern** (required for approval):
+   - Explicit technology choices with parameters (e.g., "JWT with TTL=15min")
+   - Concrete algorithm selections with configs (e.g., "bcrypt cost=12")
+   - Precise behavioral rules (e.g., "Lock account 30min after 5 failed attempts")
+
+   Iterate with user until ALL ambiguities resolved.
+
+4. **PBT Property Extraction**
+   - **{{BACKEND_PRIMARY}}**: "Extract PBT properties. For each requirement: [INVARIANT] → [FALSIFICATION STRATEGY]"
+   - **{{FRONTEND_PRIMARY}}**: "Define system properties: [PROPERTY] | [DEFINITION] | [BOUNDARY CONDITIONS] | [COUNTEREXAMPLE GENERATION]"
+
+   **Property Categories**:
+   - **Commutativity/Associativity**: Order-independent operations
+   - **Idempotency**: Repeated operations yield same result
+   - **Round-trip**: Encode→Decode returns original
+   - **Invariant Preservation**: State constraints maintained
+   - **Monotonicity**: Ordering guarantees (e.g., timestamps increase)
+   - **Bounds**: Value ranges, size limits, rate constraints
+
+4.5. **Scope Reduction Detection（范围缩水检测，BLOCKER 级）**
+
+   **这是 plan-checker 维度 7b 的等价扫描，移植自 GSD 真实事故反推（D-26：动态成本引用被静态硬编码 v1）。**
+
+   在生成 OPSX artifacts 之前，对当前规划文本（多模型分析结果 + 即将写入 tasks.md 的内容）做软化语言扫描：
+
+   **扫描关键词集合**（中英双语，大小写不敏感）：
+   - 阶段拆分类：`v1 简化` / `v1 静态` / `v1 硬编码` / `simplified version` / `static for now` / `static first`
+   - 推迟类：`future enhancement` / `未来增强` / `后续连接` / `will be wired later` / `not connected to`
+   - 占位类：`placeholder` / `占位符` / `占位实现` / `暂时硬编码` / `temporary hardcode`
+   - 知难而退类：`太复杂` / `太困难` / `too complex` / `too difficult` / `too hard`
+
+   **关键设计：与原始需求对比，避免合理 v1 渐进交付误报**
+
+   命中关键词后必须交叉对比，**不**直接阻断：
+
+   1. 抽取命中行的领域名词（如 `billing`, `cost reference`）
+   2. 与 OPSX `proposal.md` / `requirements.md` / 用户在 Step 1 选定的 change ID 对应需求做对比
+   3. 判决：
+
+   | 命中关键词 + 该能力在原始需求中存在 | plan 是否显式分阶段（v2/phase 2/增量交付被规划） | 判决 |
+   |-------------------------------------|--------------------------------------------------|------|
+   | ✅ 是 | ❌ 无 | **🔴 BLOCKER**（用户决策被缩水） |
+   | ✅ 是 | ✅ 有 | **NONE**（合理渐进，放行） |
+   | ❌ 否 | — | **🟡 WARNING**（人工确认） |
+
+   **BLOCKER 永远是 BLOCKER——不接受 warning 降级。** 命中 BLOCKER 时停止生成 artifacts，向用户输出：
+
+   ```
+   🔴 SCOPE REDUCTION BLOCKER
+   - 命中关键词：<keyword>
+   - 原文：<line>
+   - 对应需求：<requirement>
+   - 选项：
+     1. 完整实施该需求（重新规划，不再缩水）
+     2. 拆分阶段：把 v2 phase 显式列入计划（写入下一个 OPSX change，不能口头承诺）
+   ```
+
+   只有 BLOCKER 数量为 0 时才进入 Step 5。
+
+5. **Update OPSX Artifacts** (then auto plan-checker)
+   - **BEFORE calling `/opsx:continue`** (internal skill call — do NOT expose this command to user), output a structured summary for OPSX context:
+     ```markdown
+     ## Planning Summary for OPSX
+
+     **Multi-Model Analysis Results**:
+     - {{BACKEND_PRIMARY}} (Backend): [Key findings and recommendations]
+     - {{FRONTEND_PRIMARY}} (Frontend): [Key findings and recommendations]
+     - Consolidated Approach: [Selected implementation strategy]
+
+     **Resolved Constraints**:
+     - [All explicit constraints from Step 3]
+
+     **PBT Properties**:
+     - [All extracted properties from Step 4 with falsification strategies]
+
+     **Technical Decisions**:
+     - [All finalized technology choices, algorithms, configurations]
+
+     **Implementation Tasks**:
+     - [High-level task breakdown ready for tasks.md]
+     ```
+
+   - Then call `/opsx:continue` internally to generate next artifacts:
+     ```
+     /opsx:continue
+     ```
+   - The OPSX skill will use the above summary to create specs.md, design.md, and tasks.md.
+   - **Note**: This is an internal call. If this step fails, guide the user to re-run `/ccg:spec-plan`.
+   - **STOP**: After artifacts are generated, verify they exist and inform user:
+     "Plan phase complete. Artifacts generated: specs.md, design.md, tasks.md. Run `/ccg:spec-impl` to start implementation."
+     Do NOT proceed to modify source code.
+
+5.5. **自动 plan-checker 校验（5 维度 + max-3-loop，CCG v4.0 Phase 6）**
+
+   生成 OPSX artifacts 后，**必须**自动 spawn `plan-checker` agent 对 specs.md / design.md / tasks.md 做 5 维度校验：
+
+   ```
+   Agent({
+     subagent_type: "plan-checker",
+     description: "Validate OPSX plan artifacts (Dim 1/2/5/7b/10)",
+     prompt: "请对 openspec/changes/<change_id>/ 下的 specs.md / design.md / tasks.md 做 5 维度强校验：\n- Dim 1: Requirement Coverage（每条需求 ID 被某 plan/spec 声明）\n- Dim 2: Task Completeness（tasks.md 每条 task 含 Files/Action/Verify/Done）\n- Dim 5: Scope Sanity（≤3 tasks/plan）\n- Dim 7b: Scope Reduction（与 proposal.md 原始需求交叉对比）\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  # ✅ 通过
+       # 退回 planner 修订（仅针对 BLOCKER）
+       回到 Step 5 重新调用 /opsx:continue 修订 specs/design/tasks
+       loop_count += 1
+
+   if loop_count == 3 and result.hasBlocker:
+       AskUserQuestion:
+           prompt:  "plan-checker 3 轮仍存在 BLOCKER，请选择："
+           options: ["force: 忽略 BLOCKER 强制进入实施", "guide: 提供具体指导让 planner 再试", "abort: 放弃当前 plan"]
+   ```
+
+   只有 plan-checker ✅ 放行 后才进入下一步（Context Checkpoint）。
+
+6. **Context Checkpoint**
+   - Report current context usage.
+   - If approaching 80K tokens, suggest: "Run `/clear` and continue with `/ccg:spec-impl`"
+
+**Exit Criteria**
+A change is ready for implementation only when:
+- [ ] All multi-model analyses completed and synthesized
+- [ ] Zero ambiguities remain (verified by step 3 audit)
+- [ ] All PBT properties documented with falsification strategies
+- [ ] Artifacts (specs, design, tasks) generated via OpenSpec skills
+- [ ] User has explicitly approved all constraint decisions
+
+**Reference**
+- Inspect change: `openspec status --change "<id>" --json`
+- List changes: `openspec list --json`
+- Search patterns: `rg -n "INVARIANT:|PROPERTY:" openspec/`
+- Use `AskUserQuestion` for ANY ambiguity—never assume
+<!-- CCG:SPEC:PLAN:END -->

package/templates/commands/spec-research.md

@@ -0,0 +1,152 @@
+---
+description: '需求 → 约束集（并行探索 + OPSX 提案）'
+---
+<!-- CCG:SPEC:RESEARCH:START -->
+**Core Philosophy**
+- Research produces **constraint sets**, not information dumps. Each constraint narrows the solution space.
+- Constraints tell subsequent stages "don't consider this direction," enabling mechanical execution without decisions.
+- Output: 约束集合 + 可验证的成功判据 (constraint sets + verifiable success criteria).
+- Strictly adhere to OPSX rules when writing spec-structured documents.
+
+**Guardrails**
+- **STOP! BEFORE ANY OTHER ACTION**: You MUST perform Prompt Enhancement FIRST. This is NON-NEGOTIABLE.
+- **NEVER** divide subagent tasks by roles (e.g., "架构师agent", "安全专家agent").
+- **ALWAYS** divide by context boundaries (e.g., "user-related code", "authentication logic").
+- Each subagent context must be self-contained with independent output.
+- Use `{{MCP_SEARCH_TOOL}}` to minimize grep/find operations.
+- Do not make architectural decisions—surface constraints that guide decisions.
+- **USER GUIDANCE RULE**: When suggesting next steps to the user, ALWAYS use CCG commands (`/ccg:spec-research`, `/ccg:spec-plan`, `/ccg:spec-impl`, `/ccg:spec-review`). NEVER suggest `/opsx:*` commands to the user. If OpenSpec CLI returns error messages referencing OPSX skills, translate them to CCG equivalents.
+- **PHASE BOUNDARY**: This phase ONLY generates the OPSX proposal artifact. Do NOT modify any source code. Do NOT proceed to planning or implementation. After the proposal is generated, STOP and inform the user: "Research complete. Run `/ccg:spec-plan` to continue."
+
+**Steps**
+0. **MANDATORY: Enhance Requirement FIRST**
+   - **DO THIS IMMEDIATELY. DO NOT SKIP.**
+   - **Prompt 增强**（按 `/ccg:enhance` 的逻辑执行）：分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准）。
+   - Use enhanced prompt for ALL subsequent steps.
+
+1. **Generate OPSX Change**
+   - Check if change already exists:
+     ```bash
+     openspec list --json
+     ```
+   - If change doesn't exist, create it:
+     ```bash
+     openspec new change "<brief-descriptive-name>"
+     ```
+   - This scaffolds `openspec/changes/<name>/` with proposal.md.
+   - If change already exists, continue with existing change.
+
+2. **Initial Codebase Assessment**
+   - Use `{{MCP_SEARCH_TOOL}}` to scan codebase.
+   - Determine project scale: single vs multi-directory structure.
+   - **Decision**: If multi-directory → enable parallel Explore subagents.
+
+3. **Define Exploration Boundaries (Context-Based)**
+   - Identify natural context boundaries (NOT functional roles):
+     * Subagent 1: User domain code (models, services, UI)
+     * Subagent 2: Auth & authorization (middleware, session, tokens)
+     * Subagent 3: Infrastructure (configs, deployments, builds)
+   - Each boundary should be self-contained: no cross-communication needed.
+
+4. **Parallel Multi-Model Exploration**
+   - **CRITICAL**: You MUST launch BOTH {{BACKEND_PRIMARY}} AND {{FRONTEND_PRIMARY}} in a SINGLE message with TWO Bash tool calls.
+   - **DO NOT** call one model first and wait. Launch BOTH simultaneously with `run_in_background: true`.
+   - **工作目录**：`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区，先确定任务相关的工作区。
+
+   **Output Template** (instruct both models to use this format):
+   ```json
+   {
+     "module_name": "context boundary explored",
+     "existing_structures": ["key patterns found"],
+     "existing_conventions": ["standards in use"],
+     "constraints_discovered": ["hard constraints limiting solution space"],
+     "open_questions": ["ambiguities requiring user input"],
+     "dependencies": ["cross-module dependencies"],
+     "risks": ["potential blockers"],
+     "success_criteria_hints": ["observable success behaviors"]
+   }
+   ```
+
+   **Step 4.1**: In ONE message, make TWO parallel Bash calls:
+
+   **FIRST Bash call ({{BACKEND_PRIMARY}} — backend boundaries)**:
+   ```
+   Bash({
+     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nExplore backend context boundaries for <change description>:\n- Existing structures and patterns\n- Conventions in use\n- Hard constraints limiting solution space\n- Dependencies and risks\nOUTPUT: JSON using the output template above\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "{{BACKEND_PRIMARY}}: backend boundary exploration"
+   })
+   ```
+
+   **SECOND Bash call ({{FRONTEND_PRIMARY}} — frontend boundaries) - IN THE SAME MESSAGE**:
+   ```
+   Bash({
+     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{FRONTEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nExplore frontend context boundaries for <change description>:\n- Existing structures and patterns\n- Conventions in use\n- Hard constraints limiting solution space\n- Dependencies and risks\nOUTPUT: JSON using the output template above\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "{{FRONTEND_PRIMARY}}: frontend boundary exploration"
+   })
+   ```
+
+   **Step 4.2 (v4.5.2 事件驱动)**: spawn 两个 Bash bg 后说明 task-id 然后 **turn end**。引擎在每个 task 完成时自动发 `<task-notification>`，主线在通知触发的新 turn 处理结果。**不调 TaskOutput**。两个 task 都收到通知后才进 step 4.3。
+
+   ⛔ **禁止**：调 `TaskOutput({block: true, timeout: 600000})` (旧 freeze poll 模式) / Kill task。
+   ⚠️ **失败处理**：notification status=failed / exit ≠ 0 / parse 失败 → v1.7.87 标准 2-retry / 5s / 3-attempts；3 次全失败才降级单模型。
+
+5. **Aggregate and Synthesize**
+   - Collect all subagent outputs.
+   - Merge into unified constraint sets:
+     * **Hard constraints**: Technical limitations, patterns that cannot be violated
+     * **Soft constraints**: Conventions, preferences, style guides
+     * **Dependencies**: Cross-module relationships affecting implementation order
+     * **Risks**: Blockers needing mitigation
+
+6. **User Interaction for Ambiguity Resolution**
+   - Compile prioritized list of open questions.
+   - Use `AskUserQuestion` tool to present systematically:
+     * Group related questions
+     * Provide context for each
+     * Suggest defaults when applicable
+   - Capture responses as additional constraints.
+
+7. **Finalize OPSX Proposal**
+   - **BEFORE calling `/opsx:continue`** (internal skill call — do NOT expose this command to user), output a structured summary for OPSX context:
+     ```markdown
+     ## Research Summary for OPSX
+
+     **Discovered Constraints**:
+     - [List all hard and soft constraints from Step 5]
+
+     **Dependencies**:
+     - [List cross-module dependencies]
+
+     **Risks & Mitigations**:
+     - [List identified risks and mitigation strategies]
+
+     **Success Criteria**:
+     - [List verifiable success behaviors]
+
+     **User Confirmations**:
+     - [List all user decisions from Step 6]
+     ```
+
+   - Then call `/opsx:continue` internally to generate proposal artifact:
+     ```
+     /opsx:continue
+     ```
+   - The OPSX skill will use the above summary to write proposal.md.
+   - **Note**: This is an internal call. If this step fails, guide the user to re-run `/ccg:spec-research`.
+   - **STOP**: After proposal is generated, verify it exists and inform user:
+     "Research phase complete. Proposal generated. Run `/ccg:spec-plan` to continue planning."
+     Do NOT proceed to planning or implementation.
+
+8. **Context Checkpoint**
+   - Report current context usage.
+   - If approaching 80K tokens, suggest: "Run `/clear` and continue with `/ccg:spec-plan`"
+
+**Reference**
+- OPSX CLI: `openspec status --change "<id>" --json`, `openspec list --json`
+- Check prior research: `ls openspec/changes/*/`
+- Use `AskUserQuestion` for ANY ambiguity—never assume or guess
+<!-- CCG:SPEC:RESEARCH:END -->

package/templates/commands/spec-review.md

@@ -0,0 +1,120 @@
+---
+description: '双模型交叉审查（独立工具，随时可用）'
+---
+<!-- CCG:SPEC:REVIEW:START -->
+**Core Philosophy**
+- Dual-model cross-validation catches blind spots single-model review would miss.
+- Critical findings SHOULD be addressed before proceeding.
+- Review validates implementation against spec constraints and code quality.
+- This is an independent review tool—can be used anytime, not tied to archive workflow.
+
+**Guardrails**
+- **MANDATORY**: Both {{BACKEND_PRIMARY}} AND {{FRONTEND_PRIMARY}} must complete review before synthesis.
+- Review scope is strictly limited to the proposal's changes—no scope creep.
+- Refer to `openspec/config.yaml` for project conventions when reviewing OpenSpec proposals.
+
+**Steps**
+1. **Select Proposal**
+   - Run `openspec list --json` to display Active Changes.
+   - Confirm with user which proposal ID to review.
+   - Run `openspec status --change "<proposal_id>" --json` to load spec and tasks.
+
+2. **Collect Implementation Artifacts**
+   - Identify all files modified by this proposal.
+   - Use `git diff` to get change summary.
+   - Load relevant spec constraints and PBT properties from `openspec/changes/<id>/specs/`.
+
+3. **Multi-Model Review (PARALLEL)**
+   - **CRITICAL**: You MUST launch BOTH {{BACKEND_PRIMARY}} AND {{FRONTEND_PRIMARY}} in a SINGLE message with TWO Bash tool calls.
+   - **DO NOT** call one model first and wait. Launch BOTH simultaneously with `run_in_background: true`.
+   - **工作目录**：`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`（Unix）或 `cd`（Windows CMD）获取当前工作目录的绝对路径**，禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区，先确定任务相关的工作区。
+
+   **Step 3.1**: In ONE message, make TWO parallel Bash calls:
+
+   **FIRST Bash call ({{BACKEND_PRIMARY}})**:
+   ```
+   Bash({
+     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{BACKEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nReview proposal <proposal_id> implementation:\n\n## {{BACKEND_PRIMARY}} Review Dimensions\n1. **Spec Compliance**: Verify ALL constraints from spec are satisfied\n2. **PBT Properties**: Check invariants, idempotency, bounds are correctly implemented\n3. **Logic Correctness**: Edge cases, error handling, algorithm correctness\n4. **Backend Security**: Injection vulnerabilities, auth checks, input validation\n5. **Regression Risk**: Interface compatibility, type safety, breaking changes\n\n## Output Format (JSON)\n{\n  \"findings\": [\n    {\n      \"severity\": \"Critical|Warning|Info\",\n      \"dimension\": \"spec_compliance|pbt|logic|security|regression\",\n      \"file\": \"path/to/file.ts\",\n      \"line\": 42,\n      \"description\": \"What is wrong\",\n      \"constraint_violated\": \"Constraint ID from spec (if applicable)\",\n      \"fix_suggestion\": \"How to fix\"\n    }\n  ],\n  \"passed_checks\": [\"List of verified constraints/properties\"],\n  \"summary\": \"Overall assessment\"\n}\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "{{BACKEND_PRIMARY}}: backend/logic review"
+   })
+   ```
+
+   **SECOND Bash call ({{FRONTEND_PRIMARY}}) - IN THE SAME MESSAGE**:
+   ```
+   Bash({
+     command: "~/.claude/bin/codeagent-wrapper --progress --backend {{FRONTEND_PRIMARY}} {{GEMINI_MODEL_FLAG}}- \"{{WORKDIR}}\" <<'EOF'\nReview proposal <proposal_id> implementation:\n\n## {{FRONTEND_PRIMARY}} Review Dimensions\n1. **Pattern Consistency**: Naming conventions, code style, project patterns\n2. **Maintainability**: Readability, complexity, documentation adequacy\n3. **Integration Risk**: Dependency changes, cross-module impacts\n4. **Frontend Security**: XSS, CSRF, sensitive data exposure\n5. **Spec Alignment**: Implementation matches spec intent (not just letter)\n\n## Output Format (JSON)\n{\n  \"findings\": [\n    {\n      \"severity\": \"Critical|Warning|Info\",\n      \"dimension\": \"patterns|maintainability|integration|security|alignment\",\n      \"file\": \"path/to/file.ts\",\n      \"line\": 42,\n      \"description\": \"What is wrong\",\n      \"spec_reference\": \"Spec section (if applicable)\",\n      \"fix_suggestion\": \"How to fix\"\n    }\n  ],\n  \"passed_checks\": [\"List of verified aspects\"],\n  \"summary\": \"Overall assessment\"\n}\nEOF",
+     run_in_background: true,
+     timeout: 300000,
+     description: "{{FRONTEND_PRIMARY}}: patterns/integration review"
+   })
+   ```
+
+   **Step 3.2 (v4.5.2 事件驱动)**: spawn 两个 Bash bg 后说明 task-id 然后 **turn end**。引擎在每个 task 完成时自动发 `<task-notification>`，主线在通知触发的新 turn 处理结果。**不调 TaskOutput**。两个 task 都收到通知后才进 step 3.3。
+
+   ⛔ **禁止**：调 `TaskOutput({block: true, timeout: 600000})` (旧 freeze poll 模式) / Kill task。
+   ⚠️ **失败处理**：notification status=failed / exit ≠ 0 / parse 失败 → v1.7.87 标准 2-retry / 5s / 3-attempts；3 次全失败才降级单模型。
+
+4. **Synthesize Findings**
+   - Merge findings from both models.
+   - Deduplicate overlapping issues.
+   - Classify by severity:
+     * **Critical**: Spec violation, security vulnerability, breaking change → MUST fix
+     * **Warning**: Pattern deviation, maintainability concern → SHOULD fix
+     * **Info**: Minor improvement suggestion → MAY fix
+
+5. **Present Review Report**
+   - Display findings grouped by severity:
+   ```
+   ## Review Report: <proposal_id>
+
+   ### Critical (X issues) - MUST FIX
+   - [ ] [SPEC] file.ts:42 - Constraint X violated: description
+   - [ ] [SEC] api.ts:15 - SQL injection vulnerability
+
+   ### Warning (Y issues) - SHOULD FIX
+   - [ ] [PATTERN] utils.ts:88 - Inconsistent naming convention
+
+   ### Info (Z issues) - MAY FIX
+   - [ ] [MAINT] helper.ts:20 - Consider extracting to separate function
+
+   ### Passed Checks
+   - ✅ PBT: Idempotency property verified
+   - ✅ Security: No XSS vulnerabilities found
+   ```
+
+6. **Decision Gate**
+   - **If Critical > 0**:
+     * Present findings to user.
+     * Ask: "Fix now or return to `/ccg:spec-impl` to address?"
+     * Do NOT allow archiving.
+
+   - **If Critical = 0**:
+     * Ask user: "All critical checks passed. Proceed to archive?"
+     * If Warning > 0, recommend addressing before archive.
+
+7. **Optional: Inline Fix Mode**
+   - If user chooses "Fix now" for Critical issues:
+     * Route each fix to appropriate model (backend→{{BACKEND_PRIMARY}}, frontend→{{FRONTEND_PRIMARY}}).
+     * Apply fix using unified diff patch pattern.
+     * Re-run affected review dimension.
+     * Repeat until Critical = 0.
+
+8. **Context Checkpoint**
+   - Report current context usage.
+   - If approaching 80K tokens, suggest: "Run `/clear` and continue with `/ccg:spec-review` or `/ccg:spec-impl`"
+
+**Exit Criteria**
+Review is complete when:
+- [ ] Both {{BACKEND_PRIMARY}} and {{FRONTEND_PRIMARY}} reviews completed
+- [ ] All findings synthesized and classified
+- [ ] Zero Critical issues remain (fixed or user-acknowledged)
+- [ ] User decision captured (archive / return to impl / defer)
+
+**Reference**
+- View proposal: `openspec status --change "<id>" --json`
+- Check spec constraints: `rg -n "CONSTRAINT:|MUST|INVARIANT:" openspec/changes/<id>/specs/`
+- View implementation diff: `git diff`
+- Archive (after passing): `/ccg:spec-impl` → Step 10
+<!-- CCG:SPEC:REVIEW:END -->