@bhargavvc/sdd-cc 1.30.1 → 1.42.3

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

@@ -0,0 +1,294 @@
+<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=$(sdd-sdk query 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=$(sdd-sdk query resolve-model sdd-framework-selector 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+RESEARCHER_MODEL=$(sdd-sdk query resolve-model sdd-ai-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+DOMAIN_MODEL=$(sdd-sdk query resolve-model sdd-domain-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+PLANNER_MODEL=$(sdd-sdk query resolve-model sdd-eval-planner 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+```
+
+Check config:
+```bash
+AI_PHASE_ENABLED=$(sdd-sdk query 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=$(sdd-sdk query 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
+
+> **Ordering note (prevents tool-level last-writer-wins race):** Steps 7 and 8 write disjoint sections of AI-SPEC.md but MUST run sequentially — wait for Step 7 to complete before spawning Step 8. Both agents use the `Edit` tool exclusively (never `Write`) when modifying AI-SPEC.md. A `Write` on a shared file replaces the entire file, silently overwriting the other agent's work; `Edit` targets only the relevant lines. See #3096 for a confirmed 40%-incidence race on parallel dispatch.
+
+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.
+
+**Tool discipline (mandatory):**
+Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file.
+Write replaces the entire file and will overwrite work from parallel or sequential sibling agents.
+Before editing, verify the section you are about to write is still a template placeholder.
+
+<objective>
+</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
+
+> **Wait for Step 7 to complete before spawning this step** (see ordering note in Step 7).
+
+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.
+
+**Tool discipline (mandatory):**
+Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file.
+Write replaces the entire file and will overwrite work from parallel or sequential sibling agents.
+Before editing, verify the section you are about to write is still a template placeholder.
+
+<objective>
+</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>

package/sdd/workflows/analyze-dependencies.md

@@ -0,0 +1,96 @@
+<purpose>
+Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution by `/sdd:manager`.
+</purpose>
+
+<process>
+
+## 1. Load ROADMAP.md
+
+Read `.planning/ROADMAP.md`. If it does not exist, error: "No ROADMAP.md found — run `/sdd:new-project` first."
+
+Extract all phases. For each phase capture:
+- Phase number and name
+- Scope/Goal description
+- Files listed in `Files` or `files_modified` fields (if present)
+- Existing `Depends on` field value
+
+## 2. Infer Likely File Modifications
+
+For each phase without explicit `files_modified`, analyze the scope/goal description to infer which files will likely be modified. Use these heuristics:
+
+- **Database/schema phases** → migration files, schema definitions, model files
+- **API/backend phases** → route files, controller files, service files, handler files
+- **Frontend/UI phases** → component files, page files, style files
+- **Auth phases** → middleware files, auth route files, session/token files
+- **Config/infra phases** → config files, environment files, CI/CD files
+- **Test phases** → test files, spec files, fixture files
+- **Shared utility phases** → lib/utils files, shared type definitions
+
+Group phases by their inferred file domain (database, API, frontend, auth, config, shared).
+
+## 3. Detect Dependency Relationships
+
+For each pair of phases (A, B), check for dependency signals:
+
+### File Overlap Detection
+If phases A and B will both modify files in the same domain or the same specific files, one must run before the other. The phase that *provides* the foundation runs first.
+
+### Semantic Dependency Detection
+Read each phase's scope/goal for these patterns:
+- Phase B mentions consuming, using, or calling something that Phase A creates/implements
+- Phase B references an "API", "schema", "model", "endpoint", or "interface" that Phase A builds
+- Phase B says "after X is complete", "once X is built", "using the X from Phase N"
+- Phase B extends or modifies code that Phase A establishes
+
+### Data Flow Detection
+- Phase A creates data structures, schemas, or types → Phase B consumes or transforms them
+- Phase A seeds/migrates the database → Phase B reads from that database
+- Phase A exposes an API contract → Phase B implements the client for that contract
+
+## 4. Build Dependency Table
+
+Output a dependency suggestion table:
+
+```
+Phase Dependency Analysis
+=========================
+
+Phase N: <name>
+  Scope: <brief scope>
+  Likely touches: <inferred file domains>
+
+  Suggested dependencies:
+  → Depends on: <Phase M> — reason: <overlap/semantic/data-flow explanation>
+
+  Current "Depends on": <existing value or "(none)">
+```
+
+For phase pairs with no detected dependency, state: "No dependency detected between Phase X and Phase Y."
+
+## 5. Summarize Suggested Changes
+
+Show a consolidated diff of proposed ROADMAP.md `Depends on` changes:
+
+```
+Suggested ROADMAP.md updates:
+  Phase 3: add "Depends on: 1, 2"   (file overlap: database schema)
+  Phase 5: add "Depends on: 3"      (semantic: uses auth API from Phase 3)
+  Phase 4: no change needed         (independent scope)
+```
+
+## 6. Confirm and Apply
+
+Ask the user: "Apply these `Depends on` suggestions to ROADMAP.md? (yes / no / edit)"
+
+- **yes** — Write all suggested `Depends on` entries to ROADMAP.md. Confirm each write.
+- **no** — Print the suggestions as text only. User updates manually.
+- **edit** — Present each suggestion individually with yes/no/skip per suggestion.
+
+When writing to ROADMAP.md:
+- Locate the phase entry and add or update the `Depends on:` field
+- Preserve all other phase content unchanged
+- Do not reorder phases
+
+After applying: "ROADMAP.md updated. Run `/sdd:manager` to execute phases in the correct order."
+
+</process>

package/sdd/workflows/audit-fix.md

@@ -0,0 +1,177 @@
+<purpose>
+Autonomous audit-to-fix pipeline. Runs an audit, parses findings, classifies each as
+auto-fixable vs manual-only, spawns executor agents for fixable issues, runs tests
+after each fix, and commits atomically with finding IDs for traceability.
+</purpose>
+
+<available_agent_types>
+- sdd-executor — executes a specific, scoped code change
+</available_agent_types>
+
+<process>
+
+<step name="parse-arguments">
+Extract flags from the user's invocation:
+
+- `--max N` — maximum findings to fix (default: **5**)
+- `--severity high|medium|all` — minimum severity to process (default: **medium**)
+- `--dry-run` — classify findings without fixing (shows classification table only)
+- `--source <audit>` — which audit to run (default: **audit-uat**)
+
+Validate `--source` is a supported audit. Currently supported:
+- `audit-uat`
+
+If `--source` is not supported, stop with an error:
+```
+Error: Unsupported audit source "{source}". Supported sources: audit-uat
+```
+</step>
+
+<step name="run-audit">
+Invoke the source audit command and capture output.
+
+For `audit-uat` source:
+```bash
+INIT=$(sdd-sdk query audit-uat 2>/dev/null || echo "{}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Read existing UAT and verification files to extract findings:
+- Glob: `.planning/phases/*/*-UAT.md`
+- Glob: `.planning/phases/*/*-VERIFICATION.md`
+
+Parse each finding into a structured record:
+- **ID** — sequential identifier (F-01, F-02, ...)
+- **description** — concise summary of the issue
+- **severity** — high, medium, or low
+- **file_refs** — specific file paths referenced in the finding
+</step>
+
+<step name="classify-findings">
+For each finding, classify as one of:
+
+- **auto-fixable** — clear code change, specific file referenced, testable fix
+- **manual-only** — requires design decisions, ambiguous scope, architectural changes, user input needed
+- **skip** — severity below the `--severity` threshold
+
+**Classification heuristics** (err on manual-only when uncertain):
+
+Auto-fixable signals:
+- References a specific file path + line number
+- Describes a missing test or assertion
+- Missing export, wrong import path, typo in identifier
+- Clear single-file change with obvious expected behavior
+
+Manual-only signals:
+- Uses words like "consider", "evaluate", "design", "rethink"
+- Requires new architecture or API changes
+- Ambiguous scope or multiple valid approaches
+- Requires user input or design decisions
+- Cross-cutting concerns affecting multiple subsystems
+- Performance or scalability issues without clear fix
+
+**When uncertain, always classify as manual-only.**
+</step>
+
+<step name="present-classification">
+Display the classification table:
+
+```
+## Audit-Fix Classification
+
+| # | Finding | Severity | Classification | Reason |
+|---|---------|----------|---------------|--------|
+| F-01 | Missing export in index.ts | high | auto-fixable | Specific file, clear fix |
+| F-02 | No error handling in payment flow | high | manual-only | Requires design decisions |
+| F-03 | Test stub with 0 assertions | medium | auto-fixable | Clear test gap |
+```
+
+If `--dry-run` was specified, **stop here and exit**. The classification table is the
+final output — do not proceed to fixing.
+</step>
+
+<step name="fix-loop">
+For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
+
+**a. Spawn executor agent:**
+```
+Agent(
+  prompt="Fix finding {ID}: {description}. Files: {file_refs}. Make the minimal change to resolve this specific finding. Do not refactor surrounding code.",
+  subagent_type="sdd-executor"
+)
+```
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
+**b. Run tests:**
+```bash
+AUDIT_TEST_CMD=$(sdd-sdk query config-get workflow.test_command --default "" 2>/dev/null || true)
+if [ -z "$AUDIT_TEST_CMD" ]; then
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+    AUDIT_TEST_CMD="make test"
+  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+    AUDIT_TEST_CMD="just test"
+  elif [ -f "package.json" ]; then
+    AUDIT_TEST_CMD="npm test"
+  elif [ -f "Cargo.toml" ]; then
+    AUDIT_TEST_CMD="cargo test"
+  elif [ -f "go.mod" ]; then
+    AUDIT_TEST_CMD="go test ./..."
+  elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+    AUDIT_TEST_CMD="python -m pytest -x -q --tb=short"
+  else
+    AUDIT_TEST_CMD="true"
+  fi
+fi
+eval "$AUDIT_TEST_CMD" 2>&1 | tail -20
+```
+
+**c. If tests pass** — commit atomically:
+```bash
+git add {changed_files}
+git commit -m "fix({scope}): resolve {ID} — {description}"
+```
+The commit message **must** include the finding ID (e.g., F-01) for traceability.
+
+**d. If tests fail** — revert changes, mark finding as `fix-failed`, and **stop the pipeline**:
+```bash
+git checkout -- {changed_files} 2>/dev/null
+```
+Log the failure reason and stop processing — do not continue to the next finding.
+A test failure indicates the codebase may be in an unexpected state, so the pipeline
+must halt to avoid cascading issues. Remaining auto-fixable findings will appear in the
+report as `not-attempted`.
+</step>
+
+<step name="report">
+Present the final summary:
+
+```
+## Audit-Fix Complete
+
+**Source:** {audit_command}
+**Findings:** {total} total, {auto} auto-fixable, {manual} manual-only
+**Fixed:** {fixed_count}/{auto} auto-fixable findings
+**Failed:** {failed_count} (reverted)
+
+| # | Finding | Status | Commit |
+|---|---------|--------|--------|
+| F-01 | Missing export | Fixed | abc1234 |
+| F-03 | Test stub | Fix failed | (reverted) |
+
+### Manual-only findings (require developer attention):
+- F-02: No error handling in payment flow — requires design decisions
+```
+</step>
+
+</process>
+
+<success_criteria>
+- Auto-fixable findings processed sequentially until --max reached or a test failure stops the pipeline
+- Tests pass after each committed fix (no broken commits)
+- Failed fixes are reverted cleanly (no partial changes left)
+- Pipeline stops after the first test failure (no cascading fixes)
+- Every commit message contains the finding ID
+- Manual-only findings are surfaced for developer attention
+- --dry-run produces a useful standalone classification table
+</success_criteria>