create-sdd-project 0.9.1 → 0.9.3

package/README.md

@@ -302,12 +302,18 @@ SDD DevFlow combines three proven practices:
 | `bug-workflow` | `report bug`, `fix bug`, `hotfix needed` | Bug triage, investigation, and resolution |
 | `project-memory` | `set up project memory`, `log a bug fix` | Maintains institutional knowledge |
 
+### 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.
+
+For additional confidence, the optional `/review-plan` command sends the plan to an external AI model (Codex CLI, Gemini CLI, or Claude Code) for independent critique — catching blind spots that same-model review misses.
+
 ### Workflow (Steps 0–6)
 
 ```
 0. SPEC      → spec-creator drafts specs        → Spec Approval
 1. SETUP     → Branch, ticket, product tracker    → Ticket Approval
-2. PLAN      → Planner creates implementation plan → Plan Approval
+2. PLAN      → Planner creates plan + self-review → Plan Approval
 3. IMPLEMENT → Developer agent, TDD
 4. FINALIZE  → Tests/lint/build, validator       → Commit Approval
 5. REVIEW    → PR, code review, QA              → Merge Approval

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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

@@ -0,0 +1,52 @@
+Review the Implementation Plan in the current ticket using an external model for independent critique.
+
+## Prerequisites
+
+- An external AI CLI tool installed: [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or similar
+- An active feature with a completed Implementation Plan (Step 2)
+
+## What to do
+
+1. **Find the current ticket** — Read `docs/project_notes/product-tracker.md` → Active Session → ticket path
+2. **Extract the plan** — Read the ticket's `## Implementation Plan` section
+3. **Send to external reviewer** — Run the external CLI in read-only mode with this prompt:
+
+```
+You are reviewing an Implementation Plan for a software feature. Your job is to find problems, not praise.
+
+Review the plan below and report:
+1. **Errors** — Wrong assumptions, impossible steps, missing dependencies
+2. **Gaps** — Missing error handling, edge cases, rollback scenarios
+3. **Vagueness** — Steps too ambiguous to implement with TDD (no clear input/output)
+4. **Over-engineering** — Unnecessary abstractions, premature optimization
+5. **Order issues** — Steps that depend on later steps
+
+For each issue, state: [CRITICAL/IMPORTANT/SUGGESTION] — description — proposed fix.
+
+End with: VERDICT: APPROVED | VERDICT: REVISE (if any CRITICAL or 2+ IMPORTANT issues)
+
+---
+PLAN:
+<paste the Implementation Plan here>
+```
+
+Example with Codex CLI:
+```bash
+codex exec -m o4-mini --quiet "Review this Implementation Plan: $(cat docs/tickets/FXXX-*.md | sed -n '/## Implementation Plan/,/## Acceptance Criteria/p')"
+```
+
+Example with Gemini CLI:
+```bash
+gemini -m gemini-2.5-pro "Review this Implementation Plan: $(cat docs/tickets/FXXX-*.md | sed -n '/## Implementation Plan/,/## Acceptance Criteria/p')"
+```
+
+4. **Process the review** — If VERDICT: REVISE, update the plan addressing CRITICAL and IMPORTANT issues
+5. **Optional second round** — Send the revised plan for a final audit if significant changes were made
+6. **Log the review** — Add a note in the ticket's Completion Log: "Plan reviewed by [model] — N issues found, N addressed"
+
+## Notes
+
+- This command is **optional** — the workflow's built-in Plan Self-Review (Step 2.4) always runs automatically
+- Most valuable for **Complex** features or plans with 8+ steps
+- The external model runs read-only — it reviews text, not code
+- If no external CLI is available, you can copy-paste the plan into a different AI chat for manual review

package/template/.claude/settings.json

@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '{\"additionalContext\": \"Context was compacted. BEFORE doing anything else: read the product tracker Active Session section (docs/project_notes/product-tracker.md) for context recovery. Follow the Session Recovery protocol in CLAUDE.md.\"}'",
+            "command": "echo '{\"additionalContext\": \"Context was compacted. BEFORE doing anything else: (1) Read the product tracker Active Session (docs/project_notes/product-tracker.md) for context recovery. (2) Re-read the SKILL.md for your current workflow (.claude/skills/development-workflow/SKILL.md) to know what actions are required at your current step. (3) If at Step 5 or later, you MUST read references/merge-checklist.md and fill the Merge Checklist Evidence table in the ticket before requesting merge approval.\"}'",
             "statusMessage": "Injecting recovery context..."
           }
         ]

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

@@ -99,7 +99,14 @@ See `references/branching-strategy.md` for details.
 1. Use Task tool with planner agent (`backend-planner` for backend features, `frontend-planner` for frontend features)
 2. **Fullstack features:** Run `backend-planner` first, then `frontend-planner`. Each writes its own section in the Implementation Plan
 3. Agent writes Implementation Plan into ticket's `## Implementation Plan`
