claude-code-pilot 3.1.1 → 3.2.0

package/src/commands/ccp/import.md

@@ -0,0 +1,37 @@
+---
+name: ccp:import
+description: Ingest external plans with conflict detection against project decisions before writing anything.
+argument-hint: "--from <filepath>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Import external plan files into the GSD planning system with conflict detection against PROJECT.md decisions.
+
+- **--from**: Import an external plan file, detect conflicts, write as GSD PLAN.md, validate via gsd-plan-checker.
+
+Future: `--prd` mode for PRD extraction is planned for a follow-up PR.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/import.md
+@~/.claude/pilot/references/ui-brand.md
+@~/.claude/pilot/references/gate-prompts.md
+@~/.claude/pilot/references/doc-conflict-engine.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the import workflow end-to-end.
+</process>

package/src/commands/ccp/ingest-docs.md

@@ -0,0 +1,42 @@
+---
+name: ccp:ingest-docs
+description: Scan a repo for mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full .planning/ setup from them. Classifies each doc in parallel, synthesizes a consolidated context with a conflicts report, and routes to new-project or merge-milestone depending on whether .planning/ already exists.
+argument-hint: "[path] [--mode new|merge] [--manifest <file>] [--resolve auto|interactive]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Build the full `.planning/` setup (or merge into an existing one) from multiple pre-existing planning documents — ADRs, PRDs, SPECs, DOCs — in one pass.
+
+- **Net-new bootstrap** (`--mode new`, default when `.planning/` is absent): produces PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md from synthesized doc content, delegating final generation to `gsd-roadmapper`.
+- **Merge into existing** (`--mode merge`, default when `.planning/` is present): appends phases and requirements derived from the ingested docs; hard-blocks any contradiction with existing locked decisions.
+
+Auto-synthesizes most conflicts using the precedence rule `ADR > SPEC > PRD > DOC` (overridable via manifest). Surfaces unresolved cases in `.planning/INGEST-CONFLICTS.md` with three buckets: auto-resolved, competing-variants, unresolved-blockers. The BLOCKER gate from the shared conflict engine prevents any destination file from being written when unresolved contradictions exist.
+
+**Inputs:** directory-convention discovery (`docs/adr/`, `docs/prd/`, `docs/specs/`, `docs/rfc/`, root-level `{ADR,PRD,SPEC,RFC}-*.md`), or an explicit `--manifest <file>` YAML listing `{path, type, precedence?}` per doc.
+
+**v1 constraints:** hard cap of 50 docs per invocation; `--resolve interactive` is reserved for a future release.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/ingest-docs.md
+@~/.claude/pilot/references/ui-brand.md
+@~/.claude/pilot/references/gate-prompts.md
+@~/.claude/pilot/references/doc-conflict-engine.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the ingest-docs workflow end-to-end. Preserve all approval gates (discovery, conflict report, routing) and the BLOCKER safety rule.
+</process>

package/src/commands/ccp/intel.md

