spec-plan

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}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_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}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_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: After BOTH Bash calls return task IDs, wait for results with TWO TaskOutput calls:

   TaskOutput({ task_id: "<codex_task_id>", block: true, timeout: 600000 })
   TaskOutput({ task_id: "<gemini_task_id>", block: true, timeout: 600000 })
   

   ⛔ 前端模型失败必须重试：若前端模型调用失败，最多重试 2 次（间隔 5 秒）。3 次全败才跳过。 ⛔ 后端模型结果必须等待：后端模型执行 5-15 分钟属正常，超时后继续轮询，禁止跳过。

   • 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]"