claude-code-pilot 2.0.0 → 3.1.0

package/src/pilot/workflows/milestone-summary.md

@@ -0,0 +1,223 @@
+# Milestone Summary Workflow
+
+Generate a comprehensive, human-friendly project summary from completed milestone artifacts.
+Designed for team onboarding — a new contributor can read the output and understand the entire project.
+
+---
+
+## Step 1: Resolve Version
+
+```bash
+VERSION="$ARGUMENTS"
+```
+
+If `$ARGUMENTS` is empty:
+1. Check `.planning/STATE.md` for current milestone version
+2. Check `.planning/milestones/` for the latest archived version
+3. If neither found, check if `.planning/ROADMAP.md` exists (project may be mid-milestone)
+4. If nothing found: error "No milestone found. Run /ccp:new-project or /ccp:new-milestone first."
+
+Set `VERSION` to the resolved version (e.g., "1.0").
+
+## Step 2: Locate Artifacts
+
+Determine whether the milestone is **archived** or **current**:
+
+**Archived milestone** (`.planning/milestones/v{VERSION}-ROADMAP.md` exists):
+```
+ROADMAP_PATH=".planning/milestones/v${VERSION}-ROADMAP.md"
+REQUIREMENTS_PATH=".planning/milestones/v${VERSION}-REQUIREMENTS.md"
+AUDIT_PATH=".planning/milestones/v${VERSION}-MILESTONE-AUDIT.md"
+```
+
+**Current/in-progress milestone** (no archive yet):
+```
+ROADMAP_PATH=".planning/ROADMAP.md"
+REQUIREMENTS_PATH=".planning/REQUIREMENTS.md"
+AUDIT_PATH=".planning/v${VERSION}-MILESTONE-AUDIT.md"
+```
+
+Note: The audit file moves to `.planning/milestones/` on archive (per `complete-milestone` workflow). Check both locations as a fallback.
+
+**Always available:**
+```
+PROJECT_PATH=".planning/PROJECT.md"
+RETRO_PATH=".planning/RETROSPECTIVE.md"
+STATE_PATH=".planning/STATE.md"
+```
+
+Read all files that exist. Missing files are fine — the summary adapts to what's available.
+
+## Step 3: Discover Phase Artifacts
+
+Find all phase directories:
+
+```bash
+ccp-tools.cjs init progress
+```
+
+This returns phase metadata. For each phase in the milestone scope:
+
+- Read `{phase_dir}/{padded}-SUMMARY.md` if it exists — extract `one_liner`, `accomplishments`, `decisions`
+- Read `{phase_dir}/{padded}-VERIFICATION.md` if it exists — extract status, gaps, deferred items
+- Read `{phase_dir}/{padded}-CONTEXT.md` if it exists — extract key decisions from `<decisions>` section
+- Read `{phase_dir}/{padded}-RESEARCH.md` if it exists — note what was researched
+
+Track which phases have which artifacts.
+
+**If no phase directories exist** (empty milestone or pre-build state): skip to Step 5 and generate a minimal summary noting "No phases have been executed yet." Do not error — the summary should still capture PROJECT.md and ROADMAP.md content.
+
+## Step 4: Gather Git Statistics
+
+Try each method in order until one succeeds:
+
+**Method 1 — Tagged milestone** (check first):
+```bash
+git tag -l "v${VERSION}" | head -1
+```
+If the tag exists:
+```bash
+git log v${VERSION} --oneline | wc -l
+git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
+```
+
+**Method 2 — STATE.md date range** (if no tag):
+Read STATE.md and extract the `started_at` or earliest session date. Use it as the `--since` boundary:
+```bash
+git log --oneline --since="<started_at_date>" | wc -l
+```
+
+**Method 3 — Earliest phase commit** (if STATE.md has no date):
+Find the earliest `.planning/phases/` commit:
+```bash
+git log --oneline --diff-filter=A -- ".planning/phases/" | tail -1
+```
+Use that commit's date as the start boundary.
+
+**Method 4 — Skip stats** (if none of the above work):
+Report "Git statistics unavailable — no tag or date range could be determined." This is not an error — the summary continues without the Stats section.
+
+Extract (when available):
+- Total commits in milestone
+- Files changed, insertions, deletions
+- Timeline (start date → end date)
+- Contributors (from git log authors)
+
+## Step 5: Generate Summary Document
+
+Write to `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md`:
+
+```markdown
+# Milestone v{VERSION} — Project Summary
+
+**Generated:** {date}
+**Purpose:** Team onboarding and project review
+
+---
+
+## 1. Project Overview
+
+{From PROJECT.md: "What This Is", core value proposition, target users}
+{If mid-milestone: note which phases are complete vs in-progress}
+
+## 2. Architecture & Technical Decisions
+
+{From CONTEXT.md files across phases: key technical choices}
+{From SUMMARY.md decisions: patterns, libraries, frameworks chosen}
+{From PROJECT.md: tech stack if documented}
+
+Present as a bulleted list of decisions with brief rationale:
+- **Decision:** {what was chosen}
+  - **Why:** {rationale from CONTEXT.md}
+  - **Phase:** {which phase made this decision}
+
+## 3. Phases Delivered
+
+| Phase | Name | Status | One-Liner |
+|-------|------|--------|-----------|
+{For each phase: number, name, status (complete/in-progress/planned), one_liner from SUMMARY.md}
+
+## 4. Requirements Coverage
+
+{From REQUIREMENTS.md: list each requirement with status}
+- ✅ {Requirement met}
+- ⚠️ {Requirement partially met — note gap}
+- ❌ {Requirement not met — note reason}
+
+{If MILESTONE-AUDIT.md exists: include audit verdict}
+
+## 5. Key Decisions Log
+
+{Aggregate from all CONTEXT.md <decisions> sections}
+{Each decision with: ID, description, phase, rationale}
+
+## 6. Tech Debt & Deferred Items
+
+{From VERIFICATION.md files: gaps found, anti-patterns noted}
+{From RETROSPECTIVE.md: lessons learned, what to improve}
+{From CONTEXT.md <deferred> sections: ideas parked for later}
+
+## 7. Getting Started
+
+{Entry points for new contributors:}
+- **Run the project:** {from PROJECT.md or SUMMARY.md}
+- **Key directories:** {from codebase structure}
+- **Tests:** {test command from PROJECT.md or CLAUDE.md}
+- **Where to look first:** {main entry points, core modules}
+
+---
+
+## Stats
+
+- **Timeline:** {start} → {end} ({duration})
+- **Phases:** {count complete} / {count total}
+- **Commits:** {count}
+- **Files changed:** {count} (+{insertions} / -{deletions})
+- **Contributors:** {list}
+```
+
+## Step 6: Write and Commit
+
+**Overwrite guard:** If `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md` already exists, ask the user:
+> "A milestone summary for v{VERSION} already exists. Overwrite it, or view the existing one?"
+If "view": display existing file and skip to Step 8 (interactive mode). If "overwrite": proceed.
+
+Create the reports directory if needed:
+```bash
+mkdir -p .planning/reports
+```
+
+Write the summary, then commit:
+```bash
+ccp-tools.cjs commit "docs(v${VERSION}): generate milestone summary for onboarding" \
+  --files ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
+```
+
+## Step 7: Present Summary
+
+Display the full summary document inline.
+
+## Step 8: Offer Interactive Mode
+
+After presenting the summary:
+
+> "Summary written to `.planning/reports/MILESTONE_SUMMARY-v{VERSION}.md`.
+>
+> I have full context from the build artifacts. Want to ask anything about the project?
+> Architecture decisions, specific phases, requirements, tech debt — ask away."
+
+If the user asks questions:
+- Answer from the artifacts already loaded (CONTEXT.md, SUMMARY.md, VERIFICATION.md, etc.)
+- Reference specific files and decisions
+- Stay grounded in what was actually built (not speculation)
+
+If the user is done:
+- Suggest next steps: `/ccp:new-milestone`, `/ccp:progress`, or sharing the summary with the team
+
+## Step 9: Update STATE.md
+
+```bash
+ccp-tools.cjs state record-session \
+  --stopped-at "Milestone v${VERSION} summary generated" \
+  --resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
+```

