create-sdd-project 0.10.0 → 0.12.0

package/README.md

@@ -303,26 +303,29 @@ SDD DevFlow combines three proven practices:
 | `project-memory` | `set up project memory`, `log a bug fix` | Maintains institutional knowledge |
 | `health-check` | `health check`, `project health` | Quick scan: tests, build, specs sync, secrets, docs freshness |
 
-### 3 Custom Commands
+### 4 Custom Commands
 
 | Command | What it does |
 |---------|-------------|
-| `/review-plan` | Sends Implementation Plan to external AI models (Codex CLI, Gemini CLI) for independent critique |
+| `/review-spec` | Cross-model spec review — runs automatically after self-review when external CLIs are available; catches requirement gaps, ambiguity, and architectural inconsistencies |
+| `/review-plan` | Cross-model plan review — runs automatically after plan self-review when external CLIs are available; catches implementation blind spots |
 | `/context-prompt` | Generates a context recovery prompt after `/compact` with Workflow Recovery to prevent checkpoint skipping |
 | `/review-project` | Comprehensive project-level review using up to 3 AI models in parallel — 6 domains, audit context, consolidated report with action plan |
 
-### Plan Quality
+### Spec & Plan Quality
 
-Every Standard/Complex feature plan goes through a **built-in self-review** (Step 2.4) where the agent re-reads its own plan and checks for errors, vague steps, wrong assumptions, and over-engineering before requesting approval.
+Every Standard/Complex feature spec goes through a **built-in self-review** (Step 0.4) where the agent critically re-reads its own spec checking for completeness, edge cases, API contract clarity, and architectural consistency. Then `/review-spec` **automatically** sends the spec plus project context (`key_facts.md`, `decisions.md`) to external AI models for independent critique — catching requirement-level blind spots before any planning begins.
 
-For additional confidence, the optional `/review-plan` command sends the plan to external AI models (Codex CLI and/or Gemini CLI in parallel) for independent critique — catching blind spots that same-model review misses.
+Every plan then goes through its own **built-in self-review** (Step 2.4) followed by **automatic** `/review-plan` for external critique — catching implementation-level blind spots that same-model review misses.
+
+Cross-model reviews only trigger when at least one external CLI is available (Gemini CLI, Codex CLI). If no CLIs are detected, the step is skipped — the self-review is sufficient.
 
 ### Workflow (Steps 0–6)
 
 ```
-0. SPEC      → spec-creator drafts specs        → Spec Approval
-1. SETUP     → Branch, ticket, product tracker    → Ticket Approval
-2. PLAN      → Planner creates plan + self-review → Plan Approval
+0. SPEC      → spec-creator drafts + self-review + cross-model review → Spec Approval
+1. SETUP     → Branch, ticket, product tracker                       → Ticket Approval
+2. PLAN      → Planner creates plan + self-review + cross-model review → Plan Approval
 3. IMPLEMENT → Developer agent, TDD
 4. FINALIZE  → Tests/lint/build, validator       → Commit Approval
 5. REVIEW    → PR, code review, QA              → Merge Approval
@@ -421,6 +424,7 @@ project/
 │   │   ├── health-check/               # Project health diagnostics
 │   │   └── project-memory/              # Memory system setup
 │   ├── commands/                        # Custom slash commands
+│   │   ├── review-spec.md              # Cross-model spec review (pre-plan)
 │   │   ├── review-plan.md              # Cross-model plan review
 │   │   ├── context-prompt.md           # Post-compact context recovery
 │   │   └── review-project.md           # Multi-model project review

package/lib/config.js

@@ -106,6 +106,7 @@ const TEMPLATE_AGENTS = [
 // Template-provided command files (for upgrade: detect custom commands)
 const TEMPLATE_COMMANDS = [
   'review-plan.md',
+  'review-spec.md',
   'context-prompt.md',
   'review-project.md',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"

package/template/.claude/commands/review-plan.md

@@ -12,16 +12,18 @@ Review the Implementation Plan in the current ticket using external models for i
 2. **Detect available reviewers** — Check which external CLIs are installed:
 
 ```bash
