claude-code-pilot 3.1.1 → 3.2.0

package/src/pilot/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 gsd-framework-selector → gsd-ai-researcher → gsd-domain-researcher → gsd-eval-planner with a validation gate. Inserts between discuss-phase and plan-phase in the GSD 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/pilot/references/ai-frameworks.md
+@~/.claude/pilot/references/ai-evals.md
+</required_reading>
+
+<process>
+
+## 1. Initialize
+
+```bash
+INIT=$(gsd-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=$(gsd-sdk query resolve-model gsd-framework-selector 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+RESEARCHER_MODEL=$(gsd-sdk query resolve-model gsd-ai-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+DOMAIN_MODEL=$(gsd-sdk query resolve-model gsd-domain-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+PLANNER_MODEL=$(gsd-sdk query resolve-model gsd-eval-planner 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+```
+
+Check config:
+```bash
+AI_PHASE_ENABLED=$(gsd-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 /ccp:settings.
+```
+Exit workflow.
+
+**If `planning_exists` is false:** Error — run `/ccp:new-project` first.
+
+## 2. Parse and Validate Phase
+
+Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase.
+
+```bash
+PHASE_INFO=$(gsd-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 /ccp: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 gsd-framework-selector
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AI DESIGN CONTRACT — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Step 1/4 — Framework Selection...
+```
+
+Spawn `gsd-framework-selector` with:
+```markdown
+Read ~/.claude/agents/ccp: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 /ccp:ai-integration-phase {N} or answer the framework question in /ccp:discuss-phase {N} first."
+
+## 6. Initialize AI-SPEC.md
+
+Copy template:
+```bash
+cp "$HOME/.claude/pilot/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 gsd-ai-researcher
+
+Display:
+```
+◆ Step 2/4 — Researching {primary_framework} docs + AI systems best practices...
+```
+
+Spawn `gsd-ai-researcher` with:
+```markdown
+Read ~/.claude/agents/ccp: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 gsd-domain-researcher
+
+Display:
+```
+◆ Step 3/4 — Researching domain context and expert evaluation criteria...
+```
+
+Spawn `gsd-domain-researcher` with:
+```markdown
+Read ~/.claude/agents/ccp: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 gsd-eval-planner
+
+Display:
+```
+◆ Step 4/4 — Designing evaluation strategy from domain + technical context...
+```
+
+Spawn `gsd-eval-planner` with:
+```markdown
+Read ~/.claude/agents/ccp: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
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► 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:
+  /ccp: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/src/pilot/workflows/audit-fix.md

@@ -0,0 +1,175 @@
+<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>
+- gsd-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=$(gsd-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:**
+```
+Task(
+  prompt="Fix finding {ID}: {description}. Files: {file_refs}. Make the minimal change to resolve this specific finding. Do not refactor surrounding code.",
+  subagent_type="gsd-executor"
+)
+```
+
+**b. Run tests:**
+```bash
+AUDIT_TEST_CMD=$(gsd-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>