claude-code-pilot 2.0.0 → 3.1.0

package/src/pilot/workflows/help.md

@@ -0,0 +1,767 @@
+<purpose>
+Display the complete CCP command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+</purpose>
+
+<reference>
+# CCP Command Reference
+
+**CCP** (Claude Code Pilot) creates hierarchical project plans optimized for solo agentic development with Claude Code.
+
+## Quick Start
+
+1. `/ccp:new-project` - Initialize project (includes research, requirements, roadmap)
+2. `/ccp:plan-phase 1` - Create detailed plan for first phase
+3. `/ccp:execute-phase 1` - Execute the phase
+
+## Staying Updated
+
+CCP evolves fast. Update periodically:
+
+```bash
+npx claude-code-pilot@latest
+```
+
+Or use `/ccp:update` for a guided update with changelog preview.
+
+---
+
+## Part 1: Project Lifecycle Commands (`/ccp:` prefix)
+
+These commands manage the full project lifecycle: initialization, planning, execution, verification, and shipping.
+
+### Getting Started
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:new-project` | Initialize a new project with deep context gathering and PROJECT.md |
+| `/ccp:new-milestone <name>` | Start a new milestone cycle -- update PROJECT.md and route to requirements |
+| `/ccp:help` | Show this command reference |
+| `/ccp:settings` | Configure CCP workflow toggles and model profile |
+| `/ccp:set-profile <profile>` | Switch model profile for CCP agents (quality/balanced/budget/inherit) |
+| `/ccp:update` | Update CCP to latest version with changelog display |
+
+### Planning
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:discuss-phase <N>` | Gather phase context through adaptive questioning before planning |
+| `/ccp:research-phase <N>` | Research how to implement a phase (standalone ecosystem research) |
+| `/ccp:plan-phase <N>` | Create detailed phase plan (PLAN.md) with verification loop |
+| `/ccp:validate-phase <N>` | Retroactively audit and fill Nyquist validation gaps for a completed phase |
+| `/ccp:list-phase-assumptions <N>` | Surface Claude's assumptions about a phase approach before planning |
+
+### Execution
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:execute-phase <N>` | Execute all plans in a phase with wave-based parallelization |
+| `/ccp:quick` | Execute a quick task with CCP guarantees but skip optional agents |
+| `/ccp:fast [description]` | Execute a trivial task inline -- no subagents, no planning overhead |
+| `/ccp:do <description>` | Route freeform text to the right CCP command automatically |
+| `/ccp:next` | Automatically advance to the next logical step in the CCP workflow |
+| `/ccp:autonomous` | Run all remaining phases autonomously -- discuss, plan, execute per phase |
+| `/ccp:manager` | Interactive command center for managing multiple phases from one terminal |
+
+### Verification
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:verify-work [phase]` | Validate built features through conversational UAT |
+| `/ccp:audit-milestone [version]` | Audit milestone completion against original intent before archiving |
+| `/ccp:complete-milestone <version>` | Archive completed milestone and prepare for next version |
+| `/ccp:audit-uat` | Cross-phase audit of all outstanding UAT and verification items |
+
+### Navigation & Diagnostics
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:progress` | Check project progress, show context, and route to next action |
+| `/ccp:health` | Diagnose planning directory health and optionally repair issues |
+| `/ccp:stats` | Display project statistics -- phases, plans, requirements, git metrics |
+| `/ccp:debug [issue]` | Systematic debugging with persistent state across context resets |
+| `/ccp:forensics` | Post-mortem investigation for failed CCP workflows |
+
+### Content Management
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:add-phase <description>` | Add phase to end of current milestone in roadmap |
+| `/ccp:insert-phase <after> <desc>` | Insert urgent work as decimal phase between existing phases |
+| `/ccp:remove-phase <N>` | Remove a future phase from roadmap and renumber subsequent phases |
+| `/ccp:add-tests` | Generate tests for a completed phase based on UAT criteria |
+| `/ccp:add-todo [description]` | Capture idea or task as todo from current conversation context |
+| `/ccp:check-todos [area]` | List pending todos and select one to work on |
+| `/ccp:add-backlog <idea>` | Add an idea to the backlog parking lot (999.x numbering) |
+| `/ccp:review-backlog` | Review and promote backlog items to active milestone |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:pause-work` | Create context handoff when pausing work mid-phase |
+| `/ccp:resume-work` | Resume work from previous session with full context restoration |
+| `/ccp:cleanup` | Archive accumulated phase directories from completed milestones |
+| `/ccp:map-codebase` | Analyze codebase with parallel mapper agents to produce docs |
+| `/ccp:note <text>` | Zero-friction idea capture. Append, list, or promote notes to todos |
+| `/ccp:thread` | Manage persistent context threads for cross-session work |
+| `/ccp:plant-seed [idea]` | Capture a forward-looking idea with trigger conditions |
+| `/ccp:ship [phase]` | Create PR, run review, and prepare for merge after verification |
+| `/ccp:pr-branch [target]` | Create a clean PR branch by filtering out .planning/ commits |
+| `/ccp:session-report` | Generate a session report with token usage, summary, and outcomes |
+| `/ccp:milestone-summary` | Generate a comprehensive project summary from milestone artifacts |
+
+### UI Design
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:ui-phase` | Generate UI design contract (UI-SPEC.md) for frontend phases |
+| `/ccp:ui-review` | Retroactive 6-pillar visual audit of implemented frontend code |
+| `/ccp:plan-milestone-gaps` | Create phases to close gaps identified by milestone audit |
+
+---
+
+## Part 2: Development Workflow Commands (`/ccp:` prefix)
+
+These are utility commands for day-to-day development: code quality, testing, builds, sessions, and language-specific workflows.
+
+### Code Quality
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:code-review` | Comprehensive security and quality review of uncommitted changes |
+| `/ccp:tdd` | Enforce TDD workflow -- scaffold interfaces, generate tests first, then implement |
+| `/ccp:test-coverage` | Analyze test coverage, identify gaps, and generate missing tests for 80%+ |
+| `/ccp:refactor-clean` | Safely identify and remove dead code with test verification at every step |
+| `/ccp:prune` | Delete pending instincts older than 30 days that were never promoted |
+| `/ccp:rules-distill` | Scan skills to extract cross-cutting principles and distill them into rules |
+
+### Build & Fix
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:build-fix` | Incrementally fix build and type errors with minimal, safe changes |
+| `/ccp:e2e` | Generate and run end-to-end tests with Playwright |
+| `/ccp:docs` | Look up current documentation for a library or topic via Context7 |
+| `/ccp:update-docs` | Sync documentation with the codebase, generating from source-of-truth files |
+| `/ccp:update-codemaps` | Analyze codebase structure and generate token-lean architecture docs |
+
+### Planning & Orchestration
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:plan` | Restate requirements, assess risks, and create step-by-step implementation plan |
+| `/ccp:orchestrate` | Sequential and tmux/worktree guidance for multi-agent workflows |
+| `/ccp:aside` | Answer a quick side question without losing context from the current task |
+| `/ccp:context-budget` | Analyze context window usage and find optimization opportunities |
+| `/ccp:prompt-optimize` | Analyze a draft prompt and output an optimized version |
+
+### Sessions
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:save-session` | Save current session state to a dated file for future resumption |
+| `/ccp:resume-session` | Load the most recent session file and resume work with full context |
+| `/ccp:sessions` | Manage session history -- list, load, alias, and edit sessions |
+| `/ccp:checkpoint` | Create or verify a checkpoint in your workflow |
+
+### Evaluation & Skills
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:eval` | Manage eval-driven development workflow |
+| `/ccp:harness-audit` | Run a deterministic repository harness audit and return a scorecard |
+| `/ccp:skill-create` | Analyze git history to extract coding patterns and generate SKILL.md files |
+| `/ccp:skill-health` | Show skill portfolio health dashboard with charts and analytics |
+
+### Configuration & Setup
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:setup` | First-time project setup -- scan codebase, generate CLAUDE.md, install rules |
+| `/ccp:setup-refresh` | Re-scan codebase and update CLAUDE.md, rules, and architecture docs |
+| `/ccp:setup-pm` | Configure your preferred package manager (npm/pnpm/yarn/bun) |
+| `/ccp:tool-guide` | MCP tool recommendations per task type -- which tools to use when |
+| `/ccp:model-route` | Recommend the best model tier for the current task by complexity |
+| `/ccp:quality-gate` | Run the quality pipeline on demand for a file or project scope |
+| `/ccp:verify` | Run comprehensive verification on current codebase state |
+| `/ccp:learn` | Analyze current session and extract patterns worth saving as skills |
+| `/ccp:evolve` | Analyze instincts and suggest or generate evolved structures |
+
+### Language-Specific Workflows
+
+| Command | Description |
+|---------|-------------|
+| `/ccp:go-build` | Fix Go build errors, go vet warnings, and linter issues |
+| `/ccp:go-review` | Go code review for idiomatic patterns, concurrency, and security |
+| `/ccp:go-test` | TDD workflow for Go -- table-driven tests, 80%+ coverage |
+| `/ccp:rust-build` | Fix Rust build errors, borrow checker issues, and dependencies |
+| `/ccp:rust-review` | Rust code review for ownership, lifetimes, and idiomatic patterns |
+| `/ccp:rust-test` | TDD workflow for Rust -- tests first, 80%+ coverage with cargo-llvm-cov |
+| `/ccp:kotlin-build` | Fix Kotlin/Gradle build errors and dependency issues |
+| `/ccp:kotlin-review` | Kotlin code review for null safety, coroutines, and security |
+| `/ccp:kotlin-test` | TDD workflow for Kotlin -- Kotest tests, 80%+ coverage with Kover |
+| `/ccp:cpp-build` | Fix C++ build errors, CMake issues, and linker problems |
+| `/ccp:cpp-review` | C++ code review for memory safety, modern idioms, and concurrency |
+| `/ccp:cpp-test` | TDD workflow for C++ -- GoogleTest, coverage with gcov/lcov |
+| `/ccp:python-review` | Python code review for PEP 8, type hints, security, and idioms |
+| `/ccp:gradle-build` | Fix Gradle build errors for Android and KMP projects |
+
+---
+
+## Core Workflow
+
+```
+/ccp:new-project --> /ccp:plan-phase --> /ccp:execute-phase --> repeat
+```
+
+### Project Initialization
+
+**`/ccp:new-project`**
+Initialize new project through unified flow.
+
+One command takes you from idea to ready-for-planning:
+- Deep questioning to understand what you're building
+- Optional domain research (spawns 4 parallel researcher agents)
+- Requirements definition with v1/v2/out-of-scope scoping
+- Roadmap creation with phase breakdown and success criteria
+
+Creates all `.planning/` artifacts:
+- `PROJECT.md` -- vision and requirements
+- `config.json` -- workflow mode (interactive/yolo)
+- `research/` -- domain research (if selected)
+- `REQUIREMENTS.md` -- scoped requirements with REQ-IDs
+- `ROADMAP.md` -- phases mapped to requirements
+- `STATE.md` -- project memory
+
+Usage: `/ccp:new-project`
+
+**`/ccp:map-codebase`**
+Map an existing codebase for brownfield projects.
+
+- Analyzes codebase with parallel Explore agents
+- Creates `.planning/codebase/` with 7 focused documents
+- Covers stack, architecture, structure, conventions, testing, integrations, concerns
+- Use before `/ccp:new-project` on existing codebases
+
+Usage: `/ccp:map-codebase`
+
+### Phase Planning
+
+**`/ccp:discuss-phase <number>`**
+Help articulate your vision for a phase before planning.
+
+- Captures how you imagine this phase working
+- Creates CONTEXT.md with your vision, essentials, and boundaries
+- Use when you have ideas about how something should look/feel
+
+Usage: `/ccp:discuss-phase 2`
+
+**`/ccp:research-phase <number>`**
+Comprehensive ecosystem research for niche/complex domains.
+
+- Discovers standard stack, architecture patterns, pitfalls
+- Creates RESEARCH.md with "how experts build this" knowledge
+- Use for 3D, games, audio, shaders, ML, and other specialized domains
+- Goes beyond "which library" to ecosystem knowledge
+
+Usage: `/ccp:research-phase 3`
+
+**`/ccp:list-phase-assumptions <number>`**
+See what Claude is planning to do before it starts.
+
+- Shows Claude's intended approach for a phase
+- Lets you course-correct if Claude misunderstood your vision
+- No files created - conversational output only
+
+Usage: `/ccp:list-phase-assumptions 3`
+
+**`/ccp:plan-phase <number>`**
+Create detailed execution plan for a specific phase.
+
+- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
+- Breaks phase into concrete, actionable tasks
+- Includes verification criteria and success measures
+- Multiple plans per phase supported (XX-01, XX-02, etc.)
+
+Usage: `/ccp:plan-phase 1`
+Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
+
+**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase entirely. Your PRD becomes locked decisions in CONTEXT.md. Useful when you already have clear acceptance criteria.
+
+### Execution
+
+**`/ccp:execute-phase <phase-number>`**
+Execute all plans in a phase, or run a specific wave.
+
+- Groups plans by wave (from frontmatter), executes waves sequentially
+- Plans within each wave run in parallel via Task tool
+- Optional `--wave N` flag executes only Wave N and stops unless the phase is now fully complete
+- Verifies phase goal after all plans complete
+- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
+
+Usage: `/ccp:execute-phase 5`
+Usage: `/ccp:execute-phase 5 --wave 2`
+
+### Smart Router
+
+**`/ccp:do <description>`**
+Route freeform text to the right CCP command automatically.
+
+- Analyzes natural language input to find the best matching CCP command
+- Acts as a dispatcher -- never does the work itself
+- Resolves ambiguity by asking you to pick between top matches
+- Use when you know what you want but don't know which `/ccp:*` command to run
+
+Usage: `/ccp:do fix the login button`
+Usage: `/ccp:do refactor the auth system`
+
+### Quick Mode
+
+**`/ccp:quick [--full] [--discuss] [--research]`**
+Execute small, ad-hoc tasks with CCP guarantees but skip optional agents.
+
+Quick mode uses the same system with a shorter path:
+- Spawns planner + executor (skips researcher, checker, verifier by default)
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.md tracking (not ROADMAP.md)
+
+Flags enable additional quality steps:
+- `--discuss` -- Lightweight discussion to surface gray areas before planning
+- `--research` -- Focused research agent investigates approaches before planning
+- `--full` -- Adds plan-checking and post-execution verification
+
+Usage: `/ccp:quick`
+Usage: `/ccp:quick --research --full`
+Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
+
+---
+
+**`/ccp:fast [description]`**
+Execute a trivial task inline -- no subagents, no planning files, no overhead.
+
+For tasks too small to justify planning: typo fixes, config changes, forgotten commits, simple additions. Runs in the current context, makes the change, commits, and logs to STATE.md.
+
+- No PLAN.md or SUMMARY.md created
+- No subagent spawned (runs inline)
+- 3 or fewer file edits -- redirects to `/ccp:quick` if task is non-trivial
+- Atomic commit with conventional message
+
+Usage: `/ccp:fast "fix the typo in README"`
+Usage: `/ccp:fast "add .env to gitignore"`
+
+### Roadmap Management
+
+**`/ccp:add-phase <description>`**
+Add new phase to end of current milestone.
+
+- Appends to ROADMAP.md
+- Uses next sequential number
+- Updates phase directory structure
+
+Usage: `/ccp:add-phase "Add admin dashboard"`
+
+**`/ccp:insert-phase <after> <description>`**
+Insert urgent work as decimal phase between existing phases.
+
+- Creates intermediate phase (e.g., 7.1 between 7 and 8)
+- Useful for discovered work that must happen mid-milestone
+- Maintains phase ordering
+
+Usage: `/ccp:insert-phase 7 "Fix critical auth bug"`
+Result: Creates Phase 7.1
+
+**`/ccp:remove-phase <number>`**
+Remove a future phase and renumber subsequent phases.
+
+- Deletes phase directory and all references
+- Renumbers all subsequent phases to close the gap
+- Only works on future (unstarted) phases
+- Git commit preserves historical record
+
+Usage: `/ccp:remove-phase 17`
+Result: Phase 17 deleted, phases 18-20 become 17-19
+
+### Milestone Management
+
+**`/ccp:new-milestone <name>`**
+Start a new milestone through unified flow.
+
+- Deep questioning to understand what you're building next
+- Optional domain research (spawns 4 parallel researcher agents)
+- Requirements definition with scoping
+- Roadmap creation with phase breakdown
+- Optional `--reset-phase-numbers` flag restarts numbering at Phase 1
+
+Mirrors `/ccp:new-project` flow for brownfield projects (existing PROJECT.md).
+
+Usage: `/ccp:new-milestone "v2.0 Features"`
+Usage: `/ccp:new-milestone --reset-phase-numbers "v2.0 Features"`
+
+**`/ccp:complete-milestone <version>`**
+Archive completed milestone and prepare for next version.
+
+- Creates MILESTONES.md entry with stats
+- Archives full details to milestones/ directory
+- Creates git tag for the release
+- Prepares workspace for next version
+
+Usage: `/ccp:complete-milestone 1.0.0`
+
+### Progress Tracking
+
+**`/ccp:progress`**
+Check project status and intelligently route to next action.
+
+- Shows visual progress bar and completion percentage
+- Summarizes recent work from SUMMARY files
+- Displays current position and what's next
+- Lists key decisions and open issues
+- Offers to execute next plan or create it if missing
+- Detects 100% milestone completion
+
+Usage: `/ccp:progress`
+
+### Session Management
+
+**`/ccp:resume-work`**
+Resume work from previous session with full context restoration.
+
+- Reads STATE.md for project context
+- Shows current position and recent progress
+- Offers next actions based on project state
+
+Usage: `/ccp:resume-work`
+
+**`/ccp:pause-work`**
+Create context handoff when pausing work mid-phase.
+
+- Creates .continue-here file with current state
+- Updates STATE.md session continuity section
+- Captures in-progress work context
+
+Usage: `/ccp:pause-work`
+
+### Debugging
+
+**`/ccp:debug [issue description]`**
+Systematic debugging with persistent state across context resets.
+
+- Gathers symptoms through adaptive questioning
+- Creates `.planning/debug/[slug].md` to track investigation
+- Investigates using scientific method (evidence, hypothesis, test)
+- Survives `/clear` -- run `/ccp:debug` with no args to resume
+- Archives resolved issues to `.planning/debug/resolved/`
+
+Usage: `/ccp:debug "login button doesn't work"`
+Usage: `/ccp:debug` (resume active session)
+
+### Quick Notes
+
+**`/ccp:note <text>`**
+Zero-friction idea capture -- one command, instant save, no questions.
+
+- Saves timestamped note to `.planning/notes/` (or `~/.claude/notes/` globally)
+- Three subcommands: append (default), list, promote
+- Promote converts a note into a structured todo
+- Works without a project (falls back to global scope)
+
+Usage: `/ccp:note refactor the hook system`
+Usage: `/ccp:note list`
+Usage: `/ccp:note promote 3`
+Usage: `/ccp:note --global cross-project idea`
+
+### Todo Management
+
+**`/ccp:add-todo [description]`**
+Capture idea or task as todo from current conversation.
+
+- Extracts context from conversation (or uses provided description)
+- Creates structured todo file in `.planning/todos/pending/`
+- Infers area from file paths for grouping
+- Checks for duplicates before creating
+- Updates STATE.md todo count
+
+Usage: `/ccp:add-todo` (infers from conversation)
+Usage: `/ccp:add-todo Add auth token refresh`
+
+**`/ccp:check-todos [area]`**
+List pending todos and select one to work on.
+
+- Lists all pending todos with title, area, age
+- Optional area filter (e.g., `/ccp:check-todos api`)
+- Loads full context for selected todo
+- Routes to appropriate action (work now, add to phase, brainstorm)
+- Moves todo to done/ when work begins
+
+Usage: `/ccp:check-todos`
+Usage: `/ccp:check-todos api`
+
+### User Acceptance Testing
+
+**`/ccp:verify-work [phase]`**
+Validate built features through conversational UAT.
+
+- Extracts testable deliverables from SUMMARY.md files
+- Presents tests one at a time (yes/no responses)
+- Automatically diagnoses failures and creates fix plans
+- Ready for re-execution if issues found
+
+Usage: `/ccp:verify-work 3`
+
+### Ship Work
+
+**`/ccp:ship [phase]`**
+Create a PR from completed phase work with an auto-generated body.
+
+- Pushes branch to remote
+- Creates PR with summary from SUMMARY.md, VERIFICATION.md, REQUIREMENTS.md
+- Optionally requests code review
+- Updates STATE.md with shipping status
+
+Prerequisites: Phase verified, `gh` CLI installed and authenticated.
+
+Usage: `/ccp:ship 4` or `/ccp:ship 4 --draft`
+
+---
+
+**`/ccp:pr-branch [target]`**
+Create a clean branch for pull requests by filtering out .planning/ commits.
+
+- Classifies commits: code-only (include), planning-only (exclude), mixed (include sans .planning/)
+- Cherry-picks code commits onto a clean branch
+- Reviewers see only code changes, no CCP artifacts
+
+Usage: `/ccp:pr-branch` or `/ccp:pr-branch main`
+
+---
+
+**`/ccp:plant-seed [idea]`**
+Capture a forward-looking idea with trigger conditions for automatic surfacing.
+
+- Seeds preserve WHY, WHEN to surface, and breadcrumbs to related code
+- Auto-surfaces during `/ccp:new-milestone` when trigger conditions match
+- Better than deferred items -- triggers are checked, not forgotten
+
+Usage: `/ccp:plant-seed "add real-time notifications when we build the events system"`
+
+---
+
+**`/ccp:audit-uat`**
+Cross-phase audit of all outstanding UAT and verification items.
+- Scans every phase for pending, skipped, blocked, and human_needed items
+- Cross-references against codebase to detect stale documentation
+- Produces prioritized human test plan grouped by testability
+- Use before starting a new milestone to clear verification debt
+
+Usage: `/ccp:audit-uat`
+
+### Milestone Auditing
+
+**`/ccp:audit-milestone [version]`**
+Audit milestone completion against original intent.
+
+- Reads all phase VERIFICATION.md files
+- Checks requirements coverage
+- Spawns integration checker for cross-phase wiring
+- Creates MILESTONE-AUDIT.md with gaps and tech debt
+
+Usage: `/ccp:audit-milestone`
+
+**`/ccp:plan-milestone-gaps`**
+Create phases to close gaps identified by audit.
+
+- Reads MILESTONE-AUDIT.md and groups gaps into phases
+- Prioritizes by requirement priority (must/should/nice)
+- Adds gap closure phases to ROADMAP.md
+- Ready for `/ccp:plan-phase` on new phases
+
+Usage: `/ccp:plan-milestone-gaps`
+
+### Configuration
+
+**`/ccp:settings`**
+Configure workflow toggles and model profile interactively.
+
+- Toggle researcher, plan checker, verifier agents
+- Select model profile (quality/balanced/budget/inherit)
+- Updates `.planning/config.json`
+
+Usage: `/ccp:settings`
+
+**`/ccp:set-profile <profile>`**
+Quick switch model profile for CCP agents.
+
+- `quality` -- Opus everywhere except verification
+- `balanced` -- Opus for planning, Sonnet for execution (default)
+- `budget` -- Sonnet for writing, Haiku for research/verification
+- `inherit` -- Use current session model for all agents
+
+Usage: `/ccp:set-profile budget`
+
+### Utility Commands
+
+**`/ccp:cleanup`**
+Archive accumulated phase directories from completed milestones.
+
+- Identifies phases from completed milestones still in `.planning/phases/`
+- Shows dry-run summary before moving anything
+- Moves phase dirs to `.planning/milestones/v{X.Y}-phases/`
+- Use after multiple milestones to reduce `.planning/phases/` clutter
+
+Usage: `/ccp:cleanup`
+
+**`/ccp:help`**
+Show this command reference.
+
+**`/ccp:update`**
+Update CCP to latest version with changelog preview.
+
+- Shows installed vs latest version comparison
+- Displays changelog entries for versions you've missed
+- Highlights breaking changes
+- Confirms before running install
+- Better than raw `npx claude-code-pilot`
+
+Usage: `/ccp:update`
+
+## Files & Structure
+
+```
+.planning/
++-- PROJECT.md            # Project vision
++-- ROADMAP.md            # Current phase breakdown
++-- STATE.md              # Project memory & context
++-- RETROSPECTIVE.md      # Living retrospective (updated per milestone)
++-- config.json           # Workflow mode & gates
++-- todos/                # Captured ideas and tasks
+|   +-- pending/          # Todos waiting to be worked on
+|   +-- done/             # Completed todos
++-- debug/                # Active debug sessions
+|   +-- resolved/         # Archived resolved issues
++-- milestones/
+|   +-- v1.0-ROADMAP.md       # Archived roadmap snapshot
+|   +-- v1.0-REQUIREMENTS.md  # Archived requirements
+|   +-- v1.0-phases/          # Archived phase dirs (via /ccp:cleanup or --archive-phases)
+|       +-- 01-foundation/
+|       +-- 02-core-features/
++-- codebase/             # Codebase map (brownfield projects)
+|   +-- STACK.md          # Languages, frameworks, dependencies
+|   +-- ARCHITECTURE.md   # Patterns, layers, data flow
+|   +-- STRUCTURE.md      # Directory layout, key files
+|   +-- CONVENTIONS.md    # Coding standards, naming
+|   +-- TESTING.md        # Test setup, patterns
+|   +-- INTEGRATIONS.md   # External services, APIs
+|   +-- CONCERNS.md       # Tech debt, known issues
++-- phases/
+    +-- 01-foundation/
+    |   +-- 01-01-PLAN.md
+    |   +-- 01-01-SUMMARY.md
+    +-- 02-core-features/
+        +-- 02-01-PLAN.md
+        +-- 02-01-SUMMARY.md
+```
+
+## Workflow Modes
+
+Set during `/ccp:new-project`:
+
+**Interactive Mode**
+
+- Confirms each major decision
+- Pauses at checkpoints for approval
+- More guidance throughout
+
+**YOLO Mode**
+
+- Auto-approves most decisions
+- Executes plans without confirmation
+- Only stops for critical checkpoints
+
+Change anytime by editing `.planning/config.json`
+
+## Planning Configuration
+
+Configure how planning artifacts are managed in `.planning/config.json`:
+
+**`planning.commit_docs`** (default: `true`)
+- `true`: Planning artifacts committed to git (standard workflow)
+- `false`: Planning artifacts kept local-only, not committed
+
+When `commit_docs: false`:
+- Add `.planning/` to your `.gitignore`
+- Useful for OSS contributions, client projects, or keeping planning private
+- All planning files still work normally, just not tracked in git
+
+**`planning.search_gitignored`** (default: `false`)
+- `true`: Add `--no-ignore` to broad ripgrep searches
+- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
+
+Example config:
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "search_gitignored": true
+  }
+}
+```
+
+## Common Workflows
+
+**Starting a new project:**
+
+```
+/ccp:new-project        # Unified flow: questioning -> research -> requirements -> roadmap
+/clear
+/ccp:plan-phase 1       # Create plans for first phase
+/clear
+/ccp:execute-phase 1    # Execute all plans in phase
+```
+
+**Resuming work after a break:**
+
+```
+/ccp:progress  # See where you left off and continue
+```
+
+**Adding urgent mid-milestone work:**
+
+```
+/ccp:insert-phase 5 "Critical security fix"
+/ccp:plan-phase 5.1
+/ccp:execute-phase 5.1
+```
+
+**Completing a milestone:**
+
+```
+/ccp:complete-milestone 1.0.0
+/clear
+/ccp:new-milestone  # Start next milestone (questioning -> research -> requirements -> roadmap)
+```
+
+**Capturing ideas during work:**
+
+```
+/ccp:add-todo                    # Capture from conversation context
+/ccp:add-todo Fix modal z-index  # Capture with explicit description
+/ccp:check-todos                 # Review and work on todos
+/ccp:check-todos api             # Filter by area
+```
+
+**Debugging an issue:**
+
+```
+/ccp:debug "form submission fails silently"  # Start debug session
+# ... investigation happens, context fills up ...
+/clear
+/ccp:debug                                    # Resume from where you left off
+```
+
+## Getting Help
+
+- Read `.planning/PROJECT.md` for project vision
+- Read `.planning/STATE.md` for current context
+- Check `.planning/ROADMAP.md` for phase status
+- Run `/ccp:progress` to check where you're up to
+</reference>