package/{gsd/get-shit-done → src/pilot}/workflows/new-milestone.md

@@ -10,14 +10,27 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 </required_reading>
 
+<available_agent_types>
+Valid CCP subagent types (use exact names — do not fall back to 'general-purpose'):
+- ccp-project-researcher — Researches project-level technical decisions
+- ccp-research-synthesizer — Synthesizes findings from parallel research agents
+- ccp-roadmapper — Creates phased execution roadmaps
+</available_agent_types>
+
 <process>
 
 ## 1. Load Context
 
+Parse `$ARGUMENTS` before doing anything else:
+- `--reset-phase-numbers` flag → opt into restarting roadmap phase numbering at `1`
+- remaining text → use as milestone name if present
+
+If the flag is absent, keep the current behavior of continuing phase numbering from the previous milestone.
+
 - Read PROJECT.md (existing project, validated requirements, decisions)
 - Read MILESTONES.md (what shipped previously)
 - Read STATE.md (pending todos, blockers)
-- Check for MILESTONE-CONTEXT.md (from /gsd:discuss-milestone)
+- Check for MILESTONE-CONTEXT.md (from /ccp:discuss-milestone)
 
 ## 2. Gather Milestone Goals
 
@@ -37,6 +50,38 @@ Read all files referenced by the invoking prompt's execution_context before star
 - Suggest next version (v1.0 → v1.1, or v2.0 for major)
 - Confirm with user
 
