spec-review

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}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_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}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_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"
   })