-which gemini 2>/dev/null && echo "gemini: available" || echo "gemini: not found"
-which codex 2>/dev/null && echo "codex: available" || echo "codex: not found"
+command -v gemini >/dev/null 2>&1 && echo "gemini: available" || echo "gemini: not found"
+command -v codex >/dev/null 2>&1 && echo "codex: available" || echo "codex: not found"
 ```
 
 3. **Prepare the review input** — Extract the spec and plan into a temp file with the review prompt. Use the feature ID from the Active Session (e.g., `F023`):
 
 ```bash
-TICKET=$(ls docs/tickets/F023-*.md)  # Use the feature ID from Step 1
+TICKET="$(echo docs/tickets/F023-*.md)"  # Use the feature ID from Step 1; verify exactly one match
+REVIEW_DIR="/tmp/review-plan-$(basename "$PWD")"
+mkdir -p "$REVIEW_DIR"
 
-cat > /tmp/review-prompt.txt <<'CRITERIA'
+cat > "$REVIEW_DIR/input.txt" <<'CRITERIA'
 You are reviewing an Implementation Plan for a software feature. Your job is to find real problems, not praise. But if the plan is solid, say APPROVED — do not manufacture issues that are not there.
 
 Below you will find the Spec (what to build) and the Implementation Plan (how to build it). Review the plan and report:
@@ -39,7 +41,7 @@ End with: VERDICT: APPROVED | VERDICT: REVISE (if any CRITICAL or 2+ IMPORTANT i
 SPEC AND PLAN:
 CRITERIA
 
-sed -n '/## Spec/,/## Acceptance Criteria/p' "$TICKET" >> /tmp/review-prompt.txt
+sed -n '/^## Spec$/,/^## Acceptance Criteria$/p' "$TICKET" >> "$REVIEW_DIR/input.txt"
 ```
 
 4. **Send for review** — Execute **only one** of the following paths based on Step 2 results:
@@ -47,24 +49,28 @@ sed -n '/## Spec/,/## Acceptance Criteria/p' "$TICKET" >> /tmp/review-prompt.txt
 ### Path A: Both CLIs available (best — two independent perspectives)
 
 ```bash
-cat /tmp/review-prompt.txt | gemini > /tmp/review-gemini.txt 2>&1 &
-cat /tmp/review-prompt.txt | codex exec - > /tmp/review-codex.txt 2>&1 &
-wait
+cat "$REVIEW_DIR/input.txt" | gemini > "$REVIEW_DIR/gemini.txt" 2>&1 &
+PID_GEMINI=$!
+cat "$REVIEW_DIR/input.txt" | codex exec - > "$REVIEW_DIR/codex.txt" 2>&1 &
+PID_CODEX=$!
 
-echo "=== GEMINI REVIEW ===" && cat /tmp/review-gemini.txt
-echo "=== CODEX REVIEW ===" && cat /tmp/review-codex.txt
+wait $PID_GEMINI && echo "Gemini: OK" || echo "Gemini: FAILED (exit $?) — check $REVIEW_DIR/gemini.txt"
+wait $PID_CODEX && echo "Codex: OK" || echo "Codex: FAILED (exit $?) — check $REVIEW_DIR/codex.txt"
+
+echo "=== GEMINI REVIEW ===" && cat "$REVIEW_DIR/gemini.txt"
+echo "=== CODEX REVIEW ===" && cat "$REVIEW_DIR/codex.txt"
 ```
 
-Consolidate findings — issues flagged by both models independently carry higher weight. Deduplicate and prioritize.
+Consolidate findings — issues flagged by both models independently carry higher weight. Deduplicate and prioritize. Ignore output from any reviewer that failed.
 
 ### Path B: One CLI available
 
 ```bash
 # Gemini only
-cat /tmp/review-prompt.txt | gemini
+cat "$REVIEW_DIR/input.txt" | gemini
 
 # Codex only
-cat /tmp/review-prompt.txt | codex exec -
+cat "$REVIEW_DIR/input.txt" | codex exec -
 ```
 
 ### Path C: No external CLI available (self-review fallback)

package/template/.claude/commands/review-spec.md

@@ -0,0 +1,101 @@
+Review the Spec in the current ticket using external models for independent critique before planning.
+
+## Prerequisites
+
+- An active feature with a completed Spec (Step 0)
+- Ideally, one or more external AI CLIs installed: [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), or similar
+
+## What to do
+
+1. **Find the current ticket** — Read `docs/project_notes/product-tracker.md` → Active Session → ticket path
+
+2. **Detect available reviewers** — Check which external CLIs are installed:
+
+```bash
+command -v gemini >/dev/null 2>&1 && echo "gemini: available" || echo "gemini: not found"
+command -v codex >/dev/null 2>&1 && echo "codex: available" || echo "codex: not found"
+```
+
+3. **Prepare the review input** — Extract the spec, acceptance criteria, and project context into a temp file. Use the feature ID from the Active Session (e.g., `F023`):
+
+```bash
+TICKET="$(echo docs/tickets/F023-*.md)"  # Use the feature ID from Step 1; verify exactly one match
+REVIEW_DIR="/tmp/review-spec-$(basename "$PWD")"
+mkdir -p "$REVIEW_DIR"
+
+cat > "$REVIEW_DIR/input.txt" <<'CRITERIA'
+You are reviewing a Feature Specification for a software feature. Your job is to find real problems in the REQUIREMENTS — not the implementation (there is no implementation yet). If the spec is solid, say APPROVED — do not manufacture issues.
+
+Below you will find the Spec (what to build), the Acceptance Criteria, and project context (architecture, decisions). Review the spec and report:
+1. Completeness — Are all user needs covered? Missing requirements?
+2. Ambiguity — Are requirements clear enough to plan and implement with TDD?
+3. Edge cases — Are failure modes, boundary conditions, and error responses specified?
+4. API contract — Are endpoints, fields, types, status codes well-defined? (if applicable)
+5. Scope — Is the spec doing too much or too little for one feature?
+6. Consistency — Does the spec conflict with existing architecture, patterns, or decisions?
+7. Testability — Can each acceptance criterion be verified with an automated test?
+
+For each issue, state: [CRITICAL/IMPORTANT/SUGGESTION] — description — proposed fix.
+
+End with: VERDICT: APPROVED | VERDICT: REVISE (if any CRITICAL or 2+ IMPORTANT issues)
+
+---
+SPEC AND ACCEPTANCE CRITERIA:
+CRITERIA
+
+sed -n '/^## Spec$/,/^## Definition of Done$/p' "$TICKET" >> "$REVIEW_DIR/input.txt"
+
+echo -e "\n---\nPROJECT CONTEXT (architecture and decisions):\n" >> "$REVIEW_DIR/input.txt"
+cat docs/project_notes/key_facts.md >> "$REVIEW_DIR/input.txt" 2>/dev/null
+echo -e "\n---\n" >> "$REVIEW_DIR/input.txt"
+cat docs/project_notes/decisions.md >> "$REVIEW_DIR/input.txt" 2>/dev/null
+```
+
+4. **Send for review** — Execute **only one** of the following paths based on Step 2 results:
+
+### Path A: Both CLIs available (best — two independent perspectives)
+
+```bash
+cat "$REVIEW_DIR/input.txt" | gemini > "$REVIEW_DIR/gemini.txt" 2>&1 &
+PID_GEMINI=$!
+cat "$REVIEW_DIR/input.txt" | codex exec - > "$REVIEW_DIR/codex.txt" 2>&1 &
+PID_CODEX=$!
+
+wait $PID_GEMINI && echo "Gemini: OK" || echo "Gemini: FAILED (exit $?) — check $REVIEW_DIR/gemini.txt"
+wait $PID_CODEX && echo "Codex: OK" || echo "Codex: FAILED (exit $?) — check $REVIEW_DIR/codex.txt"
+
+echo "=== GEMINI REVIEW ===" && cat "$REVIEW_DIR/gemini.txt"
+echo "=== CODEX REVIEW ===" && cat "$REVIEW_DIR/codex.txt"
+```
+
+Consolidate findings — issues flagged by both models independently carry higher weight. Deduplicate and prioritize. Ignore output from any reviewer that failed.
+
+### Path B: One CLI available
+
+```bash
+# Gemini only
+cat "$REVIEW_DIR/input.txt" | gemini
+
+# Codex only
+cat "$REVIEW_DIR/input.txt" | codex exec -
+```
+
+### Path C: No external CLI available (self-review fallback)
+
+If no external CLI is installed, perform the review yourself. Re-read the full Spec from the ticket, then review it with this mindset:
+
+> You are an experienced engineer who has NOT seen this spec before. Question every assumption. Look for what is missing, ambiguous, or inconsistent with the project's architecture. Do not be lenient — find problems.
+
+Apply the same 7 criteria from the prompt above. For each issue, state severity, description, and proposed fix. End with VERDICT.
+
+5. **Process the review** — If any VERDICT is REVISE, update the spec addressing CRITICAL and IMPORTANT issues
+6. **Optional second round** — Send the revised spec for a final audit if significant changes were made
+7. **Log the review** — Add a note in the ticket's Completion Log: "Spec reviewed by [model(s) or self-review] — N issues found, N addressed"
+
+## Notes
+
+- This command is **optional** — the workflow's built-in Spec Self-Review (Step 0.4) always runs automatically
+- Most valuable for **Standard/Complex** features where a wrong spec leads to wasted planning and implementation effort
+- External models receive project context (key_facts + decisions) to check architectural consistency
+- Both CLIs use their latest default model when no `-m` flag is specified — no need to hardcode model names
+- Path C (self-review) is a last resort — external review gives genuinely independent perspectives that self-review cannot

package/template/.claude/skills/development-workflow/SKILL.md

@@ -70,6 +70,8 @@ Ask user to classify complexity before starting. See `references/complexity-guid
 1. Use Task tool with `spec-creator` agent
 2. Agent updates global spec files (`api-spec.yaml`, `ui-components.md`) and Zod schemas in `shared/src/schemas/` if applicable
 3. Agent writes spec summary into the ticket's `## Spec` section
+4. **Spec Self-Review:** Re-read the spec critically. Are requirements complete? Edge cases covered? API contract well-defined? Acceptance criteria testable? Does the spec conflict with existing architecture (`key_facts.md`, `decisions.md`)? Update the spec with any fixes found before proceeding.
+5. **Cross-Model Spec Review:** Run `/review-spec`. If at least one external CLI is available (`gemini`, `codex`), this provides independent validation from other models. If no external CLIs are detected, skip this step (the self-review above is sufficient).
 
 **→ CHECKPOINT: Spec Approval** — Update tracker (Active Session + Features table): step `0/6 (Spec)`
 
@@ -106,7 +108,8 @@ See `references/branching-strategy.md` for details.
    - Dependencies between steps that force a different order?
    - Over-engineering or unnecessary abstractions?
    Update the plan with any fixes found before proceeding.
-5. Update tracker: step `2/6 (Plan)` (Active Session + Features table)
+5. **Cross-Model Plan Review:** Run `/review-plan`. If at least one external CLI is available (`gemini`, `codex`), this provides independent validation from other models. If no external CLIs are detected, skip this step (the self-review above is sufficient).
+6. Update tracker: step `2/6 (Plan)` (Active Session + Features table)
 
 **→ CHECKPOINT: Plan Approval**
 

package/template/.gemini/commands/review-plan-instructions.md

@@ -14,16 +14,18 @@ Review the Implementation Plan in the current ticket using external models for i
 2. **Detect available reviewers** — Check which external CLIs are installed:
 
 ```bash
-which claude 2>/dev/null && echo "claude: available" || echo "claude: not found"
-which codex 2>/dev/null && echo "codex: available" || echo "codex: not found"
+command -v claude >/dev/null 2>&1 && echo "claude: available" || echo "claude: not found"
+command -v codex >/dev/null 2>&1 && echo "codex: available" || echo "codex: not found"
 ```
 
 3. **Prepare the review input** — Extract the spec and plan into a temp file with the review prompt. Use the feature ID from the Active Session (e.g., `F023`):
 
 ```bash
-TICKET=$(ls docs/tickets/F023-*.md)  # Use the feature ID from Step 1
+TICKET="$(echo docs/tickets/F023-*.md)"  # Use the feature ID from Step 1; verify exactly one match
+REVIEW_DIR="/tmp/review-plan-$(basename "$PWD")"
+mkdir -p "$REVIEW_DIR"
 
-cat > /tmp/review-prompt.txt <<'CRITERIA'
+cat > "$REVIEW_DIR/input.txt" <<'CRITERIA'
 You are reviewing an Implementation Plan for a software feature. Your job is to find real problems, not praise. But if the plan is solid, say APPROVED — do not manufacture issues that are not there.
 
 Below you will find the Spec (what to build) and the Implementation Plan (how to build it). Review the plan and report:
@@ -41,7 +43,7 @@ End with: VERDICT: APPROVED | VERDICT: REVISE (if any CRITICAL or 2+ IMPORTANT i
 SPEC AND PLAN:
 CRITERIA
 
-sed -n '/## Spec/,/## Acceptance Criteria/p' "$TICKET" >> /tmp/review-prompt.txt
+sed -n '/^## Spec$/,/^## Acceptance Criteria$/p' "$TICKET" >> "$REVIEW_DIR/input.txt"
 ```
 
 4. **Send for review** — Execute **only one** of the following paths based on Step 2 results:
@@ -49,24 +51,28 @@ sed -n '/## Spec/,/## Acceptance Criteria/p' "$TICKET" >> /tmp/review-prompt.txt
 #### Path A: Both CLIs available (best — two independent perspectives)
 
 ```bash
-cat /tmp/review-prompt.txt | claude --print > /tmp/review-claude.txt 2>&1 &
-cat /tmp/review-prompt.txt | codex exec - > /tmp/review-codex.txt 2>&1 &
-wait
+cat "$REVIEW_DIR/input.txt" | claude --print > "$REVIEW_DIR/claude.txt" 2>&1 &
+PID_CLAUDE=$!
+cat "$REVIEW_DIR/input.txt" | codex exec - > "$REVIEW_DIR/codex.txt" 2>&1 &
+PID_CODEX=$!
 
-echo "=== CLAUDE REVIEW ===" && cat /tmp/review-claude.txt
-echo "=== CODEX REVIEW ===" && cat /tmp/review-codex.txt
+wait $PID_CLAUDE && echo "Claude: OK" || echo "Claude: FAILED (exit $?) — check $REVIEW_DIR/claude.txt"
+wait $PID_CODEX && echo "Codex: OK" || echo "Codex: FAILED (exit $?) — check $REVIEW_DIR/codex.txt"
+
+echo "=== CLAUDE REVIEW ===" && cat "$REVIEW_DIR/claude.txt"
+echo "=== CODEX REVIEW ===" && cat "$REVIEW_DIR/codex.txt"
 ```
 
-Consolidate findings — issues flagged by both models independently carry higher weight. Deduplicate and prioritize.
+Consolidate findings — issues flagged by both models independently carry higher weight. Deduplicate and prioritize. Ignore output from any reviewer that failed.
 
 #### Path B: One CLI available
 
 ```bash
 # Claude only
-cat /tmp/review-prompt.txt | claude --print
+cat "$REVIEW_DIR/input.txt" | claude --print
 
 # Codex only
-cat /tmp/review-prompt.txt | codex exec -
+cat "$REVIEW_DIR/input.txt" | codex exec -
 ```
 
 #### Path C: No external CLI available (self-review fallback)

package/template/.gemini/commands/review-spec-instructions.md

@@ -0,0 +1,103 @@
+## Review Spec — Instructions
+
+Review the Spec in the current ticket using external models for independent critique before planning.
+
+### Prerequisites
+
+- An active feature with a completed Spec (Step 0)
+- Ideally, one or more external AI CLIs installed: Codex CLI, Claude Code, or similar
+
+### Steps
+
+1. **Find the current ticket** — Read `docs/project_notes/product-tracker.md` → Active Session → ticket path
+
+2. **Detect available reviewers** — Check which external CLIs are installed:
+
+```bash
+command -v claude >/dev/null 2>&1 && echo "claude: available" || echo "claude: not found"
+command -v codex >/dev/null 2>&1 && echo "codex: available" || echo "codex: not found"
+```
+
+3. **Prepare the review input** — Extract the spec, acceptance criteria, and project context into a temp file. Use the feature ID from the Active Session (e.g., `F023`):
+
+```bash
+TICKET="$(echo docs/tickets/F023-*.md)"  # Use the feature ID from Step 1; verify exactly one match
+REVIEW_DIR="/tmp/review-spec-$(basename "$PWD")"
+mkdir -p "$REVIEW_DIR"
+
+cat > "$REVIEW_DIR/input.txt" <<'CRITERIA'
+You are reviewing a Feature Specification for a software feature. Your job is to find real problems in the REQUIREMENTS — not the implementation (there is no implementation yet). If the spec is solid, say APPROVED — do not manufacture issues.
+
+Below you will find the Spec (what to build), the Acceptance Criteria, and project context (architecture, decisions). Review the spec and report:
+1. Completeness — Are all user needs covered? Missing requirements?
+2. Ambiguity — Are requirements clear enough to plan and implement with TDD?
+3. Edge cases — Are failure modes, boundary conditions, and error responses specified?
+4. API contract — Are endpoints, fields, types, status codes well-defined? (if applicable)
+5. Scope — Is the spec doing too much or too little for one feature?
+6. Consistency — Does the spec conflict with existing architecture, patterns, or decisions?
+7. Testability — Can each acceptance criterion be verified with an automated test?
+
+For each issue, state: [CRITICAL/IMPORTANT/SUGGESTION] — description — proposed fix.
+
+End with: VERDICT: APPROVED | VERDICT: REVISE (if any CRITICAL or 2+ IMPORTANT issues)
+
+---
+SPEC AND ACCEPTANCE CRITERIA:
+CRITERIA
+
+sed -n '/^## Spec$/,/^## Definition of Done$/p' "$TICKET" >> "$REVIEW_DIR/input.txt"
+
+echo -e "\n---\nPROJECT CONTEXT (architecture and decisions):\n" >> "$REVIEW_DIR/input.txt"
+cat docs/project_notes/key_facts.md >> "$REVIEW_DIR/input.txt" 2>/dev/null
+echo -e "\n---\n" >> "$REVIEW_DIR/input.txt"
+cat docs/project_notes/decisions.md >> "$REVIEW_DIR/input.txt" 2>/dev/null
+```
+
+4. **Send for review** — Execute **only one** of the following paths based on Step 2 results:
+
+#### Path A: Both CLIs available (best — two independent perspectives)
+
+```bash
+cat "$REVIEW_DIR/input.txt" | claude --print > "$REVIEW_DIR/claude.txt" 2>&1 &
+PID_CLAUDE=$!
+cat "$REVIEW_DIR/input.txt" | codex exec - > "$REVIEW_DIR/codex.txt" 2>&1 &
+PID_CODEX=$!
+
+wait $PID_CLAUDE && echo "Claude: OK" || echo "Claude: FAILED (exit $?) — check $REVIEW_DIR/claude.txt"
+wait $PID_CODEX && echo "Codex: OK" || echo "Codex: FAILED (exit $?) — check $REVIEW_DIR/codex.txt"
+
+echo "=== CLAUDE REVIEW ===" && cat "$REVIEW_DIR/claude.txt"
+echo "=== CODEX REVIEW ===" && cat "$REVIEW_DIR/codex.txt"
+```
+
+Consolidate findings — issues flagged by both models independently carry higher weight. Deduplicate and prioritize. Ignore output from any reviewer that failed.
+
+#### Path B: One CLI available
+
+```bash
+# Claude only
+cat "$REVIEW_DIR/input.txt" | claude --print
+
+# Codex only
+cat "$REVIEW_DIR/input.txt" | codex exec -
+```
+
+#### Path C: No external CLI available (self-review fallback)
+
+If no external CLI is installed, perform the review yourself. Re-read the full Spec from the ticket, then review it with this mindset:
+
+> You are an experienced engineer who has NOT seen this spec before. Question every assumption. Look for what is missing, ambiguous, or inconsistent with the project's architecture. Do not be lenient — find problems.
+
+Apply the same 7 criteria from the prompt above. For each issue, state severity, description, and proposed fix. End with VERDICT.
+
+5. **Process the review** — If any VERDICT is REVISE, update the spec addressing CRITICAL and IMPORTANT issues
+6. **Optional second round** — Send the revised spec for a final audit if significant changes were made
+7. **Log the review** — Add a note in the ticket's Completion Log: "Spec reviewed by [model(s) or self-review] — N issues found, N addressed"
+
+### Notes
+
+- This command is **optional** — the workflow's built-in Spec Self-Review (Step 0.4) always runs automatically
+- Most valuable for Standard/Complex features where a wrong spec leads to wasted planning and implementation effort
+- External models receive project context (key_facts + decisions) to check architectural consistency
+- Both CLIs use their latest default model when no `-m` flag is specified — no need to hardcode model names
+- Path C (self-review) is a last resort — external review gives genuinely independent perspectives that self-review cannot

package/template/.gemini/commands/review-spec.toml

@@ -0,0 +1,2 @@
+description = "Review the current Spec using an external AI model for independent critique before planning (optional, for Standard/Complex features)"
+prompt = "Read the file .gemini/commands/review-spec-instructions.md and follow the instructions to review the current Spec with an external model."

package/template/.gemini/skills/development-workflow/SKILL.md

@@ -70,6 +70,8 @@ Ask user to classify complexity before starting. See `references/complexity-guid
 1. Follow the instructions in `.gemini/agents/spec-creator.md`
 2. Update global spec files (`api-spec.yaml`, `ui-components.md`) and Zod schemas in `shared/src/schemas/` if applicable
 3. Write spec summary into the ticket's `## Spec` section
+4. **Spec Self-Review:** Re-read the spec critically. Are requirements complete? Edge cases covered? API contract well-defined? Acceptance criteria testable? Does the spec conflict with existing architecture (`key_facts.md`, `decisions.md`)? Update the spec with any fixes found before proceeding.
+5. **Cross-Model Spec Review:** Run `/review-spec`. If at least one external CLI is available (`claude`, `codex`), this provides independent validation from other models. If no external CLIs are detected, skip this step (the self-review above is sufficient).
 
 **→ CHECKPOINT: Spec Approval** — Update tracker (Active Session + Features table): step `0/6 (Spec)`
 
@@ -106,7 +108,8 @@ See `references/branching-strategy.md` for details.
    - Dependencies between steps that force a different order?
    - Over-engineering or unnecessary abstractions?
    Update the plan with any fixes found before proceeding.
-5. Update tracker: step `2/6 (Plan)` (Active Session + Features table)
+5. **Cross-Model Plan Review:** Run `/review-plan`. If at least one external CLI is available (`claude`, `codex`), this provides independent validation from other models. If no external CLIs are detected, skip this step (the self-review above is sufficient).
+6. Update tracker: step `2/6 (Plan)` (Active Session + Features table)
 
 **→ CHECKPOINT: Plan Approval**