@bhargavvc/sdd-cc 1.30.0 → 1.35.0

package/sdd/templates/claude-md.md

@@ -2,8 +2,8 @@
 
 Template for project-root `CLAUDE.md` — auto-generated by `sdd-tools generate-claude-md`.
 
-Contains 6 marker-bounded sections. Each section is independently updatable.
-The `generate-claude-md` subcommand manages 5 sections (project, stack, conventions, architecture, workflow enforcement).
+Contains 7 marker-bounded sections. Each section is independently updatable.
+The `generate-claude-md` subcommand manages 6 sections (project, stack, conventions, architecture, skills, workflow enforcement).
 The profile section is managed exclusively by `generate-claude-profile`.
 
 ---
@@ -21,7 +21,7 @@ The profile section is managed exclusively by `generate-claude-profile`.
 
 **Fallback text:**
 ```
-Project not yet initialized. Run /sdd:new-project to set up.
+Project not yet initialized. Run /sdd-new-project to set up.
 ```
 
 ### Stack Section
@@ -66,6 +66,28 @@ Conventions not yet established. Will populate as patterns emerge during develop
 Architecture not yet mapped. Follow existing patterns found in the codebase.
 ```
 
+### Skills Section
+```
+<!-- SDD:skills-start source:skills/ -->
+## Project Skills
+
+| Skill          | Description           | Path                      |
+| -------------- | --------------------- | ------------------------- |
+| {{skill_name}} | {{skill_description}} | `{{skill_path}}/SKILL.md` |
+<!-- SDD:skills-end -->
+```
+
+**Fallback text:**
+```
+No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.
+```
+
+**Discovery behavior:**
+- Scans `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/` for subdirectories containing `SKILL.md`
+- Extracts `name` and `description` from YAML frontmatter (supports multi-line descriptions)
+- Skips SDD's own installed skills (directories starting with `sdd-`)
+- Deduplicates by skill name across directories
+
 ### Workflow Enforcement Section
 ```
 <!-- SDD:workflow-start source:SDD defaults -->
@@ -74,9 +96,9 @@ Architecture not yet mapped. Follow existing patterns found in the codebase.
 Before using Edit, Write, or other file-changing tools, start work through a SDD command so planning artifacts and execution context stay in sync.
 
 Use these entry points:
-- `/sdd:quick` for small fixes, doc updates, and ad-hoc tasks
-- `/sdd:debug` for investigation and bug fixing
-- `/sdd:execute-phase` for planned phase work
+- `/sdd-quick` for small fixes, doc updates, and ad-hoc tasks
+- `/sdd-debug` for investigation and bug fixing
+- `/sdd-execute-phase` for planned phase work
 
 Do not make direct repo edits outside a SDD workflow unless the user explicitly asks to bypass it.
 <!-- SDD:workflow-end -->
@@ -87,7 +109,7 @@ Do not make direct repo edits outside a SDD workflow unless the user explicitly
 <!-- SDD:profile-start -->
 ## Developer Profile
 
