New command that generates a comprehensive project summary from completed
milestone artifacts. Designed for team onboarding — new contributors can
run this against a completed project and understand what was built, how,
and why, with optional interactive Q&A grounded in build artifacts.
- commands/gsd/milestone-summary.md: command definition
- get-shit-done/workflows/milestone-summary.md: 9-step workflow
- tests/milestone-summary.test.cjs: 11 tests (command + workflow validation)
- tests/copilot-install.test.cjs: bump expected skill count 53→54
Reads: ROADMAP, REQUIREMENTS, PROJECT, CONTEXT, SUMMARY, VERIFICATION,
RETROSPECTIVE artifacts. Writes to .planning/reports/MILESTONE_SUMMARY-v{X}.md.
Closes #1298
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5.7 KiB
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
VERSION="$ARGUMENTS"
If $ARGUMENTS is empty:
- Check
.planning/STATE.mdfor current milestone version - Check
.planning/milestones/for the latest archived version - If neither found, check if
.planning/ROADMAP.mdexists (project may be mid-milestone) - If nothing found: error "No milestone found. Run /gsd:new-project or /gsd: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/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"
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:
gsd-tools.cjs init progress
This returns phase metadata. For each phase in the milestone scope:
- Read
{phase_dir}/{padded}-SUMMARY.mdif it exists — extractone_liner,accomplishments,decisions - Read
{phase_dir}/{padded}-VERIFICATION.mdif it exists — extract status, gaps, deferred items - Read
{phase_dir}/{padded}-CONTEXT.mdif it exists — extract key decisions from<decisions>section - Read
{phase_dir}/{padded}-RESEARCH.mdif it exists — note what was researched
Track which phases have which artifacts.
Step 4: Gather Git Statistics
# If milestone is tagged
git log v${VERSION} --oneline | wc -l
git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
# If not tagged, use date range from STATE.md or earliest phase commit
git log --oneline --since="<milestone_start>" | wc -l
Extract:
- 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:
# 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: Commit
gsd-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:
/gsd:new-milestone,/gsd:progress, or sharing the summary with the team
Step 9: Update STATE.md
gsd-tools.cjs state record-session \
--stopped-at "Milestone v${VERSION} summary generated" \
--resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"