@@ -0,0 +1,179 @@
+---
+name: ccp:intel
+description: "Query, inspect, or refresh codebase intelligence files in .planning/intel/"
+argument-hint: "[query <term>|status|diff|refresh]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
+
+## Step 0 -- Banner
+
+**Before ANY tool calls**, display this banner:
+
+```
+CCP > INTEL
+```
+
+Then proceed to Step 1.
+
+## Step 1 -- Config Gate
+
+Check if intel is enabled by reading `.planning/config.json` directly using the Read tool.
+
+**DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
+
+1. Read `.planning/config.json` using the Read tool
+2. If the file does not exist: display the disabled message below and **STOP**
+3. Parse the JSON content. Check if `config.intel && config.intel.enabled === true`
+4. If `intel.enabled` is NOT explicitly `true`: display the disabled message below and **STOP**
+5. If `intel.enabled` is `true`: proceed to Step 2
+
+**Disabled message:**
+
+```
+CCP > INTEL
+
+Intel system is disabled. To activate:
+
+  gsd-sdk query config-set intel.enabled true
+
+Then run /ccp:intel refresh to build the initial index.
+```
+
+---
+
+## Step 2 -- Parse Argument
+
+Parse `$ARGUMENTS` to determine the operation mode:
+
+| Argument | Action |
+|----------|--------|
+| `query <term>` | Run inline query (Step 2a) |
+| `status` | Run inline status check (Step 2b) |
+| `diff` | Run inline diff check (Step 2c) |
+| `refresh` | Spawn intel-updater agent (Step 3) |
+| No argument or unknown | Show usage message |
+
+**Usage message** (shown when no argument or unrecognized argument):
+
+```
+CCP > INTEL
+
+Usage: /ccp:intel <mode>
+
+Modes:
+  query <term>  Search intel files for a term
+  status        Show intel file freshness and staleness
+  diff          Show changes since last snapshot
+  refresh       Rebuild all intel files from codebase analysis
+```
+
+### Step 2a -- Query
+
+Run:
+
+```bash
+gsd-sdk query intel.query <term>
+```
+
+Parse the JSON output and display results:
+- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
+- If no matches found, display: `No intel matches for '<term>'. Try /ccp:intel refresh to build the index.`
+- Otherwise, display matching entries grouped by intel file
+
+**STOP** after displaying results. Do not spawn an agent.
+
+### Step 2b -- Status
+
+Run:
+
+```bash
+gsd-sdk query intel.status
+```
+
+Parse the JSON output and display each intel file with:
+- File name
+- Last `updated_at` timestamp
+- STALE or FRESH status (stale if older than 24 hours or missing)
+
+**STOP** after displaying status. Do not spawn an agent.
+
+### Step 2c -- Diff
+
+Run:
+
+```bash
+gsd-sdk query intel.diff
+```
+
+Parse the JSON output and display:
+- Added entries since last snapshot
+- Removed entries since last snapshot
+- Changed entries since last snapshot
+
+If no snapshot exists, suggest running `refresh` first.
+
+**STOP** after displaying diff. Do not spawn an agent.
+
+---
+
+## Step 3 -- Refresh (Agent Spawn)
+
+Display before spawning:
+
+```
+CCP > Spawning intel-updater agent to analyze codebase...
+```
+
+Spawn a Task:
+
+```
+Task(
+  description="Refresh codebase intelligence files",
+  prompt="You are the gsd-intel-updater agent. Your job is to analyze this codebase and write/update intelligence files in .planning/intel/.
+
+Project root: ${CWD}
+Prefer: gsd-sdk query <subcommand> (installed gsd-sdk on PATH). Legacy: node $HOME/.claude/pilot/bin/gsd-tools.cjs
+
+Instructions:
+1. Analyze the codebase structure, dependencies, APIs, and architecture
+2. Write JSON intel files to .planning/intel/ (stack.json, api-map.json, dependency-graph.json, file-roles.json, arch-decisions.json)
+3. Each file must have a _meta object with updated_at timestamp
+4. Use `gsd-sdk query intel.extract-exports <file>` to analyze source files
+5. Use `gsd-sdk query intel.patch-meta <file>` to update timestamps after writing
+6. Use `gsd-sdk query intel.validate` to check your output
+
+When complete, output: ## INTEL UPDATE COMPLETE
+If something fails, output: ## INTEL UPDATE FAILED with details."
+)
+```
+
+Wait for the agent to complete.
+
+---
+
+## Step 4 -- Post-Refresh Summary
+
+After the agent completes, run:
+
+```bash
+gsd-sdk query intel.status
+```
+
+Display a summary showing:
+- Which intel files were written or updated
+- Last update timestamps
+- Overall health of the intel index
+
+---
+
+## Anti-Patterns
+
+1. DO NOT spawn an agent for query/status/diff operations -- these are inline CLI calls
+2. DO NOT modify intel files directly -- the agent handles writes during refresh
+3. DO NOT skip the config gate check
+4. DO NOT use the gsd-tools config get-value CLI for the config gate -- it exits on missing keys

