.planning/ directory.
/gsd-new-milestone [name]
Start a new version cycle for an existing project.
Syntax
/gsd-new-project. Your project already exists and PROJECT.md has its history. This command gathers what’s next, updates PROJECT.md with the new milestone goals, then runs a full requirements → roadmap cycle. Phase numbering continues from where the previous milestone left off unless you reset it.
Produces
| Artifact | Purpose |
|---|---|
.planning/PROJECT.md | Updated with new milestone goals |
.planning/REQUIREMENTS.md | Scoped requirements for this milestone |
.planning/ROADMAP.md | Phase structure (continuing numbering) |
.planning/STATE.md | Reset for the new milestone |
.planning/research/ | Domain research for new features (optional) |
Restart phase numbering from 1 for the new milestone instead of continuing from the last milestone’s final phase number.
/gsd-plan-phase [N] to begin the first phase of the new milestone.
/gsd-milestone-summary [version]
Generate a comprehensive milestone report for team onboarding and review.
Syntax
ROADMAP.md, REQUIREMENTS.md, CONTEXT.md, SUMMARY.md, VERIFICATION.md, RESEARCH.md, and RETROSPECTIVE.md files — and produces a structured seven-section human-friendly overview of what was built, how, and why. After generation, offers an interactive Q&A session so new team members can explore the context further. Omit the version to default to the current or latest milestone.
Produces
.planning/reports/MILESTONE_SUMMARY-v{version}.md covering: Overview, Architecture, Phases, Key Decisions, Requirements, Tech Debt, and Getting Started.
/gsd-complete-milestone
Archive a completed milestone and prepare for the next version.
Syntax
SUMMARY.md files, gathering stats (phase count, plan count, git range, LOC, timeline), archiving the roadmap and requirements to .planning/milestones/, collapsing ROADMAP.md to a single summary line, updating PROJECT.md with the shipped version, and tagging the release in git. Checks for a passing audit before proceeding — if no audit exists it recommends running /gsd-audit-milestone first.
Produces
| Artifact | Purpose |
|---|---|
.planning/milestones/v{ver}-ROADMAP.md | Archived roadmap for this milestone |
.planning/milestones/v{ver}-REQUIREMENTS.md | Archived requirements with completion status |
git tag v{ver} | Version tag (if git.create_tag is enabled) |
/gsd-audit-milestone
Verify a milestone met its definition of done before archiving.
Syntax
VERIFICATION.md files from all completed phases, checks requirements coverage, identifies tech debt and deferred gaps, then spawns an integration checker to verify cross-phase wiring. Produces a structured audit report with a passed or gaps_found status. Run this before /gsd-complete-milestone. Omit the version to audit the current milestone.
Produces
.planning/v{version}-MILESTONE-AUDIT.md — coverage report with status verdict, gap list, and recommended remediation steps.
/gsd-phase
CRUD operations for phases in ROADMAP.md.
Syntax
--insert it creates a decimal phase (e.g., 3.1) between existing phases for urgent work. With --remove it deletes a future phase and renumbers subsequent phases. With --edit it updates fields of an existing phase in place.
Flags
Insert an urgent work phase as a decimal (e.g.,
3.1) immediately after phase N. Pass the description as the remaining argument.Remove future phase
N and renumber all subsequent phases to keep the sequence clean.Edit any field of existing phase
N in place — name, goal, complexity, or mode.Skip the confirmation gate when editing. Use with
--edit only./gsd-mvp-phase N
Guide MVP vertical-slice planning for an existing phase.
Syntax
ROADMAP.md with **Mode:** mvp, then delegates to /gsd-plan-phase which auto-detects MVP mode. The phase must already exist in ROADMAP.md — this command converts an existing phase, it does not create new ones.
/gsd-resume-work
Restore full context from your last session and resume where you left off.
Syntax
STATE.md (or reconstructs it if missing), detects any .continue-here checkpoint files left by /gsd-pause-work, finds incomplete plans that have no corresponding SUMMARY.md, presents your current status, and routes you to the most appropriate next action.
/gsd-pause-work
Save a complete context handoff before ending a session.
Syntax
.continue-here.md handoff file that captures your exact position in the phase, all work completed so far, remaining tasks, key decisions made, and any active blockers. Commits the file as a WIP commit and prints resume instructions for your next session.
Flags
Generate a session report (
SESSION_REPORT.md) summarizing what was accomplished this session, in addition to creating the standard handoff file./gsd-manager
Interactive multi-phase command center for power users.
Syntax
Run a dependency analysis across all phases before opening the dashboard. Shows which phases block others and recommends an optimal execution order.
/gsd-health
Validate .planning/ directory integrity and diagnose issues.
Syntax
.planning/ directory for missing required files, invalid config.json values, inconsistent state, and orphaned plan files. Reports every issue with an actionable fix suggestion. With --repair it automatically resolves any issues it can fix safely.
Flags
Automatically repair any issues that can be safely fixed — missing directories, malformed state entries, and orphaned artifacts.
Check the current session’s context utilization instead of the
.planning/ directory. Reports one of three states: healthy (under 60%), warning (60–70%, recommend starting a new thread with /gsd-thread), or critical (70%+, reasoning quality may degrade)./gsd-stats
Display a project statistics dashboard.
Syntax
.planning/ directory and git history to display comprehensive project metrics: phase progress, plan execution counts, requirements completion percentage, git commit stats, file change counts, lines of code, and project timeline. No arguments or flags needed — run it any time you want a snapshot of where the project stands.