-4. Update tracker: step `2/6 (Plan)` (Active Session + Features table)
+4. **Plan Self-Review:** Re-read the complete Implementation Plan you just wrote. Critically evaluate:
+   - Missing error handling or edge cases?
+   - Steps that are too vague to implement with TDD?
+   - Wrong assumptions about existing code or schemas?
+   - 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)
 
 **→ CHECKPOINT: Plan Approval**
 

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

@@ -0,0 +1,53 @@
+## Review Plan — Instructions
+
+Review the Implementation Plan in the current ticket using an external model for independent critique.
+
+### Prerequisites
+
+- An external AI CLI tool installed: Codex CLI, Claude Code, or similar
+- An active feature with a completed Implementation Plan (Step 2)
+
+### Steps
+
+1. **Find the current ticket** — Read `docs/project_notes/product-tracker.md` → Active Session → ticket path
+2. **Extract the plan** — Read the ticket's `## Implementation Plan` section
+3. **Send to external reviewer** — Run the external CLI in read-only mode with this prompt:
+
+```
+You are reviewing an Implementation Plan for a software feature. Your job is to find problems, not praise.
+
+Review the plan below and report:
+1. Errors — Wrong assumptions, impossible steps, missing dependencies
+2. Gaps — Missing error handling, edge cases, rollback scenarios
+3. Vagueness — Steps too ambiguous to implement with TDD (no clear input/output)
+4. Over-engineering — Unnecessary abstractions, premature optimization
+5. Order issues — Steps that depend on later steps
+
+For each issue, state: [CRITICAL/IMPORTANT/SUGGESTION] — description — proposed fix.
+
+End with: VERDICT: APPROVED | VERDICT: REVISE (if any CRITICAL or 2+ IMPORTANT issues)
+
+---
+PLAN:
+<paste the Implementation Plan here>
+```
+
+Example with Claude Code:
+```bash
+claude -m claude-sonnet-4-20250514 --print "Review this plan: $(cat docs/tickets/FXXX-*.md | sed -n '/## Implementation Plan/,/## Acceptance Criteria/p')"
+```
+
+Example with Codex CLI:
+```bash
+codex exec -m o4-mini --quiet "Review this plan: $(cat docs/tickets/FXXX-*.md | sed -n '/## Implementation Plan/,/## Acceptance Criteria/p')"
+```
+
+4. **Process the review** — If VERDICT: REVISE, update the plan addressing CRITICAL and IMPORTANT issues
+5. **Optional second round** — Send the revised plan for a final audit if significant changes were made
+6. **Log the review** — Add a note in the ticket's Completion Log: "Plan reviewed by [model] — N issues found, N addressed"
+
+### Notes
+
+- This command is **optional** — the workflow's built-in Plan Self-Review (Step 2.4) always runs automatically
+- Most valuable for Complex features or plans with 8+ steps
+- The external model runs read-only — it reviews text, not code

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

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

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

@@ -99,7 +99,14 @@ See `references/branching-strategy.md` for details.
 1. Follow the planner agent instructions (`backend-planner` for backend features, `frontend-planner` for frontend features) in `.gemini/agents/`
 2. **Fullstack features:** Run `backend-planner` first, then `frontend-planner`. Each writes its own section in the Implementation Plan
 3. Write Implementation Plan into ticket's `## Implementation Plan`
-4. Update tracker: step `2/6 (Plan)` (Active Session + Features table)
+4. **Plan Self-Review:** Re-read the complete Implementation Plan you just wrote. Critically evaluate:
+   - Missing error handling or edge cases?
+   - Steps that are too vague to implement with TDD?
+   - Wrong assumptions about existing code or schemas?
+   - 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)
 
 **→ CHECKPOINT: Plan Approval**
 

package/template/CLAUDE.md

@@ -14,6 +14,7 @@ After context compaction or new session — BEFORE continuing work:
 
 1. Read product tracker (`docs/project_notes/product-tracker.md`) → **Active Session**
 2. If active feature → read referenced ticket in `docs/tickets/`
-3. Read the active skill file (`.claude/skills/*/SKILL.md`)
-4. Do NOT proceed past any checkpoint without user confirmation (respect autonomy level)
-5. If Active Session shows a pending checkpoint, ask before continuing
+3. Re-read the workflow skill (`.claude/skills/development-workflow/SKILL.md`) to know what actions the current step requires
+4. If at Step 5 or later → read `references/merge-checklist.md` and check if the ticket's `## Merge Checklist Evidence` table needs to be filled
+5. Do NOT proceed past any checkpoint without user confirmation (respect autonomy level)
+6. If Active Session shows a pending checkpoint, ask before continuing