package/src/commands/ccp/plan-review-convergence.md

@@ -0,0 +1,58 @@
+---
+name: ccp:plan-review-convergence
+description: "Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain (max 3 cycles)"
+argument-hint: "<phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--text] [--ws <name>] [--all] [--max-cycles N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Cross-AI plan convergence loop — an outer revision gate around gsd-review and gsd-planner.
+Repeatedly: review plans with external AI CLIs → if HIGH concerns found → replan with --reviews feedback → re-review. Stops when no HIGH concerns remain or max cycles reached.
+
+**Flow:** Agent→Skill("gsd-plan-phase") → Agent→Skill("gsd-review") → check HIGHs → Agent→Skill("gsd-plan-phase --reviews") → Agent→Skill("gsd-review") → ... → Converge or escalate
+
+Replaces gsd-plan-phase's internal gsd-plan-checker with external AI reviewers (codex, gemini, etc.). Each step runs inside an isolated Agent that calls the corresponding existing Skill — orchestrator only does loop control.
+
+**Orchestrator role:** Parse arguments, validate phase, spawn Agents for existing Skills, check HIGHs, stall detection, escalation gate.
+</objective>
+
+<execution_context>
+@$HOME/.claude/pilot/workflows/plan-review-convergence.md
+@$HOME/.claude/pilot/references/revision-loop.md
+@$HOME/.claude/pilot/references/gates.md
+@$HOME/.claude/pilot/references/agent-contracts.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API. Do not skip questioning steps because `AskUserQuestion` appears unavailable; use `vscode_askquestions` instead.
+</runtime_note>
+
+<context>
+Phase number: extracted from $ARGUMENTS (required)
+
+**Flags:**
+- `--codex` — Use Codex CLI as reviewer (default if no reviewer specified)
+- `--gemini` — Use Gemini CLI as reviewer
+- `--claude` — Use Claude CLI as reviewer (separate session)
+- `--opencode` — Use OpenCode as reviewer
+- `--ollama` — Use local Ollama server as reviewer (OpenAI-compatible, default host `http://localhost:11434`; configure model via `review.models.ollama`)
+- `--lm-studio` — Use local LM Studio server as reviewer (OpenAI-compatible, default host `http://localhost:1234`; configure model via `review.models.lm_studio`)
+- `--llama-cpp` — Use local llama.cpp server as reviewer (OpenAI-compatible, default host `http://localhost:8080`; configure model via `review.models.llama_cpp`)
+- `--all` — Use all available CLIs and running local model servers
+- `--max-cycles N` — Maximum replan→review cycles (default: 3)
+
+**Feature gate:** This command requires `workflow.plan_review_convergence=true`. Enable with:
+`gsd config-set workflow.plan_review_convergence true`
+</context>
+
+<process>
+Execute the plan-review-convergence workflow from @$HOME/.claude/pilot/workflows/plan-review-convergence.md end-to-end.
+Preserve all workflow gates (pre-flight, revision loop, stall detection, escalation).
+</process>

package/src/commands/ccp/scan.md

@@ -0,0 +1,26 @@
+---
+name: ccp:scan
+description: Rapid codebase assessment — lightweight alternative to /ccp:map-codebase
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Run a focused codebase scan for a single area, producing targeted documents in `.planning/codebase/`.
+Accepts an optional `--focus` flag: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default).
+
+Lightweight alternative to `/ccp:map-codebase` — spawns one mapper agent instead of four parallel ones.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/scan.md
+</execution_context>
+
+<process>
+Execute the scan workflow from @~/.claude/pilot/workflows/scan.md end-to-end.
+</process>

package/src/commands/ccp/sketch-wrap-up.md