-> Profile not yet configured. Run `/sdd:profile-user` to generate your developer profile.
+> Profile not yet configured. Run `/sdd-profile-user` to generate your developer profile.
 > This section is managed by `generate-claude-profile` — do not edit manually.
 <!-- SDD:profile-end -->
 ```
@@ -104,8 +126,9 @@ CLAUDE.md file and no profile section exists yet.
 2. **Stack** — Technology choices (what tools are used)
 3. **Conventions** — Code patterns and rules (how code is written)
 4. **Architecture** — System structure (how components fit together)
-5. **Workflow Enforcement** — Default SDD entry points for file-changing work
-6. **Profile** — Developer behavioral preferences (how to interact)
+5. **Skills** — Discovered project skills with name and description (what domain knowledge is available)
+6. **Workflow Enforcement** — Default SDD entry points for file-changing work
+7. **Profile** — Developer behavioral preferences (how to interact)
 
 ## Marker Format
 

package/sdd/templates/config.json

@@ -7,6 +7,9 @@
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": true,
+    "security_enforcement": true,
+    "security_asvs_level": 1,
+    "security_block_on": "high",
     "discuss_mode": "discuss",
     "research_before_questions": false
   },
@@ -40,5 +43,6 @@
   "hooks": {
     "context_warnings": true
   },
+  "project_code": null,
   "agent_skills": {}
 }

package/sdd/templates/debug-subagent-prompt.md

@@ -51,7 +51,7 @@ Create: .planning/debug/{slug}.md
 
 ## Usage
 
-**From /sdd:debug:**
+**From /sdd-debug:**
 ```python
 Task(
   prompt=filled_template,

package/sdd/templates/dev-preferences.md

@@ -5,7 +5,7 @@ description: Load developer preferences into this session
 # Developer Preferences
 
 > Generated by SDD on {{generated_at}} from {{data_source}}.
-> Run `/sdd:profile-user --refresh` to regenerate.
+> Run `/sdd-profile-user --refresh` to regenerate.
 
 ## Behavioral Directives
 

package/sdd/templates/discovery.md

@@ -4,7 +4,7 @@ Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for libr
 
 **Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
 
-For deep ecosystem research ("how do experts build this"), use `/sdd:research-phase` which produces RESEARCH.md.
+For deep ecosystem research ("how do experts build this"), use `/sdd-research-phase` which produces RESEARCH.md.
 
 ---
 
@@ -142,5 +142,5 @@ Create `.planning/phases/XX-name/DISCOVERY.md`:
 - Niche/complex domains (3D, games, audio, shaders)
 - Need ecosystem knowledge, not just library choice
 - "How do experts build this" questions
-- Use `/sdd:research-phase` for these
+- Use `/sdd-research-phase` for these
 </guidelines>

package/sdd/templates/phase-prompt.md

@@ -142,7 +142,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `user_setup` | No | Array of human-required setup items (external services) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
 
-**Wave is pre-computed:** Wave numbers are assigned during `/sdd:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
+**Wave is pre-computed:** Wave numbers are assigned during `/sdd-plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
 
 **Must-haves enable verification:** The `must_haves` field carries goal-backward requirements from planning to execution. After all plans complete, execute-phase spawns a verification subagent that checks these criteria against the actual codebase.
 

package/sdd/templates/planner-subagent-prompt.md

@@ -34,7 +34,7 @@ Template for spawning sdd-planner agent. The agent contains all planning experti
 </planning_context>
 
 <downstream_consumer>
-Output consumed by /sdd:execute-phase
+Output consumed by /sdd-execute-phase
 Plans must be executable prompts with:
 - Frontmatter (wave, depends_on, files_modified, autonomous)
 - Tasks in XML format
@@ -68,7 +68,7 @@ Before returning PLANNING COMPLETE:
 
 ## Usage
 
-**From /sdd:plan-phase (standard mode):**
+**From /sdd-plan-phase (standard mode):**
 ```python
 Task(
   prompt=filled_template,
@@ -77,7 +77,7 @@ Task(
 )
 ```
 
-**From /sdd:plan-phase --gaps (gap closure mode):**
+**From /sdd-plan-phase --gaps (gap closure mode):**
 ```python
 Task(
   prompt=filled_template,  # with mode: gap_closure

package/sdd/templates/project.md

@@ -149,7 +149,7 @@ and implemented by workflows/transition.md and workflows/complete-milestone.md.
 
 For existing codebases:
 
-1. **Map codebase first** via `/sdd:map-codebase`
+1. **Map codebase first** via `/sdd-map-codebase`
 
 2. **Infer Validated requirements** from existing code:
    - What does the codebase actually do?

package/sdd/templates/research.md

@@ -18,7 +18,7 @@ Template for `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - comprehensive
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 
-**CRITICAL:** If CONTEXT.md exists from /sdd:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
+**CRITICAL:** If CONTEXT.md exists from /sdd-discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
 
 ### Locked Decisions
 [Copy from CONTEXT.md `## Decisions` section - these are NON-NEGOTIABLE]

package/sdd/templates/state.md

@@ -145,10 +145,10 @@ Updated after each plan completion.
 
 **Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
 
-**Pending Todos:** Ideas captured via /sdd:add-todo
+**Pending Todos:** Ideas captured via /sdd-add-todo
 - Count of pending todos
 - Reference to .planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /sdd:check-todos")
+- Brief list if few, count if many (e.g., "5 pending todos — see /sdd-check-todos")
 
 **Blockers/Concerns:** From "Next Phase Readiness" sections
 - Issues that affect future work

package/sdd/workflows/add-phase.md

@@ -11,15 +11,15 @@ Read all files referenced by the invoking prompt's execution_context before star
 <step name="parse_arguments">
 Parse the command arguments:
 - All arguments become the phase description
-- Example: `/sdd:add-phase Add authentication` → description = "Add authentication"
-- Example: `/sdd:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+- Example: `/sdd-add-phase Add authentication` → description = "Add authentication"
+- Example: `/sdd-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
 
 If no arguments provided:
 
 ```
 ERROR: Phase description required
-Usage: /sdd:add-phase <description>
-Example: /sdd:add-phase Add authentication system
+Usage: /sdd-add-phase <description>
+Example: /sdd-add-phase Add authentication system
 ```
 
 Exit.
@@ -36,7 +36,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 Check `roadmap_exists` from init JSON. If false:
 ```
 ERROR: No roadmap found (.planning/ROADMAP.md)
-Run /sdd:new-project to initialize.
+Run /sdd-new-project to initialize.
 ```
 Exit.
 </step>
@@ -87,14 +87,14 @@ Roadmap updated: .planning/ROADMAP.md
 
 **Phase {N}: {description}**
 
-`/sdd:plan-phase {N}`
+`/clear` then:
 
-<sub>`/clear` first → fresh context window</sub>
+`/sdd-plan-phase {N}`
 
 ---
 
 **Also available:**
-- `/sdd:add-phase <description>` — add another phase
+- `/sdd-add-phase <description>` — add another phase
 - Review roadmap
 
 ---

package/sdd/workflows/add-tests.md

@@ -1,7 +1,7 @@
 <purpose>
 Generate unit and E2E tests for a completed phase based on its SUMMARY.md, CONTEXT.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
-Users currently hand-craft `/sdd:quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
+Users currently hand-craft `/sdd-quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
 </purpose>
 
 <required_reading>
@@ -15,15 +15,15 @@ Parse `$ARGUMENTS` for:
 - Phase number (integer, decimal, or letter-suffix) → store as `$PHASE_ARG`
 - Remaining text after phase number → store as `$EXTRA_INSTRUCTIONS` (optional)
 
-Example: `/sdd:add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
+Example: `/sdd-add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
 
 If no phase argument provided:
 
 ```
 ERROR: Phase number required
-Usage: /sdd:add-tests <phase> [additional instructions]
-Example: /sdd:add-tests 12
-Example: /sdd:add-tests 12 focus on edge cases in the pricing module
+Usage: /sdd-add-tests <phase> [additional instructions]
+Example: /sdd-add-tests 12
+Example: /sdd-add-tests 12 focus on edge cases in the pricing module
 ```
 
 Exit.
@@ -54,7 +54,7 @@ Read the phase artifacts (in order of priority):
 If no SUMMARY.md exists:
 ```
 ERROR: No SUMMARY.md found for phase ${PHASE_ARG}
-This command works on completed phases. Run /sdd:execute-phase first.
+This command works on completed phases. Run /sdd-execute-phase first.
 ```
 Exit.
 
@@ -108,6 +108,9 @@ Read each file to verify classification. Don't classify based on filename alone.
 <step name="present_classification">
 Present the classification to the user for confirmation before proceeding:
 
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
 ```
 AskUserQuestion(
   header: "Test Classification",
@@ -315,7 +318,7 @@ Present next steps:
 ## ▶ Next Up
 
 {if bugs discovered:}
-**Fix discovered bugs:** `/sdd:quick fix the {N} test failures discovered in phase ${phase_number}`
+**Fix discovered bugs:** `/sdd-quick fix the {N} test failures discovered in phase ${phase_number}`
 
 {if blocked tests:}
 **Resolve test blockers:** {description of what's needed}
@@ -326,8 +329,8 @@ Present next steps:
 ---
 
 **Also available:**
-- `/sdd:add-tests {next_phase}` — test another phase
-- `/sdd:verify-work {phase_number}` — run UAT verification
+- `/sdd-add-tests {next_phase}` — test another phase
+- `/sdd-verify-work {phase_number}` — run UAT verification
 
 ---
 ```

package/sdd/workflows/add-todo.md

@@ -20,7 +20,7 @@ Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos
 
 Ensure directories exist:
 ```bash
-mkdir -p .planning/todos/pending .planning/todos/done
+mkdir -p .planning/todos/pending .planning/todos/completed
 ```
 
 Note existing areas from the todos array for consistency in infer_area step.
@@ -28,7 +28,7 @@ Note existing areas from the todos array for consistency in infer_area step.
 
 <step name="extract_content">
 **With arguments:** Use as the title/focus.
-- `/sdd:add-todo Add auth token refresh` → title = "Add auth token refresh"
+- `/sdd-add-todo Add auth token refresh` → title = "Add auth token refresh"
 
 **Without arguments:** Analyze recent conversation to extract:
 - The specific problem, idea, or task discussed
@@ -70,6 +70,8 @@ If potential duplicate found:
 1. Read the existing todo
 2. Compare scope
 
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 If overlapping, use AskUserQuestion:
 - header: "Duplicate?"
 - question: "Similar todo exists: [title]. What would you like to do?"
@@ -141,7 +143,7 @@ Would you like to:
 
 1. Continue with current work
 2. Add another todo
-3. View all todos (/sdd:check-todos)
+3. View all todos (/sdd-check-todos)
 ```
 </step>
 

package/sdd/workflows/ai-integration-phase.md

@@ -0,0 +1,284 @@
+<purpose>
+Generate an AI design contract (AI-SPEC.md) for phases that involve building AI systems. Orchestrates sdd-framework-selector → sdd-ai-researcher → sdd-domain-researcher → sdd-eval-planner with a validation gate. Inserts between discuss-phase and plan-phase in the SDD lifecycle.
+
+AI-SPEC.md locks four things before the planner creates tasks:
+1. Framework selection (with rationale and alternatives)
+2. Implementation guidance (correct syntax, patterns, pitfalls from official docs)
+3. Domain context (practitioner rubric ingredients, failure modes, regulatory constraints)
+4. Evaluation strategy (dimensions, rubrics, tooling, reference dataset, guardrails)
+
+This prevents the two most common AI development failures: choosing the wrong framework for the use case, and treating evaluation as an afterthought.
+</purpose>
+
+<required_reading>
+@~/.claude/sdd/references/ai-frameworks.md
+@~/.claude/sdd/references/ai-evals.md
+</required_reading>
+
+<process>
+
+## 1. Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" init plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`.
+
+**File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`.
+
+Resolve agent models:
+```bash
+SELECTOR_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-framework-selector --raw)
+RESEARCHER_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-ai-researcher --raw)
+DOMAIN_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-domain-researcher --raw)
+PLANNER_MODEL=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" resolve-model sdd-eval-planner --raw)
+```
+
+Check config:
+```bash
+AI_PHASE_ENABLED=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" config-get workflow.ai_integration_phase 2>/dev/null || echo "true")
+```
+
+**If `AI_PHASE_ENABLED` is `false`:**
+```
+AI phase is disabled in config. Enable via /sdd-settings.
+```
+Exit workflow.
+
+**If `planning_exists` is false:** Error — run `/sdd-new-project` first.
+
+## 2. Parse and Validate Phase
+
+Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase.
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${PHASE}")
+```
+
+**If `found` is false:** Error with available phases.
+
+## 3. Check Prerequisites
+
+**If `has_context` is false:**
+```
+No CONTEXT.md found for Phase {N}.
+Recommended: run /sdd-discuss-phase {N} first to capture framework preferences.
+Continuing without user decisions — framework selector will ask all questions.
+```
+Continue (non-blocking).
+
+## 4. Check Existing AI-SPEC
+
+```bash
+AI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-AI-SPEC.md 2>/dev/null | head -1)
+```
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+**If exists:** Use AskUserQuestion:
+- header: "Existing AI-SPEC"
+- question: "AI-SPEC.md already exists for Phase {N}. What would you like to do?"
+- options:
+  - "Update — re-run with existing as baseline"
+  - "View — display current AI-SPEC and exit"
+  - "Skip — keep current AI-SPEC and exit"
+
+If "View": display file contents, exit.
+If "Skip": exit.
+If "Update": continue to step 5.
+
+## 5. Spawn sdd-framework-selector
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► AI DESIGN CONTRACT — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Step 1/4 — Framework Selection...
+```
+
+Spawn `sdd-framework-selector` with:
+```markdown
+Read ~/.claude/agents/sdd-framework-selector.md for instructions.
+
+<objective>
+Select the right AI framework for Phase {phase_number}: {phase_name}
+Goal: {phase_goal}
+</objective>
+
+<files_to_read>
+{context_path if exists}
+{requirements_path if exists}
+</files_to_read>
+
+<phase_context>
+Phase: {phase_number} — {phase_name}
+Goal: {phase_goal}
+</phase_context>
+```
+
+Parse selector output for: `primary_framework`, `system_type`, `model_provider`, `eval_concerns`, `alternative_framework`.
+
+**If selector fails or returns empty:** Exit with error — "Framework selection failed. Re-run /sdd-ai-integration-phase {N} or answer the framework question in /sdd-discuss-phase {N} first."
+
+## 6. Initialize AI-SPEC.md
+
+Copy template:
+```bash
+cp "$HOME/.claude/sdd/templates/AI-SPEC.md" "${PHASE_DIR}/${PADDED_PHASE}-AI-SPEC.md"
+```
+
+Fill in header fields:
+- Phase number and name
+- System classification (from selector)
+- Selected framework (from selector)
+- Alternative considered (from selector)
+
+## 7. Spawn sdd-ai-researcher
+
+Display:
+```
+◆ Step 2/4 — Researching {primary_framework} docs + AI systems best practices...
+```
+
+Spawn `sdd-ai-researcher` with:
+```markdown
+Read ~/.claude/agents/sdd-ai-researcher.md for instructions.
+
+<objective>
+Research {primary_framework} for Phase {phase_number}: {phase_name}
+Write Sections 3 and 4 of AI-SPEC.md
+</objective>
+
+<files_to_read>
+{ai_spec_path}
+{context_path if exists}
+</files_to_read>
+
+<input>
+framework: {primary_framework}
+system_type: {system_type}
+model_provider: {model_provider}
+ai_spec_path: {ai_spec_path}
+phase_context: Phase {phase_number}: {phase_name} — {phase_goal}
+</input>
+```
+
+## 8. Spawn sdd-domain-researcher
+
+Display:
+```
+◆ Step 3/4 — Researching domain context and expert evaluation criteria...
+```
+
+Spawn `sdd-domain-researcher` with:
+```markdown
+Read ~/.claude/agents/sdd-domain-researcher.md for instructions.
+
+<objective>
+Research the business domain and expert evaluation criteria for Phase {phase_number}: {phase_name}
+Write Section 1b (Domain Context) of AI-SPEC.md
+</objective>
+
+<files_to_read>
+{ai_spec_path}
+{context_path if exists}
+{requirements_path if exists}
+</files_to_read>
+
+<input>
+system_type: {system_type}
+phase_name: {phase_name}
+phase_goal: {phase_goal}
+ai_spec_path: {ai_spec_path}
+</input>
+```
+
+## 9. Spawn sdd-eval-planner
+
+Display:
+```
+◆ Step 4/4 — Designing evaluation strategy from domain + technical context...
+```
+
+Spawn `sdd-eval-planner` with:
+```markdown
+Read ~/.claude/agents/sdd-eval-planner.md for instructions.
+
+<objective>
+Design evaluation strategy for Phase {phase_number}: {phase_name}
+Write Sections 5, 6, and 7 of AI-SPEC.md
+AI-SPEC.md now contains domain context (Section 1b) — use it as your rubric starting point.
+</objective>
+
+<files_to_read>
+{ai_spec_path}
+{context_path if exists}
+{requirements_path if exists}
+</files_to_read>
+
+<input>
+system_type: {system_type}
+framework: {primary_framework}
+model_provider: {model_provider}
+phase_name: {phase_name}
+phase_goal: {phase_goal}
+ai_spec_path: {ai_spec_path}
+</input>
+```
+
+## 10. Validate AI-SPEC Completeness
+
+Read the completed AI-SPEC.md. Check that:
+- Section 2 has a framework name (not placeholder)
+- Section 1b has at least one domain rubric ingredient (Good/Bad/Stakes)
+- Section 3 has a non-empty code block (entry point pattern)
+- Section 4b has a Pydantic example
+- Section 5 has at least one row in the dimensions table
+- Section 6 has at least one guardrail or explicit "N/A for internal tool" note
+- Checklist section at end has 3+ items checked
+
+**If validation fails:** Display specific missing sections. Ask user if they want to re-run the specific step or continue anyway.
+
+## 11. Commit
+
+**If `commit_docs` is true:**
+```bash
+git add "${AI_SPEC_FILE}"
+git commit -m "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy"
+```
+
+## 12. Display Completion
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SDD ► AI-SPEC COMPLETE — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Framework: {primary_framework}
+◆ System Type: {system_type}
+◆ Domain: {domain_vertical from Section 1b}
+◆ Eval Dimensions: {eval_concerns}
+◆ Tracing Default: Arize Phoenix (or detected existing tool)
+◆ Output: {ai_spec_path}
+
+Next step:
+  /sdd-plan-phase {N}   — planner will consume AI-SPEC.md
+```
+
+</process>
+
+<success_criteria>
+- [ ] Framework selected with rationale (Section 2)
+- [ ] AI-SPEC.md created from template
+- [ ] Framework docs + AI best practices researched (Sections 3, 4, 4b populated)
+- [ ] Domain context + expert rubric ingredients researched (Section 1b populated)
+- [ ] Eval strategy grounded in domain context (Sections 5-7 populated)
+- [ ] Arize Phoenix (or detected tool) set as tracing default in Section 7
+- [ ] AI-SPEC.md validated (Sections 1b, 2, 3, 4b, 5, 6 all non-empty)
+- [ ] Committed if commit_docs enabled
+- [ ] Next step surfaced to user
+</success_criteria>