+## 3.5. Verify Milestone Understanding
+
+Before writing any files, present a summary of what was gathered and ask for confirmation.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Pilot ► MILESTONE SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Milestone v[X.Y]: [Name]**
+
+**Goal:** [One sentence]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+**Key context:** [Any important constraints, decisions, or notes from questioning]
+```
+
+AskUserQuestion:
+- header: "Confirm?"
+- question: "Does this capture what you want to build in this milestone?"
+- options:
+  - "Looks good" — Proceed to write PROJECT.md
+  - "Adjust" — Let me correct or add details
+
+**If "Adjust":** Ask what needs changing (plain text, NOT AskUserQuestion). Incorporate changes, re-present the summary. Loop until "Looks good" is selected.
+
+**If "Looks good":** Proceed to Step 4.
+
 ## 4. Update PROJECT.md
 
 Add/update:
@@ -54,6 +99,27 @@ Add/update:
 
 Update Active requirements section and "Last updated" footer.
 
+Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects created before this feature), add it before the footer:
+
+```markdown
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via transition workflow):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/ccp:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+```
+
 ## 5. Update STATE.md
 
 ```markdown
@@ -72,39 +138,64 @@ Keep Accumulated Context section from previous milestone.
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
 ```
 
 ## 7. Load Context and Resolve Models
 
 ```bash
-INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init new-milestone)
+INIT=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" init new-milestone)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_RESEARCHER=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" agent-skills ccp-project-researcher 2>/dev/null)
+AGENT_SKILLS_SYNTHESIZER=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" agent-skills ccp-synthesizer 2>/dev/null)
+AGENT_SKILLS_ROADMAPPER=$(node "$HOME/.claude/pilot/bin/ccp-tools.cjs" agent-skills ccp-roadmapper 2>/dev/null)
+```
+
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`.
+
+## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
+
+If `--reset-phase-numbers` is active:
+
+1. Set starting phase number to `1` for the upcoming roadmap.
+2. If `phase_dir_count > 0`, archive the old phase directories before roadmapping so new `01-*` / `02-*` directories cannot collide with stale milestone directories.
+
+If `phase_dir_count > 0` and `phase_archive_path` is available:
+
+```bash
+mkdir -p "${phase_archive_path}"
+find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "${phase_archive_path}/" \;
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
+Then verify `.planning/phases/` no longer contains old milestone directories before continuing.
+
+If `phase_dir_count > 0` but `phase_archive_path` is missing:
+- Stop and explain that reset numbering is unsafe without a completed milestone archive target.
+- Tell the user to complete/archive the previous milestone first, then rerun `/ccp:new-milestone --reset-phase-numbers`.
 
 ## 8. Research Decision
 
+Check `research_enabled` from init JSON (loaded from config).
+
+**If `research_enabled` is `true`:**
+
 AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
 - "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
-- "Skip research" — Go straight to requirements
+- "Skip research for this milestone" — Go straight to requirements (does not change your default)
 
-**Persist choice to config** (so future `/gsd:plan-phase` honors it):
+**If `research_enabled` is `false`:**
 
-```bash
-# If "Research first": persist true
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research true
+AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
+- "Skip research (current default)" — Go straight to requirements
+- "Research first" — Discover patterns, features, architecture for NEW capabilities
 
-# If "Skip research": persist false
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research false
-```
+**IMPORTANT:** Do NOT persist this choice to config.json. The `workflow.research` setting is a persistent user preference that controls plan-phase behavior across the project. Changing it here would silently alter future `/ccp:plan-phase` behavior. To change the default, use `/ccp:settings`.
 
-**If "Research first":**
+**If user chose "Research first":**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► RESEARCHING
+ Pilot ► RESEARCHING
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Spawning 4 researchers in parallel...
@@ -115,7 +206,7 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.researc
 mkdir -p .planning/research
 ```
 