@@ -0,0 +1,31 @@
+---
+name: ccp:sketch-wrap-up
+description: Package sketch design findings into a persistent project skill for future build conversations
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+<objective>
+Curate sketch design findings and package them into a persistent project skill that Claude
+auto-loads when building the real UI. Also writes a summary to `.planning/sketches/` for
+project history. Output skill goes to `./.claude/skills/sketch-findings-[project]/` (project-local).
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/sketch-wrap-up.md
+@~/.claude/pilot/references/ui-brand.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
+</runtime_note>
+
+<process>
+Execute the sketch-wrap-up workflow from @~/.claude/pilot/workflows/sketch-wrap-up.md end-to-end.
+Preserve all curation gates (per-sketch review, grouping approval, CLAUDE.md routing line).
+</process>

package/src/commands/ccp/sketch.md

@@ -0,0 +1,54 @@
+---
+name: ccp:sketch
+description: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
+argument-hint: "[design idea to explore] [--quick] [--text] or [frontier]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+---
+<objective>
+Explore design directions through throwaway HTML mockups before committing to implementation.
+Each sketch produces 2-3 variants for comparison. Sketches live in `.planning/sketches/` and
+integrate with GSD commit patterns, state tracking, and handoff workflows. Loads spike
+findings to ground mockups in real data shapes and validated interaction patterns.
+
+Two modes:
+- **Idea mode** (default) — describe a design idea to sketch
+- **Frontier mode** (no argument or "frontier") — analyzes existing sketch landscape and proposes consistency and frontier sketches
+
+Does not require `/ccp:new-project` — auto-creates `.planning/sketches/` if needed.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/sketch.md
+@~/.claude/pilot/references/ui-brand.md
+@~/.claude/pilot/references/sketch-theme-system.md
+@~/.claude/pilot/references/sketch-interactivity.md
+@~/.claude/pilot/references/sketch-tooling.md
+@~/.claude/pilot/references/sketch-variant-patterns.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
+</runtime_note>
+
+<context>
+Design idea: $ARGUMENTS
+
+**Available flags:**
+- `--quick` — Skip mood/direction intake, jump straight to decomposition and building. Use when the design direction is already clear.
+</context>
+
+<process>
+Execute the sketch workflow from @~/.claude/pilot/workflows/sketch.md end-to-end.
+Preserve all workflow gates (intake, decomposition, target stack research, variant evaluation, MANIFEST updates, commit patterns).
+</process>

package/src/commands/ccp/spec-phase.md

@@ -0,0 +1,62 @@
+---
+name: ccp:spec-phase
+description: Socratic spec refinement — clarify WHAT a phase delivers with ambiguity scoring before discuss-phase. Produces a SPEC.md with falsifiable requirements locked before implementation decisions begin.
+argument-hint: "<phase> [--auto] [--text]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Clarify phase requirements through structured Socratic questioning with quantitative ambiguity scoring.
+
+**Position in workflow:** `spec-phase → discuss-phase → plan-phase → execute-phase → verify`
+
+**How it works:**
+1. Load phase context (PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md)
+2. Scout the codebase — understand current state before asking questions
+3. Run Socratic interview loop (up to 6 rounds, rotating perspectives)
+4. Score ambiguity across 4 weighted dimensions after each round
+5. Gate: ambiguity ≤ 0.20 AND all dimensions meet minimums → write SPEC.md
+6. Commit SPEC.md — discuss-phase picks it up automatically on next run
+
+**Output:** `{phase_dir}/{padded_phase}-SPEC.md` — falsifiable requirements that lock "what/why" before discuss-phase handles "how"
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/spec-phase.md
+@~/.claude/pilot/templates/spec.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent.
+</runtime_note>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+**Flags:**
+- `--auto` — Skip interactive questions; Claude selects recommended defaults and writes SPEC.md
+- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
+
+Context files are resolved in-workflow using `init phase-op`.
+</context>
+
+<process>
+Execute the spec-phase workflow from @~/.claude/pilot/workflows/spec-phase.md end-to-end.
+
+**MANDATORY:** Read the workflow file BEFORE taking any action. The workflow contains the complete step-by-step process including the Socratic interview loop, ambiguity scoring gate, and SPEC.md generation. Do not improvise from the objective summary above.
+</process>
+
+<success_criteria>
+- Codebase scouted for current state before questioning begins
+- All 4 ambiguity dimensions scored after each interview round
+- Gate passed: ambiguity ≤ 0.20 AND all dimension minimums met
+- SPEC.md written with falsifiable requirements, explicit boundaries, and acceptance criteria
+- SPEC.md committed atomically
+- User knows they can now run /ccp:discuss-phase which will load SPEC.md automatically
+</success_criteria>

package/src/commands/ccp/spike-wrap-up.md

@@ -0,0 +1,31 @@
+---
+name: ccp:spike-wrap-up
+description: Package spike findings into a persistent project skill for future build conversations
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+<objective>
+Curate spike experiment findings and package them into a persistent project skill that Claude
+auto-loads in future build conversations. Also writes a summary to `.planning/spikes/` for
+project history. Output skill goes to `./.claude/skills/spike-findings-[project]/` (project-local).
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/spike-wrap-up.md
+@~/.claude/pilot/references/ui-brand.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
+</runtime_note>
+
+<process>
+Execute the spike-wrap-up workflow from @~/.claude/pilot/workflows/spike-wrap-up.md end-to-end.
+Preserve all workflow gates (auto-include, feature-area grouping, skill synthesis, CLAUDE.md routing line, intelligent next-step routing).
+</process>

package/src/commands/ccp/spike.md

@@ -0,0 +1,51 @@
+---
+name: ccp:spike
+description: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
+argument-hint: "[idea to validate] [--quick] [--text] or [frontier]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+---
+<objective>
+Spike an idea through experiential exploration — build focused experiments to feel the pieces
+of a future app, validate feasibility, and produce verified knowledge for the real build.
+Spikes live in `.planning/spikes/` and integrate with GSD commit patterns, state tracking,
+and handoff workflows.
+
+Two modes:
+- **Idea mode** (default) — describe an idea to spike
+- **Frontier mode** (no argument or "frontier") — analyzes existing spike landscape and proposes integration and frontier spikes
+
+Does not require `/ccp:new-project` — auto-creates `.planning/spikes/` if needed.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/spike.md
+@~/.claude/pilot/references/ui-brand.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`.
+</runtime_note>
+
+<context>
+Idea: $ARGUMENTS
+
+**Available flags:**
+- `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike.
+- `--text` — Use plain-text numbered lists instead of AskUserQuestion (for non-Claude runtimes).
+</context>
+
+<process>
+Execute the spike workflow from @~/.claude/pilot/workflows/spike.md end-to-end.
+Preserve all workflow gates (prior spike check, decomposition, research, risk ordering, observability assessment, verification, MANIFEST updates, commit patterns).
+</process>

package/src/commands/ccp/ultraplan-phase.md

@@ -0,0 +1,33 @@
+---
+name: ccp:ultraplan-phase
+description: "[BETA] Offload plan phase to Claude Code's ultraplan cloud — drafts remotely while terminal stays free, review in browser with inline comments, import back via /ccp:import. Claude Code only."
+argument-hint: "[phase-number]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Offload GSD's plan phase to Claude Code's ultraplan cloud infrastructure.
+
+Ultraplan drafts the plan in a remote cloud session while your terminal stays free.
+Review and comment on the plan in your browser, then import it back via /ccp:import --from.
+
+⚠ BETA: ultraplan is in research preview. Use /ccp:plan-phase for stable local planning.
+Requirements: Claude Code v2.1.91+, claude.ai account, GitHub repository.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/ultraplan-phase.md
+@~/.claude/pilot/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the ultraplan-phase workflow end-to-end.
+</process>