-Spawn 4 parallel gsd-project-researcher agents. Each uses this template with dimension-specific fields:
+Spawn 4 parallel ccp-project-researcher agents. Each uses this template with dimension-specific fields:
 
 **Common structure for all 4 researchers:**
 ```
@@ -134,15 +225,17 @@ Focus ONLY on what's needed for the NEW features.
 - .planning/PROJECT.md (Project context)
 </files_to_read>
 
+${AGENT_SKILLS_RESEARCHER}
+
 <downstream_consumer>{CONSUMER}</downstream_consumer>
 
 <quality_gate>{GATES}</quality_gate>
 
 <output>
 Write to: .planning/research/{FILE}
-Use template: ~/.claude/get-shit-done/templates/research-project/{FILE}
+Use template: ~/.claude/pilot/templates/research-project/{FILE}
 </output>
-", subagent_type="gsd-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+", subagent_type="ccp-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
 ```
 
 **Dimension-specific fields:**
@@ -168,16 +261,18 @@ Synthesize research outputs into SUMMARY.md.
 - .planning/research/PITFALLS.md
 </files_to_read>
 
+${AGENT_SKILLS_SYNTHESIZER}
+
 Write to: .planning/research/SUMMARY.md
-Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
+Use template: ~/.claude/pilot/templates/research-project/SUMMARY.md
 Commit after writing.
-", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+", subagent_type="ccp-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
 ```
 
 Display key findings from SUMMARY.md:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► RESEARCH COMPLETE ✓
+ Pilot ► RESEARCH COMPLETE ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Stack additions:** [from SUMMARY.md]
@@ -191,7 +286,7 @@ Display key findings from SUMMARY.md:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► DEFINING REQUIREMENTS
+ Pilot ► DEFINING REQUIREMENTS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -255,20 +350,22 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► CREATING ROADMAP
+ Pilot ► CREATING ROADMAP
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Spawning roadmapper...
 ```
 
-**Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
+**Starting phase number:**
+- If `--reset-phase-numbers` is active, start at **Phase 1**
+- Otherwise, continue from the previous milestone's last phase number (v1.0 ended at phase 5 → v1.1 starts at phase 6)
 
 ```
 Task(prompt="
@@ -280,11 +377,16 @@ Task(prompt="
 - .planning/config.json
 - .planning/MILESTONES.md
 </files_to_read>
+
+${AGENT_SKILLS_ROADMAPPER}
+
 </planning_context>
 
 <instructions>
 Create roadmap for milestone v[X.Y]:
-1. Start phase numbering from [N]
+1. Respect the selected numbering mode:
+   - `--reset-phase-numbers` → start at Phase 1
+   - default behavior → continue from the previous milestone's last phase number
 2. Derive phases from THIS MILESTONE's requirements only
 3. Map every requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
@@ -294,7 +396,7 @@ Create roadmap for milestone v[X.Y]:
 
 Write files first, then return.
 </instructions>
-", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+", subagent_type="ccp-roadmapper", model="{roadmapper_model}", description="Create roadmap")
 ```
 
 **Handle return:**
@@ -332,14 +434,14 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+node "$HOME/.claude/pilot/bin/ccp-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
 ## 11. Done
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► MILESTONE INITIALIZED ✓
+ Pilot ► MILESTONE INITIALIZED ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Milestone v[X.Y]: [Name]**
@@ -357,11 +459,11 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: create milest
 
 **Phase [N]: [Phase Name]** — [Goal]
 
-`/gsd:discuss-phase [N]` — gather context and clarify approach
+`/ccp:discuss-phase [N]` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
-Also: `/gsd:plan-phase [N]` — skip discussion, plan directly
+Also: `/ccp:plan-phase [N]` — skip discussion, plan directly
 ```
 
 </process>
@@ -373,12 +475,12 @@ Also: `/gsd:plan-phase [N]` — skip discussion, plan directly
 - [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
 - [ ] Requirements gathered and scoped per category
 - [ ] REQUIREMENTS.md created with REQ-IDs
-- [ ] gsd-roadmapper spawned with phase numbering context
+- [ ] ccp-roadmapper spawned with phase numbering context
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md phases continue from previous milestone
+- [ ] Phase numbering mode respected (continued or reset)
 - [ ] All commits made (if planning docs committed)
-- [ ] User knows next step: `/gsd:discuss-phase [N]`
+- [ ] User knows next step: `/ccp:discuss-phase [N]`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>