refactor: update commands, workflows, agents for gsd-tools integration

Commands (15): audit-milestone, complete-milestone, debug, execute-phase,
help, insert-phase, new-milestone, new-project, plan-milestone-gaps,
plan-phase, progress, quick, remove-phase, research-phase, verify-work

Workflows (22): execute-plan (69% reduction), verify-phase (55%), others
Agents (14): All updated for new workflow structure

Total token savings: ~22k chars (75.6% in affected sections)

Ported from: get-shit-done-v2@d1fb2d5, 7f79a9b
This commit is contained in:
TÂCHES
2026-02-07 11:08:45 -06:00
parent d2623e0114
commit d44c7dcc9b
44 changed files with 4941 additions and 10374 deletions

View File

@@ -0,0 +1,234 @@
<purpose>
Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
## 0. Resolve Model Profile
```bash
CHECKER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-integration-checker --raw)
```
## 1. Determine Milestone Scope
```bash
# Get phases in milestone
ls -d .planning/phases/*/ | sort -V
```
- Parse version from arguments or detect current from ROADMAP.md
- Identify all phase directories in scope
- Extract milestone definition of done from ROADMAP.md
- Extract requirements mapped to this milestone from REQUIREMENTS.md
## 2. Read All Phase Verifications
For each phase directory, read the VERIFICATION.md:
```bash
cat .planning/phases/01-*/*-VERIFICATION.md
cat .planning/phases/02-*/*-VERIFICATION.md
# etc.
```
From each VERIFICATION.md, extract:
- **Status:** passed | gaps_found
- **Critical gaps:** (if any — these are blockers)
- **Non-critical gaps:** tech debt, deferred items, warnings
- **Anti-patterns found:** TODOs, stubs, placeholders
- **Requirements coverage:** which requirements satisfied/blocked
If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
## 3. Spawn Integration Checker
With phase context collected:
```
Task(
prompt="Check cross-phase integration and E2E flows.
Phases: {phase_dirs}
Phase exports: {from SUMMARYs}
API routes: {routes created}
Verify cross-phase wiring and E2E user flows.",
subagent_type="gsd-integration-checker",
model="{integration_checker_model}"
)
```
## 4. Collect Results
Combine:
- Phase-level gaps and tech debt (from step 2)
- Integration checker's report (wiring gaps, broken flows)
## 5. Check Requirements Coverage
For each requirement in REQUIREMENTS.md mapped to this milestone:
- Find owning phase
- Check phase verification status
- Determine: satisfied | partial | unsatisfied
## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:
```yaml
---
milestone: {version}
audited: {timestamp}
status: passed | gaps_found | tech_debt
scores:
requirements: N/M
phases: N/M
integration: N/M
flows: N/M
gaps: # Critical blockers
requirements: [...]
integration: [...]
flows: [...]
tech_debt: # Non-critical, deferred
- phase: 01-auth
items:
- "TODO: add rate limiting"
- "Warning: no password strength validation"
- phase: 03-dashboard
items:
- "Deferred: mobile responsive layout"
---
```
Plus full markdown report with tables for requirements, phases, integration, tech debt.
**Status values:**
- `passed` — all requirements met, no critical gaps, minimal tech debt
- `gaps_found` — critical blockers exist
- `tech_debt` — no blockers but accumulated deferred items need review
## 7. Present Results
Route by status (see `<offer_next>`).
</process>
<offer_next>
Output this markdown directly (not as a code block). Route based on status:
---
**If passed:**
## ✓ Milestone {version} — Audit Passed
**Score:** {N}/{M} requirements satisfied
**Report:** .planning/v{version}-MILESTONE-AUDIT.md
All requirements covered. Cross-phase integration verified. E2E flows complete.
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Complete milestone** — archive and tag
/gsd:complete-milestone {version}
<sub>/clear first → fresh context window</sub>
───────────────────────────────────────────────────────────────
---
**If gaps_found:**
## ⚠ Milestone {version} — Gaps Found
**Score:** {N}/{M} requirements satisfied
**Report:** .planning/v{version}-MILESTONE-AUDIT.md
### Unsatisfied Requirements
{For each unsatisfied requirement:}
- **{REQ-ID}: {description}** (Phase {X})
- {reason}
### Cross-Phase Issues
{For each integration gap:}
- **{from} → {to}:** {issue}
### Broken Flows
{For each flow gap:}
- **{flow name}:** breaks at {step}
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Plan gap closure** — create phases to complete milestone
/gsd:plan-milestone-gaps
<sub>/clear first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
- /gsd:complete-milestone {version} — proceed anyway (accept tech debt)
───────────────────────────────────────────────────────────────
---
**If tech_debt (no blockers but accumulated debt):**
## ⚡ Milestone {version} — Tech Debt Review
**Score:** {N}/{M} requirements satisfied
**Report:** .planning/v{version}-MILESTONE-AUDIT.md
All requirements met. No critical blockers. Accumulated tech debt needs review.
### Tech Debt by Phase
{For each phase with debt:}
**Phase {X}: {name}**
- {item 1}
- {item 2}
### Total: {N} items across {M} phases
───────────────────────────────────────────────────────────────
## ▶ Options
**A. Complete milestone** — accept debt, track in backlog
/gsd:complete-milestone {version}
**B. Plan cleanup phase** — address debt before completing
/gsd:plan-milestone-gaps
<sub>/clear first → fresh context window</sub>
───────────────────────────────────────────────────────────────
</offer_next>
<success_criteria>
- [ ] Milestone scope identified
- [ ] All phase VERIFICATION.md files read
- [ ] Tech debt and deferred gaps aggregated
- [ ] Integration checker spawned for cross-phase wiring
- [ ] v{version}-MILESTONE-AUDIT.md created
- [ ] Results presented with actionable next steps
</success_criteria>

View File

@@ -1,15 +1,11 @@
<purpose>
Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
This is the ritual that separates "development" from "shipped."
Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
</purpose>
<required_reading>
**Read these files NOW:**
1. templates/milestone.md
2. templates/milestone-archive.md
3. `.planning/ROADMAP.md`
@@ -20,28 +16,20 @@ This is the ritual that separates "development" from "shipped."
<archival_behavior>
When a milestone completes, this workflow:
When a milestone completes:
1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
3. Updates ROADMAP.md to replace milestone details with one-line summary
4. Deletes REQUIREMENTS.md (fresh one created for next milestone)
5. Performs full PROJECT.md evolution review
6. Offers to create next milestone inline
1. Extract full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Archive requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
3. Update ROADMAP.md — replace milestone details with one-line summary
4. Delete REQUIREMENTS.md (fresh one for next milestone)
5. Perform full PROJECT.md evolution review
6. Offer to create next milestone inline
**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
**Archive Format:**
**ROADMAP archive** uses `templates/milestone-archive.md` — includes milestone header (status, phases, date), full phase details, milestone summary (decisions, issues, tech debt).
**ROADMAP archive** uses `templates/milestone-archive.md` template with:
- Milestone header (status, phases, date)
- Full phase details from roadmap
- Milestone summary (decisions, issues, technical debt)
**REQUIREMENTS archive** contains:
- All v1 requirements marked complete with outcomes
- Traceability table with final status
- Notes on any requirements that changed during milestone
**REQUIREMENTS archive** contains all requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.
</archival_behavior>
@@ -49,26 +37,25 @@ When a milestone completes, this workflow:
<step name="verify_readiness">
Check if milestone is truly complete:
Check milestone completion:
```bash
cat .planning/ROADMAP.md
ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
```
**Questions to ask:**
Verify:
- Which phases belong to this milestone?
- Are all those phases complete (all plans have summaries)?
- Has the work been tested/validated?
- Is this ready to ship/tag?
- All phases complete (all plans have summaries)?
- Work tested/validated?
- Ready to ship/tag?
Present:
```
Milestone: [Name from user, e.g., "v1.0 MVP"]
Milestone: [Name, e.g., "v1.0 MVP"]
Appears to include:
Includes:
- Phase 1: Foundation (2/2 plans complete)
- Phase 2: Authentication (2/2 plans complete)
- Phase 3: Core Features (3/3 plans complete)
@@ -89,13 +76,11 @@ cat .planning/config.json 2>/dev/null
```
⚡ Auto-approved: Milestone scope verification
[Show breakdown summary without prompting]
Proceeding to stats gathering...
```
Proceed directly to gather_stats step.
Proceed to gather_stats.
</if>
@@ -107,9 +92,8 @@ Ready to mark this milestone as shipped?
```
Wait for confirmation.
If "adjust scope": Ask which phases should be included.
If "wait": Stop, user will return when ready.
- "adjust scope": Ask which phases to include.
- "wait": Stop, user returns when ready.
</if>
@@ -120,30 +104,20 @@ If "wait": Stop, user will return when ready.
Calculate milestone statistics:
```bash
# Count phases and plans in milestone
# (user specified or detected from roadmap)
# Find git range
git log --oneline --grep="feat(" | head -20
# Count files modified in range
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
# Count LOC (adapt to language)
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
# Calculate timeline
git log --format="%ai" FIRST_COMMIT | tail -1 # Start date
git log --format="%ai" LAST_COMMIT | head -1 # End date
git log --format="%ai" FIRST_COMMIT | tail -1
git log --format="%ai" LAST_COMMIT | head -1
```
Present summary:
Present:
```
Milestone Stats:
- Phases: [X-Y]
- Plans: [Z] total
- Tasks: [N] total (estimated from phase summaries)
- Tasks: [N] total (from phase summaries)
- Files modified: [M]
- Lines of code: [LOC] [language]
- Timeline: [Days] days ([Start] → [End])
@@ -162,9 +136,7 @@ cat .planning/phases/02-*/02-*-SUMMARY.md
# ... for each phase in milestone
```
From summaries, extract 4-6 key accomplishments.
Present:
Extract 4-6 key accomplishments. Present:
```
Key accomplishments for this milestone:
@@ -181,15 +153,7 @@ Key accomplishments for this milestone:
Create or update `.planning/MILESTONES.md`.
If file doesn't exist:
```markdown
# Project Milestones: [Project Name from PROJECT.md]
[New entry]
```
If exists, prepend new entry (reverse chronological order).
If file doesn't exist, create with project name header. If exists, prepend new entry (reverse chronological).
Use template from `templates/milestone.md`:
@@ -209,7 +173,7 @@ Use template from `templates/milestone.md`:
- [Files] files created/modified
- [LOC] lines of [language]
- [Phases] phases, [Plans] plans, [Tasks] tasks
- [Days] days from [start milestone or start project] to ship
- [Days] days from [start] to ship
**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
@@ -222,9 +186,9 @@ Use template from `templates/milestone.md`:
<step name="evolve_project_full_review">
Perform full PROJECT.md evolution review at milestone completion.
Full PROJECT.md evolution review at milestone completion.
**Read all phase summaries in this milestone:**
Read all phase summaries:
```bash
cat .planning/phases/*-*/*-SUMMARY.md
@@ -233,48 +197,43 @@ cat .planning/phases/*-*/*-SUMMARY.md
**Full review checklist:**
1. **"What This Is" accuracy:**
- Read current description
- Compare to what was actually built
- Update if the product has meaningfully changed
- Compare current description to what was built
- Update if product has meaningfully changed
2. **Core Value check:**
- Is the stated core value still the right priority?
- Did shipping reveal a different core value?
- Still the right priority? Did shipping reveal a different core value?
- Update if the ONE thing has shifted
3. **Requirements audit:**
**Validated section:**
- All Active requirements shipped in this milestone → Move to Validated
- All Active requirements shipped this milestone → Move to Validated
- Format: `- ✓ [Requirement] — v[X.Y]`
**Active section:**
- Remove requirements that moved to Validated
- Add any new requirements for next milestone
- Keep requirements that weren't addressed yet
- Remove requirements moved to Validated
- Add new requirements for next milestone
- Keep unaddressed requirements
**Out of Scope audit:**
- Review each item — is the reasoning still valid?
- Remove items that are no longer relevant
- Add any requirements invalidated during this milestone
- Review each item — reasoning still valid?
- Remove irrelevant items
- Add requirements invalidated during milestone
4. **Context update:**
- Current codebase state (LOC, tech stack)
- User feedback themes (if any)
- Known issues or technical debt to address
- Known issues or technical debt
5. **Key Decisions audit:**
- Extract all decisions from milestone phase summaries
- Add to Key Decisions table with outcomes where known
- Mark ✓ Good, ⚠️ Revisit, or — Pending for each
- Add to Key Decisions table with outcomes
- Mark ✓ Good, ⚠️ Revisit, or — Pending
6. **Constraints check:**
- Any constraints that changed during development?
- Update as needed
- Any constraints changed during development? Update as needed
**Update PROJECT.md:**
Make all edits inline. Update "Last updated" footer:
Update PROJECT.md inline. Update "Last updated" footer:
```markdown
---
@@ -366,9 +325,7 @@ Initial user testing showed demand for shape tools.
<step name="reorganize_roadmap">
Update `.planning/ROADMAP.md` to group completed milestone phases.
Add milestone headers and collapse completed work:
Update `.planning/ROADMAP.md` — group completed milestone phases:
```markdown
# Roadmap: [Project Name]
@@ -412,89 +369,53 @@ Add milestone headers and collapse completed work:
<step name="archive_milestone">
Extract completed milestone details and create archive file.
**Process:**
1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`
Extract completed milestone details to archive.
1. Create `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template
3. Extract data from current ROADMAP.md:
- All phases belonging to this milestone (by phase number range)
- Full phase details (goals, plans, dependencies, status)
- Phase plan lists with completion checkmarks
4. Extract data from PROJECT.md:
- Key decisions made during this milestone
- Requirements that were validated
5. Fill template {{PLACEHOLDERS}}:
- {{VERSION}} — Milestone version (e.g., "1.0")
- {{MILESTONE_NAME}} — From ROADMAP.md milestone header
- {{DATE}} — Today's date
- {{PHASE_START}} — First phase number in milestone
- {{PHASE_END}} — Last phase number in milestone
- {{TOTAL_PLANS}} — Count of all plans in milestone
- {{MILESTONE_DESCRIPTION}} — From ROADMAP.md overview
- {{PHASES_SECTION}} — Full phase details extracted
- {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
- {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
7. Delete ROADMAP.md (fresh one created for next milestone):
3. Extract from ROADMAP.md: all phases in milestone (by number range), full phase details, plan lists with checkmarks
4. Extract from PROJECT.md: key decisions, validated requirements
5. Fill template placeholders: {{VERSION}}, {{MILESTONE_NAME}}, {{DATE}}, {{PHASE_START}}, {{PHASE_END}}, {{TOTAL_PLANS}}, {{MILESTONE_DESCRIPTION}}, {{PHASES_SECTION}}, {{DECISIONS_FROM_PROJECT}}, {{ISSUES_RESOLVED_DURING_MILESTONE}}
6. Write to `.planning/milestones/v[X.Y]-ROADMAP.md`
7. Delete ROADMAP.md:
```bash
rm .planning/ROADMAP.md
```
8. Verify archive exists:
8. Verify:
```bash
ls .planning/milestones/v[X.Y]-ROADMAP.md
```
9. Confirm roadmap archive complete:
9. Confirm:
```
✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
✅ ROADMAP.md deleted (fresh one for next milestone)
```
**Note:** Phase directories (`.planning/phases/`) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
**Note:** Phase directories (`.planning/phases/`) are NOT deleted — they accumulate across milestones as raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
</step>
<step name="archive_requirements">
Archive requirements and prepare for fresh requirements in next milestone.
Archive requirements for next milestone.
**Process:**
1. Read current REQUIREMENTS.md:
1. Read REQUIREMENTS.md:
```bash
cat .planning/REQUIREMENTS.md
```
2. Create archive file: `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
2. Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
3. Transform requirements for archive:
- Mark all v1 requirements as `[x]` complete
- Add outcome notes where relevant (validated, adjusted, dropped)
- Update traceability table status to "Complete" for all shipped requirements
- Add "Milestone Summary" section with:
- Total requirements shipped
- Any requirements that changed scope during milestone
- Any requirements dropped and why
3. Transform: mark all requirements `[x]` complete, add outcome notes, update traceability table to "Complete", add milestone summary (total shipped, scope changes, drops)
4. Write archive file with header:
4. Write archive with header:
```markdown
# Requirements Archive: v[X.Y] [Milestone Name]
**Archived:** [DATE]
**Status:** ✅ SHIPPED
This is the archived requirements specification for v[X.Y].
For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
For current requirements, see `.planning/REQUIREMENTS.md`.
---
@@ -504,15 +425,15 @@ Archive requirements and prepare for fresh requirements in next milestone.
## Milestone Summary
**Shipped:** [X] of [Y] v1 requirements
**Adjusted:** [list any requirements that changed during implementation]
**Dropped:** [list any requirements removed and why]
**Shipped:** [X] of [Y] requirements
**Adjusted:** [list any that changed]
**Dropped:** [list any removed and why]
---
*Archived: [DATE] as part of v[X.Y] milestone completion*
```
5. Delete original REQUIREMENTS.md:
5. Delete original:
```bash
rm .planning/REQUIREMENTS.md
```
@@ -520,34 +441,31 @@ Archive requirements and prepare for fresh requirements in next milestone.
6. Confirm:
```
✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
✅ REQUIREMENTS.md deleted (fresh one for next milestone)
```
**Important:** The next milestone workflow starts with `/gsd:new-milestone` which includes requirements definition. PROJECT.md's Validated section carries the cumulative record across milestones.
**Note:** Next milestone starts with `/gsd:new-milestone` which includes requirements definition. PROJECT.md's Validated section carries cumulative record across milestones.
</step>
<step name="archive_audit">
Move the milestone audit file to the archive (if it exists):
Move audit file to archive (if exists):
```bash
# Move audit to milestones folder (if exists)
[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
AUDIT_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/v[X.Y]-MILESTONE-AUDIT.md --raw)
[ "$AUDIT_EXISTS" = "true" ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
```
Confirm:
```
✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
```
Confirm: `✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md`
(Skip silently if no audit file exists — audit is optional)
Skip silently if no audit file — audit is optional.
</step>
<step name="update_state">
Update STATE.md to reflect milestone completion.
Update STATE.md for milestone completion.
**Project Reference:**
@@ -572,7 +490,6 @@ Progress: [updated progress bar]
```
**Accumulated Context:**
- Clear decisions summary (full log in PROJECT.md)
- Clear resolved blockers
- Keep open blockers for next milestone
@@ -581,95 +498,63 @@ Progress: [updated progress bar]
<step name="handle_branches">
Check if branching was used and offer merge options.
**Check branching strategy:**
Check branching strategy and offer merge options.
```bash
# Get branching strategy from config
BRANCHING_STRATEGY=$(cat .planning/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")
GSD_CONFIG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw)
BRANCHING_STRATEGY=$(echo "$GSD_CONFIG" | grep '^branching_strategy=' | cut -d= -f2)
PHASE_BRANCH_TEMPLATE=$(echo "$GSD_CONFIG" | grep '^phase_branch_template=' | cut -d= -f2)
MILESTONE_BRANCH_TEMPLATE=$(echo "$GSD_CONFIG" | grep '^milestone_branch_template=' | cut -d= -f2)
```
**If strategy is "none":** Skip to git_tag step.
**If "none":** Skip to git_tag.
**For "phase" strategy — find phase branches:**
**For "phase" strategy:**
```bash
PHASE_BRANCH_TEMPLATE=$(cat .planning/config.json 2>/dev/null | grep -o '"phase_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/phase-{phase}-{slug}")
# Extract prefix from template (before first variable)
BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
# Find all phase branches for this milestone
PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
```
**For "milestone" strategy — find milestone branch:**
**For "milestone" strategy:**
```bash
MILESTONE_BRANCH_TEMPLATE=$(cat .planning/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/{milestone}-{slug}")
# Extract prefix from template
BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
# Find milestone branch
MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
```
**If no branches found:** Skip to git_tag step.
**If no branches found:** Skip to git_tag.
**If branches exist — present merge options:**
**If branches exist:**
```
## Git Branches Detected
Branching strategy: {phase/milestone}
Branches found:
{list of branches}
Branches: {list}
Options:
1. **Merge to main** — Merge branch(es) to main
2. **Delete without merging** — Branches already merged or not needed
2. **Delete without merging** — Already merged or not needed
3. **Keep branches** — Leave for manual handling
```
Use AskUserQuestion:
AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.
```
AskUserQuestion([
{
question: "How should branches be handled?",
header: "Branches",
multiSelect: false,
options: [
{ label: "Squash merge (Recommended)", description: "Squash all commits into one clean commit on main" },
{ label: "Merge with history", description: "Preserve all individual commits (--no-ff)" },
{ label: "Delete without merging", description: "Branches already merged or not needed" },
{ label: "Keep branches", description: "Leave branches for manual handling later" }
]
}
])
```
**If "Squash merge":**
**Squash merge:**
```bash
CURRENT_BRANCH=$(git branch --show-current)
git checkout main
# For phase strategy - squash merge each phase branch
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
echo "Squash merging $branch..."
git merge --squash "$branch"
git commit -m "feat: $branch for v[X.Y]"
done
fi
# For milestone strategy - squash merge milestone branch
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
echo "Squash merging $MILESTONE_BRANCH..."
git merge --squash "$MILESTONE_BRANCH"
git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
fi
@@ -677,34 +562,26 @@ fi
git checkout "$CURRENT_BRANCH"
```
Report: "Squash merged branches to main"
**If "Merge with history":**
**Merge with history:**
```bash
CURRENT_BRANCH=$(git branch --show-current)
git checkout main
# For phase strategy - merge each phase branch
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
echo "Merging $branch..."
git merge --no-ff "$branch" -m "Merge branch '$branch' for v[X.Y]"
done
fi
# For milestone strategy - merge milestone branch
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
echo "Merging $MILESTONE_BRANCH..."
git merge --no-ff "$MILESTONE_BRANCH" -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
fi
git checkout "$CURRENT_BRANCH"
```
Report: "Merged branches to main with full history"
**If "Delete without merging":**
**Delete without merging:**
```bash
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
@@ -718,17 +595,13 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
fi
```
Report: "Deleted branches"
**If "Keep branches":**
Report: "Branches preserved for manual handling"
**Keep branches:** Report "Branches preserved for manual handling"
</step>
<step name="git_tag">
Create git tag for milestone:
Create git tag:
```bash
git tag -a v[X.Y] -m "$(cat <<'EOF'
@@ -751,7 +624,6 @@ Confirm: "Tagged: v[X.Y]"
Ask: "Push tag to remote? (y/n)"
If yes:
```bash
git push origin v[X.Y]
```
@@ -760,54 +632,11 @@ git push origin v[X.Y]
<step name="git_commit_milestone">
Commit milestone completion including archive files and deletions.
**Check planning config:**
Commit milestone completion.
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash
# Stage archive files (new)
git add .planning/milestones/v[X.Y]-ROADMAP.md
git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
git add .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
# Stage updated files
git add .planning/MILESTONES.md
git add .planning/PROJECT.md
git add .planning/STATE.md
# Stage deletions
git add -u .planning/
# Commit with descriptive message
git commit -m "$(cat <<'EOF'
chore: complete v[X.Y] milestone
Archived:
- milestones/v[X.Y]-ROADMAP.md
- milestones/v[X.Y]-REQUIREMENTS.md
- milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
Deleted (fresh for next milestone):
- ROADMAP.md
- REQUIREMENTS.md
Updated:
- MILESTONES.md (new entry)
- PROJECT.md (requirements → Validated)
- STATE.md (reset for next milestone)
Tagged: v[X.Y]
EOF
)"
```
Confirm: "Committed: chore: complete v[X.Y] milestone"
@@ -851,35 +680,20 @@ Tag: v[X.Y]
**Version conventions:**
- **v1.0** — Initial MVP
- **v1.1, v1.2, v1.3** — Minor updates, new features, fixes
- **v2.0, v3.0** — Major rewrites, breaking changes, significant new direction
- **v1.1, v1.2** — Minor updates, new features, fixes
- **v2.0, v3.0** — Major rewrites, breaking changes, new direction
**Name conventions:**
- v1.0 MVP
- v1.1 Security
- v1.2 Performance
- v2.0 Redesign
- v2.0 iOS Launch
Keep names short (1-2 words describing the focus).
**Names:** Short 1-2 words (v1.0 MVP, v1.1 Security, v1.2 Performance, v2.0 Redesign).
</milestone_naming>
<what_qualifies>
**Create milestones for:**
- Initial release (v1.0)
- Public releases
- Major feature sets shipped
- Before archiving planning
**Create milestones for:** Initial release, public releases, major feature sets shipped, before archiving planning.
**Don't create milestones for:**
- Every phase completion (too granular)
- Work in progress (wait until shipped)
- Internal dev iterations (unless truly shipped internally)
**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).
If uncertain, ask: "Is this deployed/usable/shipped in some form?"
If yes → milestone. If no → keep working.
Heuristic: "Is this deployed/usable/shipped?" If yes → milestone. If no → keep working.
</what_qualifies>

View File

@@ -156,21 +156,9 @@ For each gap in the Gaps section, add artifacts and missing fields:
Update status in frontmatter to "diagnosed".
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
Commit the updated UAT.md:
```bash
git add ".planning/phases/XX-name/{phase}-UAT.md"
git commit -m "docs({phase}): add root causes from diagnosis"
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs({phase}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase}-UAT.md"
```
</step>

View File

@@ -130,9 +130,8 @@ Exit workflow.
Check if CONTEXT.md already exists:
```bash
# Match both zero-padded (05-*) and unpadded (5-*) folders
PADDED_PHASE=$(printf "%02d" ${PHASE})
ls .planning/phases/${PADDED_PHASE}-*/*-CONTEXT.md .planning/phases/${PHASE}-*/*-CONTEXT.md 2>/dev/null
PHASE_DIR=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "${PHASE}" --raw)
ls ${PHASE_DIR}/*-CONTEXT.md 2>/dev/null
```
**If exists:**
@@ -282,14 +281,15 @@ Create CONTEXT.md capturing decisions made.
**Find or create phase directory:**
```bash
# Match existing directory (padded or unpadded)
PADDED_PHASE=$(printf "%02d" ${PHASE})
PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "${PHASE}")
PHASE_DIR=$(echo "$PHASE_INFO" | grep -o '"directory":"[^"]*"' | cut -d'"' -f4)
PADDED_PHASE=$(echo "$PHASE_INFO" | grep -o '"phase_number":"[^"]*"' | cut -d'"' -f4)
if [ -z "$PHASE_DIR" ]; then
# Create from roadmap name (lowercase, hyphens)
PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
mkdir -p ".planning/phases/${PADDED_PHASE}-${PHASE_NAME}"
PHASE_DIR=".planning/phases/${PADDED_PHASE}-${PHASE_NAME}"
PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //')
PHASE_SLUG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$PHASE_NAME" --raw)
PADDED_PHASE=$(printf "%02d" ${PHASE})
mkdir -p ".planning/phases/${PADDED_PHASE}-${PHASE_SLUG}"
PHASE_DIR=".planning/phases/${PADDED_PHASE}-${PHASE_SLUG}"
fi
```
@@ -393,27 +393,8 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
<step name="git_commit">
Commit phase context:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash
git add "${PHASE_DIR}/${PADDED_PHASE}-CONTEXT.md"
git commit -m "$(cat <<'EOF'
docs(${PADDED_PHASE}): capture phase context
Phase ${PADDED_PHASE}: ${PHASE_NAME}
- Implementation decisions documented
- Phase boundary established
EOF
)"
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs(${PADDED_PHASE}): capture phase context" --files "${PHASE_DIR}/${PADDED_PHASE}-CONTEXT.md"
```
Confirm: "Committed: docs(${PADDED_PHASE}): capture phase context"

View File

@@ -1,163 +1,80 @@
<purpose>
Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean by delegating plan execution to subagents.
Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
</purpose>
<core_principle>
The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, handles checkpoints, collects results.
Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
</core_principle>
<required_reading>
Read STATE.md before any operation to load project context.
Read config.json for planning behavior settings.
Read STATE.md and config.json before any operation.
</required_reading>
<process>
<step name="resolve_model_profile" priority="first">
Read model profile for agent spawning:
```bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
EXECUTOR_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-executor --raw)
VERIFIER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-verifier --raw)
```
Default to "balanced" if not set.
**Model lookup table:**
| Agent | quality | balanced | budget |
|-------|---------|----------|--------|
| gsd-executor | opus | sonnet | sonnet |
| gsd-verifier | sonnet | sonnet | haiku |
| general-purpose | — | — | — |
Store resolved models for use in Task calls below.
</step>
<step name="load_project_state">
Before any operation, read project state:
```bash
cat .planning/STATE.md 2>/dev/null
```
**If file exists:** Parse and internalize:
- Current position (phase, plan, status)
- Accumulated decisions (constraints on this execution)
- Blockers/concerns (things to watch for)
**If exists:** Parse current position, accumulated decisions, blockers.
**If missing but .planning/ exists:** Offer reconstruct from artifacts or continue without state.
**If .planning/ missing:** Error — project not initialized.
**If file missing but .planning/ exists:**
```
STATE.md missing but planning artifacts exist.
Options:
1. Reconstruct from existing artifacts
2. Continue without project state (may lose accumulated context)
```
**If .planning/ doesn't exist:** Error - project not initialized.
**Load planning config:**
**Load configs:**
```bash
# Check if planning docs should be committed (default: true)
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
# Auto-detect gitignored (overrides config)
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
GSD_CONFIG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw)
COMMIT_PLANNING_DOCS=$(echo "$GSD_CONFIG" | grep '^commit_docs=' | cut -d= -f2)
PARALLELIZATION=$(echo "$GSD_CONFIG" | grep '^parallelization=' | cut -d= -f2)
BRANCHING_STRATEGY=$(echo "$GSD_CONFIG" | grep '^branching_strategy=' | cut -d= -f2)
PHASE_BRANCH_TEMPLATE=$(echo "$GSD_CONFIG" | grep '^phase_branch_template=' | cut -d= -f2)
MILESTONE_BRANCH_TEMPLATE=$(echo "$GSD_CONFIG" | grep '^milestone_branch_template=' | cut -d= -f2)
```
Store `COMMIT_PLANNING_DOCS` for use in git operations.
**Load parallelization config:**
```bash
# Check if parallelization is enabled (default: true)
PARALLELIZATION=$(cat .planning/config.json 2>/dev/null | grep -o '"parallelization"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
```
Store `PARALLELIZATION` for use in wave execution step. When `false`, plans within a wave execute sequentially instead of in parallel.
**Load git branching config:**
```bash
# Get branching strategy (default: none)
BRANCHING_STRATEGY=$(cat .planning/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")
# Get templates
PHASE_BRANCH_TEMPLATE=$(cat .planning/config.json 2>/dev/null | grep -o '"phase_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/phase-{phase}-{slug}")
MILESTONE_BRANCH_TEMPLATE=$(cat .planning/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "gsd/{milestone}-{slug}")
```
Store `BRANCHING_STRATEGY` and templates for use in branch creation step.
When `PARALLELIZATION=false`, plans within a wave execute sequentially.
</step>
<step name="handle_branching">
Create or switch to appropriate branch based on branching strategy.
Create or switch to branch based on `BRANCHING_STRATEGY`.
**Skip if strategy is "none":**
**"none":** Skip, continue on current branch.
**"phase":**
```bash
if [ "$BRANCHING_STRATEGY" = "none" ]; then
# No branching, continue on current branch
exit 0
fi
PHASE_NAME=$(basename "$PHASE_DIR" | sed 's/^[0-9]*-//')
PHASE_SLUG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$PHASE_NAME" --raw)
BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
```
**For "phase" strategy — create phase branch:**
**"milestone":**
```bash
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
# Get phase name from directory (e.g., "03-authentication" → "authentication")
PHASE_NAME=$(basename "$PHASE_DIR" | sed 's/^[0-9]*-//')
# Create slug from phase name
PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
# Apply template
BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
# Create or switch to branch
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
echo "Branch: $BRANCH_NAME (phase branching)"
fi
MILESTONE_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' .planning/ROADMAP.md | head -1 || echo "v1.0")
MILESTONE_NAME=$(grep -A1 "## .*$MILESTONE_VERSION" .planning/ROADMAP.md | tail -1 | sed 's/.*- //' | cut -d'(' -f1 | tr -d ' ' || echo "milestone")
MILESTONE_SLUG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$MILESTONE_NAME" --raw)
BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
```
**For "milestone" strategy — create/switch to milestone branch:**
```bash
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
# Get current milestone info from ROADMAP.md
MILESTONE_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' .planning/ROADMAP.md | head -1 || echo "v1.0")
MILESTONE_NAME=$(grep -A1 "## .*$MILESTONE_VERSION" .planning/ROADMAP.md | tail -1 | sed 's/.*- //' | cut -d'(' -f1 | tr -d ' ' || echo "milestone")
# Create slug
MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
# Apply template
BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
# Create or switch to branch (same branch for all phases in milestone)
git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
echo "Branch: $BRANCH_NAME (milestone branching)"
fi
```
**Report branch status:**
```
Branching: {strategy} → {branch_name}
```
**Note:** All subsequent plan commits go to this branch. User handles merging based on their workflow.
All subsequent commits go to this branch. User handles merging.
</step>
<step name="validate_phase">
Confirm phase exists and has plans:
```bash
# Match both zero-padded (05-*) and unpadded (5-*) folders
PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}")
PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "${PHASE_ARG}")
PHASE_DIR=$(echo "$PHASE_INFO" | grep -o '"directory":"[^"]*"' | cut -d'"' -f4)
if [ -z "$PHASE_DIR" ]; then
echo "ERROR: No phase directory matching '${PHASE_ARG}'"
exit 1
@@ -174,41 +91,22 @@ Report: "Found {N} plans in {phase_dir}"
</step>
<step name="discover_plans">
List all plans and extract metadata:
```bash
# Get all plans
ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | sort
# Get completed plans (have SUMMARY.md)
ls -1 "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null | sort
```
For each plan, read frontmatter to extract:
- `wave: N` - Execution wave (pre-computed)
- `autonomous: true/false` - Whether plan has checkpoints
- `gap_closure: true/false` - Whether plan closes gaps from verification/UAT
For each plan, read frontmatter: `wave`, `autonomous`, `gap_closure`.
Build plan inventory:
- Plan path
- Plan ID (e.g., "03-01")
- Wave number
- Autonomous flag
- Gap closure flag
- Completion status (SUMMARY exists = complete)
Build inventory: path, plan ID, wave, autonomous flag, gap_closure flag, completion (SUMMARY exists = complete).
**Filtering:**
- Skip completed plans (have SUMMARY.md)
- If `--gaps-only` flag: also skip plans where `gap_closure` is not `true`
If all plans filtered out, report "No matching incomplete plans" and exit.
**Filtering:** Skip completed plans. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
</step>
<step name="group_by_wave">
Read `wave` from each plan's frontmatter and group by wave number:
```bash
# For each plan, extract wave from frontmatter
for plan in $PHASE_DIR/*-PLAN.md; do
wave=$(grep "^wave:" "$plan" | cut -d: -f2 | tr -d ' ')
autonomous=$(grep "^autonomous:" "$plan" | cut -d: -f2 | tr -d ' ')
@@ -216,18 +114,9 @@ for plan in $PHASE_DIR/*-PLAN.md; do
done
```
**Group plans:**
```
waves = {
1: [plan-01, plan-02],
2: [plan-03, plan-04],
3: [plan-05]
}
```
Group by wave number. **No dependency analysis needed** — waves pre-computed during `/gsd:plan-phase`.
**No dependency analysis needed.** Wave numbers are pre-computed during `/gsd:plan-phase`.
Report wave structure with context:
Report:
```
## Execution Plan
@@ -235,68 +124,49 @@ Report wave structure with context:
| Wave | Plans | What it builds |
|------|-------|----------------|
| 1 | 01-01, 01-02 | {from plan objectives} |
| 2 | 01-03 | {from plan objectives} |
| 3 | 01-04 [checkpoint] | {from plan objectives} |
| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
| 2 | 01-03 | ... |
```
The "What it builds" column comes from skimming plan names/objectives. Keep it brief (3-8 words).
</step>
<step name="execute_waves">
Execute each wave in sequence. Autonomous plans within a wave run in parallel **only if `PARALLELIZATION=true`**.
**If `PARALLELIZATION=false`:** Execute plans within each wave sequentially (one at a time). This prevents side effects from concurrent operations like tests, linting, and code generation.
Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
**For each wave:**
1. **Describe what's being built (BEFORE spawning):**
Read each plan's `<objective>` section. Extract what's being built and why it matters.
Read each plan's `<objective>`. Extract what's being built and why.
**Output:**
```
---
## Wave {N}
**{Plan ID}: {Plan Name}**
{2-3 sentences: what this builds, key technical approach, why it matters in context}
**{Plan ID}: {Plan Name}** (if parallel)
{same format}
{2-3 sentences: what this builds, technical approach, why it matters}
Spawning {count} agent(s)...
---
```
**Examples:**
- Bad: "Executing terrain generation plan"
- Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
2. **Read files and spawn agents:**
Before spawning, read file contents. The `@` syntax does not work across Task() boundaries - content must be inlined.
Content must be inlined — `@` syntax doesn't work across Task() boundaries.
```bash
# Read each plan in the wave
PLAN_CONTENT=$(cat "{plan_path}")
STATE_CONTENT=$(cat .planning/STATE.md)
CONFIG_CONTENT=$(cat .planning/config.json 2>/dev/null)
```
**If `PARALLELIZATION=true` (default):** Use Task tool with multiple parallel calls.
**If `PARALLELIZATION=false`:** Spawn agents one at a time, waiting for each to complete before starting the next. This ensures no concurrent file modifications or build operations.
Each agent gets prompt with inlined content:
Each agent prompt:
```
<objective>
Execute plan {plan_number} of phase {phase_number}-{phase_name}.
Commit each task atomically. Create SUMMARY.md. Update STATE.md.
</objective>
@@ -326,311 +196,166 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel **
</success_criteria>
```
2. **Wait for all agents in wave to complete:**
3. **Wait for all agents in wave to complete.**
Task tool blocks until each agent finishes. All parallel agents return together.
4. **Report completion — spot-check claims first:**
3. **Report completion and what was built:**
For each SUMMARY.md:
- Verify first 2 files from `key-files.created` exist on disk
- Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
- Check for `## Self-Check: FAILED` marker
For each completed agent:
- Verify SUMMARY.md exists at expected path
- Read SUMMARY.md to extract what was built
- Note any issues or deviations
If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
**Spot-check claims before trusting SUMMARY:**
For each completed plan's SUMMARY.md:
- Pick the first 2 files from `key-files.created` frontmatter — verify they exist on disk with `[ -f ]`
- Check `git log --oneline --all --grep="{phase}-{plan}"` returns at least 1 commit
- Check SUMMARY.md for `## Self-Check: FAILED` marker
If ANY spot-check fails:
- Do NOT proceed silently
- Report which plan failed verification and what was missing
- Route to failure handler (step 4): ask user "Retry plan?" or "Continue with remaining waves?"
If spot-checks pass: proceed normally.
**Output:**
If pass:
```
---
## Wave {N} Complete
**{Plan ID}: {Plan Name}**
{What was built — from SUMMARY.md deliverables}
{Notable deviations or discoveries, if any}
**{Plan ID}: {Plan Name}** (if parallel)
{same format}
{If more waves: brief note on what this enables for next wave}
{What was built — from SUMMARY.md}
{Notable deviations, if any}
{If more waves: what this enables for next wave}
---
```
**Examples:**
- Bad: "Wave 2 complete. Proceeding to Wave 3."
- Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
4. **Handle failures:**
5. **Handle failures:** Report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
If any agent in wave fails:
- Report which plan failed and why
- Ask user: "Continue with remaining waves?" or "Stop execution?"
- If continue: proceed to next wave (dependent plans may also fail)
- If stop: exit with partial completion report
5. **Execute checkpoint plans between waves:**
See `<checkpoint_handling>` for details.
6. **Proceed to next wave**
6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
7. **Proceed to next wave.**
</step>
<step name="checkpoint_handling">
Plans with `autonomous: false` require user interaction.
**Detection:** Check `autonomous` field in frontmatter.
**Flow:**
**Execution flow for checkpoint plans:**
1. **Spawn agent for checkpoint plan:**
```
Task(prompt="{subagent-task-prompt}", subagent_type="gsd-executor", model="{executor_model}")
```
2. **Agent runs until checkpoint:**
- Executes auto tasks normally
- Reaches checkpoint task (e.g., `type="checkpoint:human-verify"`) or auth gate
- Agent returns with structured checkpoint (see checkpoint-return.md template)
3. **Agent return includes (structured format):**
- Completed Tasks table with commit hashes and files
- Current task name and blocker
- Checkpoint type and details for user
- What's awaited from user
4. **Orchestrator presents checkpoint to user:**
Extract and display the "Checkpoint Details" and "Awaiting" sections from agent return:
1. Spawn agent for checkpoint plan
2. Agent runs until checkpoint task or auth gate → returns structured state
3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
4. **Present to user:**
```
## Checkpoint: [Type]
**Plan:** 03-03 Dashboard Layout
**Progress:** 2/3 tasks complete
[Checkpoint Details section from agent return]
[Checkpoint Details from agent return]
[Awaiting section from agent return]
```
5. **User responds:**
- "approved" / "done" → spawn continuation agent
- Description of issues → spawn continuation agent with feedback
- Decision selection → spawn continuation agent with choice
6. **Spawn continuation agent (NOT resume):**
Use the continuation-prompt.md template:
```
Task(
prompt=filled_continuation_template,
subagent_type="gsd-executor",
model="{executor_model}"
)
```
Fill template with:
- `{completed_tasks_table}`: From agent's checkpoint return
- `{resume_task_number}`: Current task from checkpoint
- `{resume_task_name}`: Current task name from checkpoint
5. User responds: "approved"/"done" | issue description | decision selection
6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
- `{completed_tasks_table}`: From checkpoint return
- `{resume_task_number}` + `{resume_task_name}`: Current task
- `{user_response}`: What user provided
- `{resume_instructions}`: Based on checkpoint type (see continuation-prompt.md)
- `{resume_instructions}`: Based on checkpoint type
7. Continuation agent verifies previous commits, continues from resume point
8. Repeat until plan completes or user stops
7. **Continuation agent executes:**
- Verifies previous commits exist
- Continues from resume point
- May hit another checkpoint (repeat from step 4)
- Or completes plan
**Why fresh agent, not resume:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
8. **Repeat until plan completes or user stops**
**Why fresh agent instead of resume:**
Resume relies on Claude Code's internal serialization which breaks with parallel tool calls.
Fresh agents with explicit state are more reliable and maintain full context.
**Checkpoint in parallel context:**
If a plan in a parallel wave has a checkpoint:
- Spawn as normal
- Agent pauses at checkpoint and returns with structured state
- Other parallel agents may complete while waiting
- Present checkpoint to user
- Spawn continuation agent with user response
- Wait for all agents to finish before next wave
**Checkpoints in parallel waves:** Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.
</step>
<step name="aggregate_results">
After all waves complete, aggregate results:
After all waves:
```markdown
## Phase {X}: {Name} Execution Complete
**Waves executed:** {N}
**Plans completed:** {M} of {total}
### Wave Summary
**Waves:** {N} | **Plans:** {M}/{total} complete
| Wave | Plans | Status |
|------|-------|--------|
| 1 | plan-01, plan-02 | ✓ Complete |
| CP | plan-03 | ✓ Verified |
| 2 | plan-04 | ✓ Complete |
| 3 | plan-05 | ✓ Complete |
### Plan Details
1. **03-01**: [one-liner from SUMMARY.md]
2. **03-02**: [one-liner from SUMMARY.md]
...
### Issues Encountered
[Aggregate from all SUMMARYs, or "None"]
[Aggregate from SUMMARYs, or "None"]
```
</step>
<step name="verify_phase_goal">
Verify phase achieved its GOAL, not just completed its TASKS.
**Spawn verifier:**
Verify phase achieved its GOAL, not just completed tasks.
```
Task(
prompt="Verify phase {phase_number} goal achievement.
Phase directory: {phase_dir}
Phase goal: {goal from ROADMAP.md}
Check must_haves against actual codebase. Create VERIFICATION.md.
Verify what actually exists in the code.",
Check must_haves against actual codebase. Create VERIFICATION.md.",
subagent_type="gsd-verifier",
model="{verifier_model}"
)
```
**Read verification status:**
Read status:
```bash
grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
```
**Route by status:**
| Status | Action |
|--------|--------|
| `passed` | Continue to update_roadmap |
| `human_needed` | Present items to user, get approval or feedback |
| `passed` | → update_roadmap |
| `human_needed` | Present items for human testing, get approval or feedback |
| `gaps_found` | Present gap summary, offer `/gsd:plan-phase {phase} --gaps` |
**If passed:**
Phase goal verified. Proceed to update_roadmap.
**If human_needed:**
```markdown
```
## ✓ Phase {X}: {Name} — Human Verification Required
All automated checks passed. {N} items need human testing:
### Human Verification Checklist
{From VERIFICATION.md human_verification section}
{Extract from VERIFICATION.md human_verification section}
---
**After testing:**
- "approved" → continue to update_roadmap
- Report issues → will route to gap closure planning
"approved" → continue | Report issues → gap closure
```
If user approves → continue to update_roadmap.
If user reports issues → treat as gaps_found.
**If gaps_found:**
Present gaps and offer next command:
```markdown
```
## ⚠ Phase {X}: {Name} — Gaps Found
**Score:** {N}/{M} must-haves verified
**Report:** {phase_dir}/{phase}-VERIFICATION.md
### What's Missing
{Extract gap summaries from VERIFICATION.md gaps section}
{Gap summaries from VERIFICATION.md}
---
## ▶ Next Up
**Plan gap closure** — create additional plans to complete the phase
`/gsd:plan-phase {X} --gaps`
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
- `cat {phase_dir}/{phase}-VERIFICATION.md` — see full report
- `/gsd:verify-work {X}` — manual testing before planning
Also: `cat {phase_dir}/{phase}-VERIFICATION.md` — full report
Also: `/gsd:verify-work {X}` — manual testing first
```
User runs `/gsd:plan-phase {X} --gaps` which:
1. Reads VERIFICATION.md gaps
2. Creates additional plans (04, 05, etc.) with `gap_closure: true` to close gaps
3. User then runs `/gsd:execute-phase {X} --gaps-only`
4. Execute-phase runs only gap closure plans (04-05)
5. Verifier runs again after new plans complete
User stays in control at each decision point.
Gap closure cycle: `/gsd:plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/gsd:execute-phase {X} --gaps-only` → verifier re-runs.
</step>
<step name="update_roadmap">
Update ROADMAP.md to reflect phase completion:
Mark phase complete in ROADMAP.md (date, status).
```bash
# Mark phase complete
# Update completion date
# Update status
```
**Check planning config:**
If `COMMIT_PLANNING_DOCS=false` (set in load_project_state):
- Skip all git operations for .planning/ files
- Planning docs exist locally but are gitignored
- Log: "Skipping planning docs commit (commit_docs: false)"
- Proceed to offer_next step
If `COMMIT_PLANNING_DOCS=true` (default):
- Continue with git operations below
Commit phase completion (roadmap, state, verification):
```bash
git add .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md
git add .planning/REQUIREMENTS.md # if updated
git commit -m "docs(phase-{X}): complete phase execution"
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md .planning/REQUIREMENTS.md
```
</step>
<step name="offer_next">
Present next steps based on milestone status:
**If more phases remain:**
**If more phases:**
```
## Next Up
@@ -654,47 +379,18 @@ All {N} phases executed.
</process>
<context_efficiency>
Orchestrator: ~10-15% context (frontmatter, spawning, results).
Subagents: Fresh 200k each (full workflow + execution).
No polling (Task blocks). No context bleed.
Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task blocks). No context bleed.
</context_efficiency>
<failure_handling>
**Subagent fails mid-plan:**
- SUMMARY.md won't exist
- Orchestrator detects missing SUMMARY
- Reports failure, asks user how to proceed
**Dependency chain breaks:**
- Wave 1 plan fails
- Wave 2 plans depending on it will likely fail
- Orchestrator can still attempt them (user choice)
- Or skip dependent plans entirely
**All agents in wave fail:**
- Something systemic (git issues, permissions, etc.)
- Stop execution
- Report for manual investigation
**Checkpoint fails to resolve:**
- User can't approve or provides repeated issues
- Ask: "Skip this plan?" or "Abort phase execution?"
- Record partial progress in STATE.md
- **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
- **All agents in wave fail:** Systemic issue → stop, report for investigation
- **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
</failure_handling>
<resumption>
**Resuming interrupted execution:**
Re-run `/gsd:execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
If phase execution was interrupted (context limit, user exit, error):
1. Run `/gsd:execute-phase {phase}` again
2. discover_plans finds completed SUMMARYs
3. Skips completed plans
4. Resumes from first incomplete plan
5. Continues wave-based execution
**STATE.md tracks:**
- Last completed plan
- Current wave
- Any pending checkpoints
STATE.md tracks: last completed plan, current wave, pending checkpoints.
</resumption>

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,470 @@
<purpose>
Display the complete GSD 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>
# GSD Command Reference
**GSD** (Get Shit Done) creates hierarchical project plans optimized for solo agentic development with Claude Code.
## Quick Start
1. `/gsd:new-project` - Initialize project (includes research, requirements, roadmap)
2. `/gsd:plan-phase 1` - Create detailed plan for first phase
3. `/gsd:execute-phase 1` - Execute the phase
## Staying Updated
GSD evolves fast. Update periodically:
```bash
npx get-shit-done-cc@latest
```
## Core Workflow
```
/gsd:new-project → /gsd:plan-phase → /gsd:execute-phase → repeat
```
### Project Initialization
**`/gsd: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: `/gsd:new-project`
**`/gsd: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 `/gsd:new-project` on existing codebases
Usage: `/gsd:map-codebase`
### Phase Planning
**`/gsd: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: `/gsd:discuss-phase 2`
**`/gsd: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: `/gsd:research-phase 3`
**`/gsd: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: `/gsd:list-phase-assumptions 3`
**`/gsd: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: `/gsd:plan-phase 1`
Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
### Execution
**`/gsd:execute-phase <phase-number>`**
Execute all plans in a phase.
- Groups plans by wave (from frontmatter), executes waves sequentially
- Plans within each wave run in parallel via Task tool
- Verifies phase goal after all plans complete
- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
Usage: `/gsd:execute-phase 5`
### Quick Mode
**`/gsd:quick`**
Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.
Quick mode uses the same system with a shorter path:
- Spawns planner + executor (skips researcher, checker, verifier)
- Quick tasks live in `.planning/quick/` separate from planned phases
- Updates STATE.md tracking (not ROADMAP.md)
Use when you know exactly what to do and the task is small enough to not need research or verification.
Usage: `/gsd:quick`
Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
### Roadmap Management
**`/gsd:add-phase <description>`**
Add new phase to end of current milestone.
- Appends to ROADMAP.md
- Uses next sequential number
- Updates phase directory structure
Usage: `/gsd:add-phase "Add admin dashboard"`
**`/gsd: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: `/gsd:insert-phase 7 "Fix critical auth bug"`
Result: Creates Phase 7.1
**`/gsd: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: `/gsd:remove-phase 17`
Result: Phase 17 deleted, phases 18-20 become 17-19
### Milestone Management
**`/gsd: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
Mirrors `/gsd:new-project` flow for brownfield projects (existing PROJECT.md).
Usage: `/gsd:new-milestone "v2.0 Features"`
**`/gsd: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: `/gsd:complete-milestone 1.0.0`
### Progress Tracking
**`/gsd: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: `/gsd:progress`
### Session Management
**`/gsd: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: `/gsd:resume-work`
**`/gsd: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: `/gsd:pause-work`
### Debugging
**`/gsd: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 `/gsd:debug` with no args to resume
- Archives resolved issues to `.planning/debug/resolved/`
Usage: `/gsd:debug "login button doesn't work"`
Usage: `/gsd:debug` (resume active session)
### Todo Management
**`/gsd: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: `/gsd:add-todo` (infers from conversation)
Usage: `/gsd:add-todo Add auth token refresh`
**`/gsd: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., `/gsd: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: `/gsd:check-todos`
Usage: `/gsd:check-todos api`
### User Acceptance Testing
**`/gsd: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: `/gsd:verify-work 3`
### Milestone Auditing
**`/gsd: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: `/gsd:audit-milestone`
**`/gsd: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 `/gsd:plan-phase` on new phases
Usage: `/gsd:plan-milestone-gaps`
### Configuration
**`/gsd:settings`**
Configure workflow toggles and model profile interactively.
- Toggle researcher, plan checker, verifier agents
- Select model profile (quality/balanced/budget)
- Updates `.planning/config.json`
Usage: `/gsd:settings`
**`/gsd:set-profile <profile>`**
Quick switch model profile for GSD agents.
- `quality` — Opus everywhere except verification
- `balanced` — Opus for planning, Sonnet for execution (default)
- `budget` — Sonnet for writing, Haiku for research/verification
Usage: `/gsd:set-profile budget`
### Utility Commands
**`/gsd:help`**
Show this command reference.
**`/gsd:update`**
Update GSD 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 get-shit-done-cc`
Usage: `/gsd:update`
**`/gsd:join-discord`**
Join the GSD Discord community.
- Get help, share what you're building, stay updated
- Connect with other GSD users
Usage: `/gsd:join-discord`
## Files & Structure
```
.planning/
├── PROJECT.md # Project vision
├── ROADMAP.md # Current phase breakdown
├── STATE.md # Project memory & context
├── 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
├── 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 `/gsd: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:**
```
/gsd:new-project # Unified flow: questioning → research → requirements → roadmap
/clear
/gsd:plan-phase 1 # Create plans for first phase
/clear
/gsd:execute-phase 1 # Execute all plans in phase
```
**Resuming work after a break:**
```
/gsd:progress # See where you left off and continue
```
**Adding urgent mid-milestone work:**
```
/gsd:insert-phase 5 "Critical security fix"
/gsd:plan-phase 5.1
/gsd:execute-phase 5.1
```
**Completing a milestone:**
```
/gsd:complete-milestone 1.0.0
/clear
/gsd:new-milestone # Start next milestone (questioning → research → requirements → roadmap)
```
**Capturing ideas during work:**
```
/gsd:add-todo # Capture from conversation context
/gsd:add-todo Fix modal z-index # Capture with explicit description
/gsd:check-todos # Review and work on todos
/gsd:check-todos api # Filter by area
```
**Debugging an issue:**
```
/gsd:debug "form submission fails silently" # Start debug session
# ... investigation happens, context fills up ...
/clear
/gsd: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 `/gsd:progress` to check where you're up to
</reference>

View File

@@ -0,0 +1,213 @@
<purpose>
Insert a decimal phase for urgent work discovered mid-milestone between existing integer phases. Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions without renumbering the entire roadmap.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
<step name="parse_arguments">
Parse the command arguments:
- First argument: integer phase number to insert after
- Remaining arguments: phase description
Example: `/gsd:insert-phase 72 Fix critical auth bug`
-> after = 72
-> description = "Fix critical auth bug"
Validation:
```bash
if [ $# -lt 2 ]; then
echo "ERROR: Both phase number and description required"
echo "Usage: /gsd:insert-phase <after> <description>"
echo "Example: /gsd:insert-phase 72 Fix critical auth bug"
exit 1
fi
```
Parse first argument as integer:
```bash
after_phase=$1
shift
description="$*"
# Validate after_phase is an integer
if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
echo "ERROR: Phase number must be an integer"
exit 1
fi
```
</step>
<step name="load_roadmap">
Load the roadmap file:
```bash
ROADMAP_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/ROADMAP.md --raw)
if [ "$ROADMAP_EXISTS" = "true" ]; then
ROADMAP=".planning/ROADMAP.md"
else
echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
exit 1
fi
```
Read roadmap content for parsing.
</step>
<step name="verify_target_phase">
Verify that the target phase exists in the roadmap:
1. Search for "### Phase {after_phase}:" heading
2. If not found:
```
ERROR: Phase {after_phase} not found in roadmap
Available phases: [list phase numbers]
```
Exit.
3. Verify phase is in current milestone (not completed/archived)
</step>
<step name="find_existing_decimals">
Find existing decimal phases after the target phase:
1. Search for all "### Phase {after_phase}.N:" headings
2. Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)
3. Find the highest decimal suffix
4. Calculate next decimal: max + 1
Examples:
- Phase 72 with no decimals -> next is 72.1
- Phase 72 with 72.1 -> next is 72.2
- Phase 72 with 72.1, 72.2 -> next is 72.3
Store as: `decimal_phase="$(printf "%02d" $after_phase).${next_decimal}"`
</step>
<step name="generate_slug">
Convert the phase description to a kebab-case slug:
```bash
slug=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$description" --raw)
```
Phase directory name: `{decimal-phase}-{slug}`
Example: `06.1-fix-critical-auth-bug` (phase 6 insertion)
</step>
<step name="create_phase_directory">
Create the phase directory structure:
```bash
phase_dir=".planning/phases/${decimal_phase}-${slug}"
mkdir -p "$phase_dir"
```
Confirm: "Created directory: $phase_dir"
</step>
<step name="update_roadmap">
Insert the new phase entry into the roadmap:
1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
2. Insert new phase heading with (INSERTED) marker:
```
### Phase {decimal_phase}: {Description} (INSERTED)
**Goal:** [Urgent work - to be planned]
**Depends on:** Phase {after_phase}
**Plans:** 0 plans
Plans:
- [ ] TBD (run /gsd:plan-phase {decimal_phase} to break down)
**Details:**
[To be added during planning]
```
3. Write updated roadmap back to file
The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
Preserve all other content exactly (formatting, spacing, other phases).
</step>
<step name="update_project_state">
Update STATE.md to reflect the inserted phase:
1. Read `.planning/STATE.md`
2. Under "## Accumulated Context" -> "### Roadmap Evolution" add entry:
```
- Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
```
If "Roadmap Evolution" section doesn't exist, create it.
Add note about insertion reason if appropriate.
</step>
<step name="completion">
Present completion summary:
```
Phase {decimal_phase} inserted after Phase {after_phase}:
- Description: {description}
- Directory: .planning/phases/{decimal-phase}-{slug}/
- Status: Not planned yet
- Marker: (INSERTED) - indicates urgent work
Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md
---
## Next Up
**Phase {decimal_phase}: {description}** -- urgent insertion
`/gsd:plan-phase {decimal_phase}`
<sub>`/clear` first -> fresh context window</sub>
---
**Also available:**
- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
- Review roadmap
---
```
</step>
</process>
<anti_patterns>
- Don't use this for planned work at end of milestone (use /gsd:add-phase)
- Don't insert before Phase 1 (decimal 0.1 makes no sense)
- Don't renumber existing phases
- Don't modify the target phase content
- Don't create plans yet (that's /gsd:plan-phase)
- Don't commit changes (user decides when to commit)
</anti_patterns>
<success_criteria>
Phase insertion is complete when:
- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
- [ ] Phase inserted in correct position (after target phase, before next integer phase)
- [ ] STATE.md updated with roadmap evolution note
- [ ] Decimal number calculated correctly (based on existing decimals)
- [ ] User informed of next steps and dependency implications
</success_criteria>

View File

@@ -23,28 +23,17 @@ Documents are reference material for Claude when planning/executing. Always incl
<process>
<step name="resolve_model_profile" priority="first">
Read model profile for agent spawning:
```bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
MAPPER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-codebase-mapper --raw)
```
Default to "balanced" if not set.
**Model lookup table:**
| Agent | quality | balanced | budget |
|-------|---------|----------|--------|
| gsd-codebase-mapper | sonnet | haiku | haiku |
Store resolved model for use in Task calls below.
</step>
<step name="check_existing">
Check if .planning/codebase/ already exists:
```bash
ls -la .planning/codebase/ 2>/dev/null
CODEBASE_MAP_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/codebase --raw)
[ "$CODEBASE_MAP_EXISTS" = "true" ] && ls -la .planning/codebase/
```
**If exists:**
@@ -268,31 +257,8 @@ Continue to commit_codebase_map.
<step name="commit_codebase_map">
Commit the codebase map:
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
```bash
git add .planning/codebase/*.md
git commit -m "$(cat <<'EOF'
docs: map existing codebase
- STACK.md - Technologies and dependencies
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure
- INTEGRATIONS.md - External services
- CONCERNS.md - Technical debt and issues
EOF
)"
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs: map existing codebase" --files .planning/codebase/*.md
```
Continue to offer_next.

View File

@@ -0,0 +1,363 @@
<purpose>
Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
## 1. Load Context
- 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)
## 2. Gather Milestone Goals
**If MILESTONE-CONTEXT.md exists:**
- Use features and scope from discuss-milestone
- Present summary for confirmation
**If no context file:**
- Present what shipped in last milestone
- Ask: "What do you want to build next?"
- Use AskUserQuestion to explore features, priorities, constraints, scope
## 3. Determine Milestone Version
- Parse last version from MILESTONES.md
- Suggest next version (v1.0 → v1.1, or v2.0 for major)
- Confirm with user
## 4. Update PROJECT.md
Add/update:
```markdown
## Current Milestone: v[X.Y] [Name]
**Goal:** [One sentence describing milestone focus]
**Target features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]
```
Update Active requirements section and "Last updated" footer.
## 5. Update STATE.md
```markdown
## Current Position
Phase: Not started (defining requirements)
Plan: —
Status: Defining requirements
Last activity: [today] — Milestone v[X.Y] started
```
Keep Accumulated Context section from previous milestone.
## 6. Cleanup and Commit
Delete MILESTONE-CONTEXT.md if exists (consumed).
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
```
## 7. Resolve Model Profile
```bash
RESEARCHER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-project-researcher --raw)
SYNTHESIZER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-research-synthesizer --raw)
ROADMAPPER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-roadmapper --raw)
```
## 8. Research Decision
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
**If "Research first":**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning 4 researchers in parallel...
→ Stack, Features, Architecture, Pitfalls
```
```bash
mkdir -p .planning/research
```
Spawn 4 parallel gsd-project-researcher agents. Each uses this template with dimension-specific fields:
**Common structure for all 4 researchers:**
```
Task(prompt="
<research_type>Project Research — {DIMENSION} for [new features].</research_type>
<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.
{EXISTING_CONTEXT}
Focus ONLY on what's needed for the NEW features.
</milestone_context>
<question>{QUESTION}</question>
<project_context>[PROJECT.md summary]</project_context>
<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}
</output>
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
```
**Dimension-specific fields:**
| Field | Stack | Features | Architecture | Pitfalls |
|-------|-------|----------|-------------|----------|
| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from PROJECT.md] | Existing features (already built): [from PROJECT.md] | Existing architecture: [from PROJECT.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
| GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
After all 4 complete, spawn synthesizer:
```
Task(prompt="
Synthesize research outputs into SUMMARY.md.
Read: .planning/research/STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md
Write to: .planning/research/SUMMARY.md
Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
Commit after writing.
", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
```
Display key findings from SUMMARY.md:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Stack additions:** [from SUMMARY.md]
**Feature table stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]
```
**If "Skip research":** Continue to Step 9.
## 9. Define Requirements
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► DEFINING REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
**If research exists:** Read FEATURES.md, extract feature categories.
Present features by category:
```
## [Category 1]
**Table stakes:** Feature A, Feature B
**Differentiators:** Feature C, Feature D
**Research notes:** [any relevant notes]
```
**If no research:** Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
**Scope each category** via AskUserQuestion (multiSelect: true):
- "[Feature 1]" — [brief description]
- "[Feature 2]" — [brief description]
- "None for this milestone" — Defer entire category
Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
**Identify gaps** via AskUserQuestion:
- "No, research covered it" — Proceed
- "Yes, let me add some" — Capture additions
**Generate REQUIREMENTS.md:**
- v1 Requirements grouped by category (checkboxes, REQ-IDs)
- Future Requirements (deferred)
- Out of Scope (explicit exclusions with reasoning)
- Traceability section (empty, filled by roadmap)
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, NOTIF-02). Continue numbering from existing.
**Requirement quality criteria:**
Good requirements are:
- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
- **User-centric:** "User can X" (not "System does Y")
- **Atomic:** One capability per requirement (not "User can login and manage profile")
- **Independent:** Minimal dependencies on other requirements
Present FULL requirements list for confirmation:
```
## Milestone v[X.Y] Requirements
### [Category 1]
- [ ] **CAT1-01**: User can do X
- [ ] **CAT1-02**: User can do Y
### [Category 2]
- [ ] **CAT2-01**: User can do Z
Does this capture what you're building? (yes / adjust)
```
If "adjust": Return to scoping.
**Commit requirements:**
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
```
## 10. Create Roadmap
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► 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).
```
Task(prompt="
<planning_context>
@.planning/PROJECT.md
@.planning/REQUIREMENTS.md
@.planning/research/SUMMARY.md (if exists)
@.planning/config.json
@.planning/MILESTONES.md
</planning_context>
<instructions>
Create roadmap for milestone v[X.Y]:
1. Start phase numbering from [N]
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)
5. Validate 100% coverage
6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
7. Return ROADMAP CREATED with summary
Write files first, then return.
</instructions>
", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
```
**Handle return:**
**If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
**If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
```
## Proposed Roadmap
**[N] phases** | **[X] requirements mapped** | All covered ✓
| # | Phase | Goal | Requirements | Success Criteria |
|---|-------|------|--------------|------------------|
| [N] | [Name] | [Goal] | [REQ-IDs] | [count] |
### Phase Details
**Phase [N]: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]
```
**Ask for approval** via AskUserQuestion:
- "Approve" — Commit and continue
- "Adjust phases" — Tell me what to change
- "Review full file" — Show raw ROADMAP.md
**If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
**If "Review":** Display raw ROADMAP.md, re-ask.
**Commit roadmap** (after approval):
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js 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 ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Milestone v[X.Y]: [Name]**
| Artifact | Location |
|----------------|-----------------------------|
| Project | `.planning/PROJECT.md` |
| Research | `.planning/research/` |
| Requirements | `.planning/REQUIREMENTS.md` |
| Roadmap | `.planning/ROADMAP.md` |
**[N] phases** | **[X] requirements** | Ready to build ✓
## ▶ Next Up
**Phase [N]: [Phase Name]** — [Goal]
`/gsd:discuss-phase [N]` — gather context and clarify approach
<sub>`/clear` first → fresh context window</sub>
Also: `/gsd:plan-phase [N]` — skip discussion, plan directly
```
</process>
<success_criteria>
- [ ] PROJECT.md updated with Current Milestone section
- [ ] STATE.md reset for new milestone
- [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
- [ ] 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
- [ ] Roadmap files written immediately (not draft)
- [ ] User feedback incorporated (if any)
- [ ] ROADMAP.md phases continue from previous milestone
- [ ] All commits made (if planning docs committed)
- [ ] User knows next step: `/gsd:discuss-phase [N]`
**Atomic commits:** Each phase commits its artifacts immediately.
</success_criteria>

View File

@@ -0,0 +1,937 @@
<purpose>
Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
## 1. Setup
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
1. **Abort if project exists:**
```bash
PROJECT_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/PROJECT.md --raw)
[ "$PROJECT_EXISTS" = "true" ] && echo "ERROR: Project already initialized. Use /gsd:progress" && exit 1
```
2. **Initialize git repo in THIS directory** (required even if inside a parent repo):
```bash
if [ -d .git ] || [ -f .git ]; then
echo "Git repo exists in current directory"
else
git init
echo "Initialized new git repo"
fi
```
3. **Detect existing code (brownfield detection):**
```bash
CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
HAS_CODEBASE_MAP=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/codebase --raw)
[ "$HAS_CODEBASE_MAP" = "true" ] && HAS_CODEBASE_MAP="yes"
```
**You MUST run all bash commands above using the Bash tool before proceeding.**
## 2. Brownfield Offer
**If existing code detected and .planning/codebase/ doesn't exist:**
Check the results from setup step:
- If `CODE_FILES` is non-empty OR `HAS_PACKAGE` is "yes"
- AND `HAS_CODEBASE_MAP` is NOT "yes"
Use AskUserQuestion:
- header: "Existing Code"
- question: "I detected existing code in this directory. Would you like to map the codebase first?"
- options:
- "Map codebase first" — Run /gsd:map-codebase to understand existing architecture (Recommended)
- "Skip mapping" — Proceed with project initialization
**If "Map codebase first":**
```
Run `/gsd:map-codebase` first, then return to `/gsd:new-project`
```
Exit command.
**If "Skip mapping":** Continue to Step 3.
**If no existing code detected OR codebase already mapped:** Continue to Step 3.
## 3. Deep Questioning
**Display stage banner:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► QUESTIONING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Open the conversation:**
Ask inline (freeform, NOT AskUserQuestion):
"What do you want to build?"
Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
**Follow the thread:**
Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
Keep following threads. Each answer opens new threads to explore. Ask about:
- What excited them
- What problem sparked this
- What they mean by vague terms
- What it would actually look like
- What's already decided
Consult `questioning.md` for techniques:
- Challenge vagueness
- Make abstract concrete
- Surface assumptions
- Find edges
- Reveal motivation
**Check context (background, not out loud):**
As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
**Decision gate:**
When you could write a clear PROJECT.md, use AskUserQuestion:
- header: "Ready?"
- question: "I think I understand what you're after. Ready to create PROJECT.md?"
- options:
- "Create PROJECT.md" — Let's move forward
- "Keep exploring" — I want to share more / ask me more
If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
Loop until "Create PROJECT.md" selected.
## 4. Write PROJECT.md
Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
**For greenfield projects:**
Initialize requirements as hypotheses:
```markdown
## Requirements
### Validated
(None yet — ship to validate)
### Active
- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]
### Out of Scope
- [Exclusion 1] — [why]
- [Exclusion 2] — [why]
```
All Active requirements are hypotheses until shipped and validated.
**For brownfield projects (codebase map exists):**
Infer Validated requirements from existing code:
1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
2. Identify what the codebase already does
3. These become the initial Validated set
```markdown
## Requirements
### Validated
- ✓ [Existing capability 1] — existing
- ✓ [Existing capability 2] — existing
- ✓ [Existing capability 3] — existing
### Active
- [ ] [New requirement 1]
- [ ] [New requirement 2]
### Out of Scope
- [Exclusion 1] — [why]
```
**Key Decisions:**
Initialize with any decisions made during questioning:
```markdown
## Key Decisions
| Decision | Rationale | Outcome |
|----------|-----------|---------|
| [Choice from questioning] | [Why] | — Pending |
```
**Last updated footer:**
```markdown
---
*Last updated: [date] after initialization*
```
Do not compress. Capture everything gathered.
**Commit PROJECT.md:**
```bash
mkdir -p .planning
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
```
## 5. Workflow Preferences
**Round 1 — Core workflow settings (4 questions):**
```
questions: [
{
header: "Mode",
question: "How do you want to work?",
multiSelect: false,
options: [
{ label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
{ label: "Interactive", description: "Confirm at each step" }
]
},
{
header: "Depth",
question: "How thorough should planning be?",
multiSelect: false,
options: [
{ label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
{ label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
{ label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
]
},
{
header: "Execution",
question: "Run plans in parallel?",
multiSelect: false,
options: [
{ label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
{ label: "Sequential", description: "One plan at a time" }
]
},
{
header: "Git Tracking",
question: "Commit planning docs to git?",
multiSelect: false,
options: [
{ label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
{ label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
]
}
]
```
**Round 2 — Workflow agents:**
These spawn additional agents during planning/execution. They add tokens and time but improve quality.
| Agent | When it runs | What it does |
|-------|--------------|--------------|
| **Researcher** | Before planning each phase | Investigates domain, finds patterns, surfaces gotchas |
| **Plan Checker** | After plan is created | Verifies plan actually achieves the phase goal |
| **Verifier** | After phase execution | Confirms must-haves were delivered |
All recommended for important projects. Skip for quick experiments.
```
questions: [
{
header: "Research",
question: "Research before planning each phase? (adds tokens/time)",
multiSelect: false,
options: [
{ label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
{ label: "No", description: "Plan directly from requirements" }
]
},
{
header: "Plan Check",
question: "Verify plans will achieve their goals? (adds tokens/time)",
multiSelect: false,
options: [
{ label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
{ label: "No", description: "Execute plans without verification" }
]
},
{
header: "Verifier",
question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
multiSelect: false,
options: [
{ label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
{ label: "No", description: "Trust execution, skip verification" }
]
},
{
header: "Model Profile",
question: "Which AI models for planning agents?",
multiSelect: false,
options: [
{ label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
{ label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
{ label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
]
}
]
```
Create `.planning/config.json` with all settings:
```json
{
"mode": "yolo|interactive",
"depth": "quick|standard|comprehensive",
"parallelization": true|false,
"commit_docs": true|false,
"model_profile": "quality|balanced|budget",
"workflow": {
"research": true|false,
"plan_check": true|false,
"verifier": true|false
}
}
```
**If commit_docs = No:**
- Set `commit_docs: false` in config.json
- Add `.planning/` to `.gitignore` (create if needed)
**If commit_docs = Yes:**
- No additional gitignore entries needed
**Commit config.json:**
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "chore: add project config" --files .planning/config.json
```
**Note:** Run `/gsd:settings` anytime to update these preferences.
## 5.5. Resolve Model Profile
Read model profile for agent spawning:
```bash
RESEARCHER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-project-researcher --raw)
SYNTHESIZER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-research-synthesizer --raw)
ROADMAPPER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-roadmapper --raw)
```
## 6. Research Decision
Use AskUserQuestion:
- header: "Research"
- question: "Research the domain ecosystem before defining requirements?"
- options:
- "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
- "Skip research" — I know this domain well, go straight to requirements
**If "Research first":**
Display stage banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Researching [domain] ecosystem...
```
Create research directory:
```bash
mkdir -p .planning/research
```
**Determine milestone context:**
Check if this is greenfield or subsequent milestone:
- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
Display spawning indicator:
```
◆ Spawning 4 researchers in parallel...
→ Stack research
→ Features research
→ Architecture research
→ Pitfalls research
```
Spawn 4 parallel gsd-project-researcher agents with rich context:
```
Task(prompt="First, read ~/.claude/agents/gsd-project-researcher.md for your role and instructions.
<research_type>
Project Research — Stack dimension for [domain].
</research_type>
<milestone_context>
[greenfield OR subsequent]
Greenfield: Research the standard stack for building [domain] from scratch.
Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
</milestone_context>
<question>
What's the standard 2025 stack for [domain]?
</question>
<project_context>
[PROJECT.md summary - core value, constraints, what they're building]
</project_context>
<downstream_consumer>
Your STACK.md feeds into roadmap creation. Be prescriptive:
- Specific libraries with versions
- Clear rationale for each choice
- What NOT to use and why
</downstream_consumer>
<quality_gate>
- [ ] Versions are current (verify with Context7/official docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Confidence levels assigned to each recommendation
</quality_gate>
<output>
Write to: .planning/research/STACK.md
Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
Task(prompt="First, read ~/.claude/agents/gsd-project-researcher.md for your role and instructions.
<research_type>
Project Research — Features dimension for [domain].
</research_type>
<milestone_context>
[greenfield OR subsequent]
Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
Subsequent: How do [target features] typically work? What's expected behavior?
</milestone_context>
<question>
What features do [domain] products have? What's table stakes vs differentiating?
</question>
<project_context>
[PROJECT.md summary]
</project_context>
<downstream_consumer>
Your FEATURES.md feeds into requirements definition. Categorize clearly:
- Table stakes (must have or users leave)
- Differentiators (competitive advantage)
- Anti-features (things to deliberately NOT build)
</downstream_consumer>
<quality_gate>
- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies between features identified
</quality_gate>
<output>
Write to: .planning/research/FEATURES.md
Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
Task(prompt="First, read ~/.claude/agents/gsd-project-researcher.md for your role and instructions.
<research_type>
Project Research — Architecture dimension for [domain].
</research_type>
<milestone_context>
[greenfield OR subsequent]
Greenfield: How are [domain] systems typically structured? What are major components?
Subsequent: How do [target features] integrate with existing [domain] architecture?
</milestone_context>
<question>
How are [domain] systems typically structured? What are major components?
</question>
<project_context>
[PROJECT.md summary]
</project_context>
<downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
- Component boundaries (what talks to what)
- Data flow (how information moves)
- Suggested build order (dependencies between components)
</downstream_consumer>
<quality_gate>
- [ ] Components clearly defined with boundaries
- [ ] Data flow direction explicit
- [ ] Build order implications noted
</quality_gate>
<output>
Write to: .planning/research/ARCHITECTURE.md
Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
Task(prompt="First, read ~/.claude/agents/gsd-project-researcher.md for your role and instructions.
<research_type>
Project Research — Pitfalls dimension for [domain].
</research_type>
<milestone_context>
[greenfield OR subsequent]
Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
Subsequent: What are common mistakes when adding [target features] to [domain]?
</milestone_context>
<question>
What do [domain] projects commonly get wrong? Critical mistakes?
</question>
<project_context>
[PROJECT.md summary]
</project_context>
<downstream_consumer>
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
- Warning signs (how to detect early)
- Prevention strategy (how to avoid)
- Which phase should address it
</downstream_consumer>
<quality_gate>
- [ ] Pitfalls are specific to this domain (not generic advice)
- [ ] Prevention strategies are actionable
- [ ] Phase mapping included where relevant
</quality_gate>
<output>
Write to: .planning/research/PITFALLS.md
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
```
After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
```
Task(prompt="
<task>
Synthesize research outputs into SUMMARY.md.
</task>
<research_files>
Read these files:
- .planning/research/STACK.md
- .planning/research/FEATURES.md
- .planning/research/ARCHITECTURE.md
- .planning/research/PITFALLS.md
</research_files>
<output>
Write to: .planning/research/SUMMARY.md
Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
Commit after writing.
</output>
", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
```
Display research complete banner and key findings:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Key Findings
**Stack:** [from SUMMARY.md]
**Table Stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]
Files: `.planning/research/`
```
**If "Skip research":** Continue to Step 7.
## 7. Define Requirements
Display stage banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► DEFINING REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Load context:**
Read PROJECT.md and extract:
- Core value (the ONE thing that must work)
- Stated constraints (budget, timeline, tech limitations)
- Any explicit scope boundaries
**If research exists:** Read research/FEATURES.md and extract feature categories.
**Present features by category:**
```
Here are the features for [domain]:
## Authentication
**Table stakes:**
- Sign up with email/password
- Email verification
- Password reset
- Session management
**Differentiators:**
- Magic link login
- OAuth (Google, GitHub)
- 2FA
**Research notes:** [any relevant notes]
---
## [Next Category]
...
```
**If no research:** Gather requirements through conversation instead.
Ask: "What are the main things users need to be able to do?"
For each capability mentioned:
- Ask clarifying questions to make it specific
- Probe for related capabilities
- Group into categories
**Scope each category:**
For each category, use AskUserQuestion:
- header: "[Category name]"
- question: "Which [category] features are in v1?"
- multiSelect: true
- options:
- "[Feature 1]" — [brief description]
- "[Feature 2]" — [brief description]
- "[Feature 3]" — [brief description]
- "None for v1" — Defer entire category
Track responses:
- Selected features → v1 requirements
- Unselected table stakes → v2 (users expect these)
- Unselected differentiators → out of scope
**Identify gaps:**
Use AskUserQuestion:
- header: "Additions"
- question: "Any requirements research missed? (Features specific to your vision)"
- options:
- "No, research covered it" — Proceed
- "Yes, let me add some" — Capture additions
**Validate core value:**
Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
**Generate REQUIREMENTS.md:**
Create `.planning/REQUIREMENTS.md` with:
- v1 Requirements grouped by category (checkboxes, REQ-IDs)
- v2 Requirements (deferred)
- Out of Scope (explicit exclusions with reasoning)
- Traceability section (empty, filled by roadmap)
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
**Requirement quality criteria:**
Good requirements are:
- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
- **User-centric:** "User can X" (not "System does Y")
- **Atomic:** One capability per requirement (not "User can login and manage profile")
- **Independent:** Minimal dependencies on other requirements
Reject vague requirements. Push for specificity:
- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
- "Support sharing" → "User can share post via link that opens in recipient's browser"
**Present full requirements list:**
Show every requirement (not counts) for user confirmation:
```
## v1 Requirements
### Authentication
- [ ] **AUTH-01**: User can create account with email/password
- [ ] **AUTH-02**: User can log in and stay logged in across sessions
- [ ] **AUTH-03**: User can log out from any page
### Content
- [ ] **CONT-01**: User can create posts with text
- [ ] **CONT-02**: User can edit their own posts
[... full list ...]
---
Does this capture what you're building? (yes / adjust)
```
If "adjust": Return to scoping.
**Commit requirements:**
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
```
## 8. Create Roadmap
Display stage banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► CREATING ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning roadmapper...
```
Spawn gsd-roadmapper agent with context:
```
Task(prompt="
<planning_context>
**Project:**
@.planning/PROJECT.md
**Requirements:**
@.planning/REQUIREMENTS.md
**Research (if exists):**
@.planning/research/SUMMARY.md
**Config:**
@.planning/config.json
</planning_context>
<instructions>
Create roadmap:
1. Derive phases from requirements (don't impose structure)
2. Map every v1 requirement to exactly one phase
3. Derive 2-5 success criteria per phase (observable user behaviors)
4. Validate 100% coverage
5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
6. Return ROADMAP CREATED with summary
Write files first, then return. This ensures artifacts persist even if context is lost.
</instructions>
", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
```
**Handle roadmapper return:**
**If `## ROADMAP BLOCKED`:**
- Present blocker information
- Work with user to resolve
- Re-spawn when resolved
**If `## ROADMAP CREATED`:**
Read the created ROADMAP.md and present it nicely inline:
```
---
## Proposed Roadmap
**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
| # | Phase | Goal | Requirements | Success Criteria |
|---|-------|------|--------------|------------------|
| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
...
### Phase Details
**Phase 1: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]
3. [criterion]
**Phase 2: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]
[... continue for all phases ...]
---
```
**CRITICAL: Ask for approval before committing:**
Use AskUserQuestion:
- header: "Roadmap"
- question: "Does this roadmap structure work for you?"
- options:
- "Approve" — Commit and continue
- "Adjust phases" — Tell me what to change
- "Review full file" — Show raw ROADMAP.md
**If "Approve":** Continue to commit.
**If "Adjust phases":**
- Get user's adjustment notes
- Re-spawn roadmapper with revision context:
```
Task(prompt="
<revision>
User feedback on roadmap:
[user's notes]
Current ROADMAP.md: @.planning/ROADMAP.md
Update the roadmap based on feedback. Edit files in place.
Return ROADMAP REVISED with changes made.
</revision>
", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
```
- Present revised roadmap
- Loop until user approves
**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
**Commit roadmap (after approval):**
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
```
## 9. Done
Present completion with next steps:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PROJECT INITIALIZED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**[Project Name]**
| Artifact | Location |
|----------------|-----------------------------|
| Project | `.planning/PROJECT.md` |
| Config | `.planning/config.json` |
| Research | `.planning/research/` |
| Requirements | `.planning/REQUIREMENTS.md` |
| Roadmap | `.planning/ROADMAP.md` |
**[N] phases** | **[X] requirements** | Ready to build ✓
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
/gsd:discuss-phase 1 — gather context and clarify approach
<sub>/clear first → fresh context window</sub>
---
**Also available:**
- /gsd:plan-phase 1 — skip discussion, plan directly
───────────────────────────────────────────────────────────────
```
</process>
<output>
- `.planning/PROJECT.md`
- `.planning/config.json`
- `.planning/research/` (if research selected)
- `STACK.md`
- `FEATURES.md`
- `ARCHITECTURE.md`
- `PITFALLS.md`
- `SUMMARY.md`
- `.planning/REQUIREMENTS.md`
- `.planning/ROADMAP.md`
- `.planning/STATE.md`
</output>
<success_criteria>
- [ ] .planning/ directory created
- [ ] Git repo initialized
- [ ] Brownfield detection completed
- [ ] Deep questioning completed (threads followed, not rushed)
- [ ] PROJECT.md captures full context → **committed**
- [ ] config.json has workflow mode, depth, parallelization → **committed**
- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
- [ ] Requirements gathered (from research or conversation)
- [ ] User scoped each category (v1/v2/out of scope)
- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
- [ ] gsd-roadmapper spawned with context
- [ ] Roadmap files written immediately (not draft)
- [ ] User feedback incorporated (if any)
- [ ] ROADMAP.md created with phases, requirement mappings, success criteria
- [ ] STATE.md initialized
- [ ] REQUIREMENTS.md traceability updated
- [ ] User knows next step is `/gsd:discuss-phase 1`
**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
</success_criteria>

View File

@@ -0,0 +1,254 @@
<purpose>
Create all phases necessary to close gaps identified by `/gsd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/gsd:add-phase` per gap.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
## 1. Load Audit Results
```bash
# Find the most recent audit file
ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | head -1
```
Parse YAML frontmatter to extract structured gaps:
- `gaps.requirements` — unsatisfied requirements
- `gaps.integration` — missing cross-phase connections
- `gaps.flows` — broken E2E flows
If no audit file exists or has no gaps, error:
```
No audit gaps found. Run `/gsd:audit-milestone` first.
```
## 2. Prioritize Gaps
Group gaps by priority from REQUIREMENTS.md:
| Priority | Action |
|----------|--------|
| `must` | Create phase, blocks milestone |
| `should` | Create phase, recommended |
| `nice` | Ask user: include or defer? |
For integration/flow gaps, infer priority from affected requirements.
## 3. Group Gaps into Phases
Cluster related gaps into logical phases:
**Grouping rules:**
- Same affected phase → combine into one fix phase
- Same subsystem (auth, API, UI) → combine
- Dependency order (fix stubs before wiring)
- Keep phases focused: 2-4 tasks each
**Example grouping:**
```
Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
Gap: Integration Phase 1→3 (Auth not passed to API calls)
Gap: Flow "View dashboard" broken at data fetch
→ Phase 6: "Wire Dashboard to API"
- Add fetch to Dashboard.tsx
- Include auth header in fetch
- Handle response, update state
- Render user data
```
## 4. Determine Phase Numbers
Find highest existing phase:
```bash
ls -d .planning/phases/*/ | sort -V | tail -1
```
New phases continue from there:
- If Phase 5 is highest, gaps become Phase 6, 7, 8...
## 5. Present Gap Closure Plan
```markdown
## Gap Closure Plan
**Milestone:** {version}
**Gaps to close:** {N} requirements, {M} integration, {K} flows
### Proposed Phases
**Phase {N}: {Name}**
Closes:
- {REQ-ID}: {description}
- Integration: {from} → {to}
Tasks: {count}
**Phase {N+1}: {Name}**
Closes:
- {REQ-ID}: {description}
- Flow: {flow name}
Tasks: {count}
{If nice-to-have gaps exist:}
### Deferred (nice-to-have)
These gaps are optional. Include them?
- {gap description}
- {gap description}
---
Create these {X} phases? (yes / adjust / defer all optional)
```
Wait for user confirmation.
## 6. Update ROADMAP.md
Add new phases to current milestone:
```markdown
### Phase {N}: {Name}
**Goal:** {derived from gaps being closed}
**Requirements:** {REQ-IDs being satisfied}
**Gap Closure:** Closes gaps from audit
### Phase {N+1}: {Name}
...
```
## 7. Create Phase Directories
```bash
mkdir -p ".planning/phases/{NN}-{name}"
```
## 8. Commit Roadmap Update
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md
```
## 9. Offer Next Steps
```markdown
## ✓ Gap Closure Phases Created
**Phases added:** {N} - {M}
**Gaps addressed:** {count} requirements, {count} integration, {count} flows
---
## ▶ Next Up
**Plan first gap closure phase**
`/gsd:plan-phase {N}`
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
- `/gsd:execute-phase {N}` — if plans already exist
- `cat .planning/ROADMAP.md` — see updated roadmap
---
**After all gap phases complete:**
`/gsd:audit-milestone` — re-audit to verify gaps closed
`/gsd:complete-milestone {version}` — archive when audit passes
```
</process>
<gap_to_phase_mapping>
## How Gaps Become Tasks
**Requirement gap → Tasks:**
```yaml
gap:
id: DASH-01
description: "User sees their data"
reason: "Dashboard exists but doesn't fetch from API"
missing:
- "useEffect with fetch to /api/user/data"
- "State for user data"
- "Render user data in JSX"
becomes:
phase: "Wire Dashboard Data"
tasks:
- name: "Add data fetching"
files: [src/components/Dashboard.tsx]
action: "Add useEffect that fetches /api/user/data on mount"
- name: "Add state management"
files: [src/components/Dashboard.tsx]
action: "Add useState for userData, loading, error states"
- name: "Render user data"
files: [src/components/Dashboard.tsx]
action: "Replace placeholder with userData.map rendering"
```
**Integration gap → Tasks:**
```yaml
gap:
from_phase: 1
to_phase: 3
connection: "Auth token → API calls"
reason: "Dashboard API calls don't include auth header"
missing:
- "Auth header in fetch calls"
- "Token refresh on 401"
becomes:
phase: "Add Auth to Dashboard API Calls"
tasks:
- name: "Add auth header to fetches"
files: [src/components/Dashboard.tsx, src/lib/api.ts]
action: "Include Authorization header with token in all API calls"
- name: "Handle 401 responses"
files: [src/lib/api.ts]
action: "Add interceptor to refresh token or redirect to login on 401"
```
**Flow gap → Tasks:**
```yaml
gap:
name: "User views dashboard after login"
broken_at: "Dashboard data load"
reason: "No fetch call"
missing:
- "Fetch user data on mount"
- "Display loading state"
- "Render user data"
becomes:
# Usually same phase as requirement/integration gap
# Flow gaps often overlap with other gap types
```
</gap_to_phase_mapping>
<success_criteria>
- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
- [ ] Gaps prioritized (must/should/nice)
- [ ] Gaps grouped into logical phases
- [ ] User confirmed phase plan
- [ ] ROADMAP.md updated with new phases
- [ ] Phase directories created
- [ ] Changes committed
- [ ] User knows to run `/gsd:plan-phase` next
</success_criteria>

View File

@@ -0,0 +1,400 @@
<purpose>
Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates gsd-phase-researcher, gsd-planner, and gsd-plan-checker agents with a revision loop (max 3 iterations).
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
@~/.claude/get-shit-done/references/ui-brand.md
</required_reading>
<process>
## 1. Validate Environment and Resolve Model Profile
```bash
PLANNING_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning --raw)
echo "$PLANNING_EXISTS"
```
**If not found:** Error — run `/gsd:new-project` first.
**Resolve models:**
```bash
RESEARCHER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-phase-researcher --raw)
PLANNER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-planner --raw)
CHECKER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-plan-checker --raw)
```
## 2. Parse and Normalize Arguments
Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`).
**If no phase number:** Detect next unplanned phase from roadmap.
**Find phase directory:**
```bash
PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "$PHASE")
PHASE_DIR=$(echo "$PHASE_INFO" | grep -o '"directory":"[^"]*"' | cut -d'"' -f4)
```
If `found` is false, validate phase exists in ROADMAP.md. If valid, create the directory:
```bash
PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //')
PHASE_SLUG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$PHASE_NAME" --raw)
PADDED=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "$PHASE" --raw | grep -o '^[0-9]*' || printf "%02d" "$PHASE")
mkdir -p ".planning/phases/${PADDED}-${PHASE_SLUG}"
PHASE_DIR=".planning/phases/${PADDED}-${PHASE_SLUG}"
```
**Check for existing research and plans:**
```bash
ls ${PHASE_DIR}/*-RESEARCH.md 2>/dev/null
ls ${PHASE_DIR}/*-PLAN.md 2>/dev/null
```
## 3. Validate Phase
```bash
grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
```
**If not found:** Error with available phases. **If found:** Extract phase number, name, description.
## 4. Load CONTEXT.md
```bash
CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null)
```
**CRITICAL:** Store `CONTEXT_CONTENT` now — pass to researcher, planner, checker, and revision agents.
If CONTEXT.md exists, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md`
## 5. Handle Research
**Skip if:** `--gaps` flag, `--skip-research` flag, or config `workflow.research=false` (without `--research` override).
```bash
WORKFLOW_RESEARCH=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw | grep '^research=' | cut -d= -f2)
```
**If RESEARCH.md exists AND no `--research` flag:** Use existing, skip to step 6.
**If RESEARCH.md missing OR `--research` flag:**
Display banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCHING PHASE {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning researcher...
```
### Spawn gsd-phase-researcher
```bash
PHASE_DESC=$(grep -A3 "Phase ${PHASE}:" .planning/ROADMAP.md)
REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requirements" | head -50)
DECISIONS=$(grep -A20 "### Decisions Made" .planning/STATE.md 2>/dev/null)
```
Research prompt:
```markdown
<objective>
Research how to implement Phase {phase_number}: {phase_name}
Answer: "What do I need to know to PLAN this phase well?"
</objective>
<phase_context>
IMPORTANT: If CONTEXT.md exists below, it contains user decisions from /gsd:discuss-phase.
- **Decisions** = Locked — research THESE deeply, no alternatives
- **Claude's Discretion** = Freedom areas — research options, recommend
- **Deferred Ideas** = Out of scope — ignore
{context_content}
</phase_context>
<additional_context>
**Phase description:** {phase_description}
**Requirements:** {requirements}
**Prior decisions:** {decisions}
</additional_context>
<output>
Write to: {phase_dir}/{phase}-RESEARCH.md
</output>
```
```
Task(
prompt="First, read ~/.claude/agents/gsd-phase-researcher.md for your role and instructions.\n\n" + research_prompt,
subagent_type="general-purpose",
model="{researcher_model}",
description="Research Phase {phase}"
)
```
### Handle Researcher Return
- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
- **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
## 6. Check Existing Plans
```bash
ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
```
**If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
## 7. Read Context Files
Read and store for planner agent (`@` syntax doesn't work across Task() boundaries):
```bash
STATE_CONTENT=$(cat .planning/STATE.md)
ROADMAP_CONTENT=$(cat .planning/ROADMAP.md)
REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)
RESEARCH_CONTENT=$(cat "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null)
VERIFICATION_CONTENT=$(cat "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null)
UAT_CONTENT=$(cat "${PHASE_DIR}"/*-UAT.md 2>/dev/null)
```
## 8. Spawn gsd-planner Agent
Display banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PLANNING PHASE {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning planner...
```
Planner prompt:
```markdown
<planning_context>
**Phase:** {phase_number}
**Mode:** {standard | gap_closure}
**Project State:** {state_content}
**Roadmap:** {roadmap_content}
**Requirements:** {requirements_content}
**Phase Context:**
IMPORTANT: If context exists below, it contains USER DECISIONS from /gsd:discuss-phase.
- **Decisions** = LOCKED — honor exactly, do not revisit
- **Claude's Discretion** = Freedom — make implementation choices
- **Deferred Ideas** = Out of scope — do NOT include
{context_content}
**Research:** {research_content}
**Gap Closure (if --gaps):** {verification_content} {uat_content}
</planning_context>
<downstream_consumer>
Output consumed by /gsd:execute-phase. Plans need:
- Frontmatter (wave, depends_on, files_modified, autonomous)
- Tasks in XML format
- Verification criteria
- must_haves for goal-backward verification
</downstream_consumer>
<quality_gate>
- [ ] PLAN.md files created in phase directory
- [ ] Each plan has valid frontmatter
- [ ] Tasks are specific and actionable
- [ ] Dependencies correctly identified
- [ ] Waves assigned for parallel execution
- [ ] must_haves derived from phase goal
</quality_gate>
```
```
Task(
prompt="First, read ~/.claude/agents/gsd-planner.md for your role and instructions.\n\n" + filled_prompt,
subagent_type="general-purpose",
model="{planner_model}",
description="Plan Phase {phase}"
)
```
## 9. Handle Planner Return
- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or config `workflow.plan_check=false`: skip to step 13. Otherwise: step 10.
```bash
WORKFLOW_PLAN_CHECK=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw | grep '^plan_checker=' | cut -d= -f2)
```
- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
## 10. Spawn gsd-plan-checker Agent
Display banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► VERIFYING PLANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning plan checker...
```
```bash
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
```
Checker prompt:
```markdown
<verification_context>
**Phase:** {phase_number}
**Phase Goal:** {goal from ROADMAP}
**Plans to verify:** {plans_content}
**Requirements:** {requirements_content}
**Phase Context:**
IMPORTANT: Plans MUST honor user decisions. Flag as issue if plans contradict.
- **Decisions** = LOCKED — plans must implement exactly
- **Claude's Discretion** = Freedom areas — plans can choose approach
- **Deferred Ideas** = Out of scope — plans must NOT include
{context_content}
</verification_context>
<expected_output>
- ## VERIFICATION PASSED — all checks pass
- ## ISSUES FOUND — structured issue list
</expected_output>
```
```
Task(
prompt=checker_prompt,
subagent_type="gsd-plan-checker",
model="{checker_model}",
description="Verify Phase {phase} plans"
)
```
## 11. Handle Checker Return
- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
## 12. Revision Loop (Max 3 Iterations)
Track `iteration_count` (starts at 1 after initial plan + check).
**If iteration_count < 3:**
Display: `Sending back to planner for revision... (iteration {N}/3)`
```bash
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
```
Revision prompt:
```markdown
<revision_context>
**Phase:** {phase_number}
**Mode:** revision
**Existing plans:** {plans_content}
**Checker issues:** {structured_issues_from_checker}
**Phase Context:**
Revisions MUST still honor user decisions.
{context_content}
</revision_context>
<instructions>
Make targeted updates to address checker issues.
Do NOT replan from scratch unless issues are fundamental.
Return what changed.
</instructions>
```
```
Task(
prompt="First, read ~/.claude/agents/gsd-planner.md for your role and instructions.\n\n" + revision_prompt,
subagent_type="general-purpose",
model="{planner_model}",
description="Revise Phase {phase} plans"
)
```
After planner returns -> spawn checker again (step 10), increment iteration_count.
**If iteration_count >= 3:**
Display: `Max iterations reached. {N} issues remain:` + issue list
Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
## 13. Present Final Status
Route to `<offer_next>`.
</process>
<offer_next>
Output this markdown directly (not as a code block):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PHASE {X} PLANNED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Phase {X}: {Name}** — {N} plan(s) in {M} wave(s)
| Wave | Plans | What it builds |
|------|-------|----------------|
| 1 | 01, 02 | [objectives] |
| 2 | 03 | [objective] |
Research: {Completed | Used existing | Skipped}
Verification: {Passed | Passed with override | Skipped}
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Execute Phase {X}** — run all {N} plans
/gsd:execute-phase {X}
<sub>/clear first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
- /gsd:plan-phase {X} --research — re-research first
───────────────────────────────────────────────────────────────
</offer_next>
<success_criteria>
- [ ] .planning/ directory validated
- [ ] Phase validated against roadmap
- [ ] Phase directory created if needed
- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
- [ ] Research completed (unless --skip-research or --gaps or exists)
- [ ] gsd-phase-researcher spawned with CONTEXT.md
- [ ] Existing plans checked
- [ ] gsd-planner spawned with CONTEXT.md + RESEARCH.md
- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
- [ ] gsd-plan-checker spawned with CONTEXT.md
- [ ] Verification passed OR user override OR max iterations with user decision
- [ ] User sees status between agent spawns
- [ ] User knows next steps
</success_criteria>

View File

@@ -0,0 +1,354 @@
<purpose>
Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
<step name="verify">
**Verify planning structure exists:**
Use Bash (not Glob) to check—Glob respects .gitignore but .planning/ is often gitignored:
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning --raw
```
If no `.planning/` directory:
```
No planning structure found.
Run /gsd:new-project to start a new project.
```
Exit.
If missing STATE.md: suggest `/gsd:new-project`.
**If ROADMAP.md missing but PROJECT.md exists:**
This means a milestone was completed and archived. Go to **Route F** (between milestones).
If missing both ROADMAP.md and PROJECT.md: suggest `/gsd:new-project`.
</step>
<step name="load">
**Load full project context:**
- Read `.planning/STATE.md` for living memory (position, decisions, issues)
- Read `.planning/ROADMAP.md` for phase structure and objectives
- Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements)
- Read `.planning/config.json` for settings (model_profile, workflow toggles)
</step>
<step name="recent">
**Gather recent work context:**
- Find the 2-3 most recent SUMMARY.md files
- Extract from each: what was accomplished, key decisions, any issues logged
- This shows "what we've been working on"
</step>
<step name="position">
**Parse current position:**
- From STATE.md: current phase, plan number, status
- Calculate: total plans, completed plans, remaining plans
- Note any blockers or concerns
- Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
- Count pending todos: `node ~/.claude/get-shit-done/bin/gsd-tools.js list-todos --raw`
- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
</step>
<step name="report">
**Present rich status report:**
```
# [Project Name]
**Progress:** [████████░░] 8/10 plans complete
**Profile:** [quality/balanced/budget]
## Recent Work
- [Phase X, Plan Y]: [what was accomplished - 1 line]
- [Phase X, Plan Z]: [what was accomplished - 1 line]
## Current Position
Phase [N] of [total]: [phase-name]
Plan [M] of [phase-total]: [status]
CONTEXT: [✓ if CONTEXT.md exists | - if not]
## Key Decisions Made
- [decision 1 from STATE.md]
- [decision 2]
## Blockers/Concerns
- [any blockers or concerns from STATE.md]
## Pending Todos
- [count] pending — /gsd:check-todos to review
## Active Debug Sessions
- [count] active — /gsd:debug to continue
(Only show this section if count > 0)
## What's Next
[Next phase/plan objective from ROADMAP]
```
</step>
<step name="route">
**Determine next action based on verified counts.**
**Step 1: Count plans, summaries, and issues in current phase**
List files in the current phase directory:
```bash
ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l
```
State: "This phase has {X} plans, {Y} summaries."
**Step 1.5: Check for unaddressed UAT gaps**
Check for UAT.md files with status "diagnosed" (has gaps needing fixes).
```bash
# Check for diagnosed UAT with gaps
grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null
```
Track:
- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)
**Step 2: Route based on counts**
| Condition | Meaning | Action |
|-----------|---------|--------|
| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** |
| summaries < plans | Unexecuted plans exist | Go to **Route A** |
| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
| plans = 0 | Phase not yet planned | Go to **Route B** |
---
**Route A: Unexecuted plan exists**
Find the first PLAN.md without matching SUMMARY.md.
Read its `<objective>` section.
```
---
## ▶ Next Up
**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
`/gsd:execute-phase {phase}`
<sub>`/clear` first → fresh context window</sub>
---
```
---
**Route B: Phase needs planning**
Check if `{phase}-CONTEXT.md` exists in phase directory.
**If CONTEXT.md exists:**
```
---
## ▶ Next Up
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
<sub>✓ Context gathered, ready to plan</sub>
`/gsd:plan-phase {phase-number}`
<sub>`/clear` first → fresh context window</sub>
---
```
**If CONTEXT.md does NOT exist:**
```
---
## ▶ Next Up
**Phase {N}: {Name}** — {Goal from ROADMAP.md}
`/gsd:discuss-phase {phase}` — gather context and clarify approach
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
- `/gsd:plan-phase {phase}` — skip discussion, plan directly
- `/gsd:list-phase-assumptions {phase}` — see Claude's assumptions
---
```
---
**Route E: UAT gaps need fix plans**
UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
```
---
## ⚠ UAT Gaps Found
**{phase}-UAT.md** has {N} gaps requiring fixes.
`/gsd:plan-phase {phase} --gaps`
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
- `/gsd:execute-phase {phase}` — execute phase plans
- `/gsd:verify-work {phase}` — run more UAT testing
---
```
---
**Step 3: Check milestone status (only when phase complete)**
Read ROADMAP.md and identify:
1. Current phase number
2. All phase numbers in the current milestone section
Count total phases and identify the highest phase number.
State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
**Route based on milestone status:**
| Condition | Meaning | Action |
|-----------|---------|--------|
| current phase < highest phase | More phases remain | Go to **Route C** |
| current phase = highest phase | Milestone complete | Go to **Route D** |
---
**Route C: Phase complete, more phases remain**
Read ROADMAP.md to get the next phase's name and goal.
```
---
## ✓ Phase {Z} Complete
## ▶ Next Up
**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
`/gsd:discuss-phase {Z+1}` — gather context and clarify approach
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
- `/gsd:plan-phase {Z+1}` — skip discussion, plan directly
- `/gsd:verify-work {Z}` — user acceptance test before continuing
---
```
---
**Route D: Milestone complete**
```
---
## 🎉 Milestone Complete
All {N} phases finished!
## ▶ Next Up
**Complete Milestone** — archive and prepare for next
`/gsd:complete-milestone`
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
- `/gsd:verify-work` — user acceptance test before completing milestone
---
```
---
**Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**
A milestone was completed and archived. Ready to start the next milestone cycle.
Read MILESTONES.md to find the last completed milestone version.
```
---
## ✓ Milestone v{X.Y} Complete
Ready to plan the next milestone.
## ▶ Next Up
**Start Next Milestone** — questioning → research → requirements → roadmap
`/gsd:new-milestone`
<sub>`/clear` first → fresh context window</sub>
---
```
</step>
<step name="edge_cases">
**Handle edge cases:**
- Phase complete but next phase not planned → offer `/gsd:plan-phase [next]`
- All work complete → offer milestone completion
- Blockers present → highlight before offering to continue
- Handoff file exists → mention it, offer `/gsd:resume-work`
</step>
</process>
<success_criteria>
- [ ] Rich context provided (recent work, decisions, issues)
- [ ] Current position clear with visual progress
- [ ] What's next clearly explained
- [ ] Smart routing: /gsd:execute-phase if plans exist, /gsd:plan-phase if not
- [ ] User confirms before any action
- [ ] Seamless handoff to appropriate gsd command
</success_criteria>

View File

@@ -0,0 +1,258 @@
<purpose>
Execute small, ad-hoc tasks with GSD guarantees (atomic commits, STATE.md tracking) while skipping optional agents (research, plan-checker, verifier). Quick mode spawns gsd-planner (quick mode) + gsd-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
**Step 0: Resolve Model Profile**
```bash
PLANNER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-planner --raw)
EXECUTOR_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-executor --raw)
```
---
**Step 1: Pre-flight validation**
Check that an active GSD project exists:
```bash
ROADMAP_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/ROADMAP.md --raw)
if [ "$ROADMAP_EXISTS" != "true" ]; then
echo "Quick mode requires an active project with ROADMAP.md."
echo "Run /gsd:new-project first."
exit 1
fi
```
If validation fails, stop immediately with the error message.
Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.
---
**Step 2: Get task description**
Prompt user interactively for the task description:
```
AskUserQuestion(
header: "Quick Task",
question: "What do you want to do?",
followUp: null
)
```
Store response as `$DESCRIPTION`.
If empty, re-prompt: "Please provide a task description."
Generate slug from description:
```bash
slug=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$DESCRIPTION" --raw | cut -c1-40)
```
---
**Step 3: Calculate next quick task number**
Ensure `.planning/quick/` directory exists and find the next sequential number:
```bash
# Ensure .planning/quick/ exists
mkdir -p .planning/quick
# Find highest existing number and increment
last=$(ls -1d .planning/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1 | xargs -I{} basename {} | grep -oE '^[0-9]+')
if [ -z "$last" ]; then
next_num="001"
else
next_num=$(printf "%03d" $((10#$last + 1)))
fi
```
---
**Step 4: Create quick task directory**
Create the directory for this quick task:
```bash
QUICK_DIR=".planning/quick/${next_num}-${slug}"
mkdir -p "$QUICK_DIR"
```
Report to user:
```
Creating quick task ${next_num}: ${DESCRIPTION}
Directory: ${QUICK_DIR}
```
Store `$QUICK_DIR` for use in orchestration.
---
**Step 5: Spawn planner (quick mode)**
Spawn gsd-planner with quick mode context:
```
Task(
prompt="
<planning_context>
**Mode:** quick
**Directory:** ${QUICK_DIR}
**Description:** ${DESCRIPTION}
**Project State:**
@.planning/STATE.md
</planning_context>
<constraints>
- Create a SINGLE plan with 1-3 focused tasks
- Quick tasks should be atomic and self-contained
- No research phase, no checker phase
- Target ~30% context usage (simple, focused)
</constraints>
<output>
Write plan to: ${QUICK_DIR}/${next_num}-PLAN.md
Return: ## PLANNING COMPLETE with plan path
</output>
",
subagent_type="gsd-planner",
model="{planner_model}",
description="Quick plan: ${DESCRIPTION}"
)
```
After planner returns:
1. Verify plan exists at `${QUICK_DIR}/${next_num}-PLAN.md`
2. Extract plan count (typically 1 for quick tasks)
3. Report: "Plan created: ${QUICK_DIR}/${next_num}-PLAN.md"
If plan not found, error: "Planner failed to create ${next_num}-PLAN.md"
---
**Step 6: Spawn executor**
Spawn gsd-executor with plan reference:
```
Task(
prompt="
Execute quick task ${next_num}.
Plan: @${QUICK_DIR}/${next_num}-PLAN.md
Project state: @.planning/STATE.md
<constraints>
- Execute all tasks in the plan
- Commit each task atomically
- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md
- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
</constraints>
",
subagent_type="gsd-executor",
model="{executor_model}",
description="Execute: ${DESCRIPTION}"
)
```
After executor returns:
1. Verify summary exists at `${QUICK_DIR}/${next_num}-SUMMARY.md`
2. Extract commit hash from executor output
3. Report completion status
If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md"
Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns.
---
**Step 7: Update STATE.md**
Update STATE.md with quick task completion record.
**7a. Check if "Quick Tasks Completed" section exists:**
Read STATE.md and check for `### Quick Tasks Completed` section.
**7b. If section doesn't exist, create it:**
Insert after `### Blockers/Concerns` section:
```markdown
### Quick Tasks Completed
| # | Description | Date | Commit | Directory |
|---|-------------|------|--------|-----------|
```
**7c. Append new row to table:**
```markdown
| ${next_num} | ${DESCRIPTION} | $(node ~/.claude/get-shit-done/bin/gsd-tools.js current-timestamp date --raw) | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
```
**7d. Update "Last activity" line:**
Find and update the line:
```
Last activity: $(node ~/.claude/get-shit-done/bin/gsd-tools.js current-timestamp date --raw) - Completed quick task ${next_num}: ${DESCRIPTION}
```
Use Edit tool to make these changes atomically
---
**Step 8: Final commit and completion**
Stage and commit quick task artifacts:
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${QUICK_DIR}/${next_num}-PLAN.md ${QUICK_DIR}/${next_num}-SUMMARY.md .planning/STATE.md
```
Get final commit hash:
```bash
commit_hash=$(git rev-parse --short HEAD)
```
Display completion output:
```
---
GSD > QUICK TASK COMPLETE
Quick Task ${next_num}: ${DESCRIPTION}
Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md
Commit: ${commit_hash}
---
Ready for next task: /gsd:quick
```
</process>
<success_criteria>
- [ ] ROADMAP.md validation passes
- [ ] User provides task description
- [ ] Slug generated (lowercase, hyphens, max 40 chars)
- [ ] Next number calculated (001, 002, 003...)
- [ ] Directory created at `.planning/quick/NNN-slug/`
- [ ] `${next_num}-PLAN.md` created by planner
- [ ] `${next_num}-SUMMARY.md` created by executor
- [ ] STATE.md updated with quick task row
- [ ] Artifacts committed
</success_criteria>

View File

@@ -0,0 +1,323 @@
<purpose>
Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
</purpose>
<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
<process>
<step name="parse_arguments">
Parse the command arguments:
- Argument is the phase number to remove (integer or decimal)
- Example: `/gsd:remove-phase 17` → phase = 17
- Example: `/gsd:remove-phase 16.1` → phase = 16.1
If no argument provided:
```
ERROR: Phase number required
Usage: /gsd:remove-phase <phase-number>
Example: /gsd:remove-phase 17
```
Exit.
</step>
<step name="load_state">
Load project state:
```bash
cat .planning/STATE.md 2>/dev/null
cat .planning/ROADMAP.md 2>/dev/null
```
Parse current phase number from STATE.md "Current Position" section.
</step>
<step name="validate_phase_exists">
Verify the target phase exists in ROADMAP.md:
1. Search for `### Phase {target}:` heading
2. If not found:
```
ERROR: Phase {target} not found in roadmap
Available phases: [list phase numbers]
```
Exit.
</step>
<step name="validate_future_phase">
Verify the phase is a future phase (not started):
1. Compare target phase to current phase from STATE.md
2. Target must be > current phase number
If target <= current phase:
```
ERROR: Cannot remove Phase {target}
Only future phases can be removed:
- Current phase: {current}
- Phase {target} is current or completed
To abandon current work, use /gsd:pause-work instead.
```
Exit.
3. Check for SUMMARY.md files in phase directory:
```bash
ls .planning/phases/{target}-*/*-SUMMARY.md 2>/dev/null
```
If any SUMMARY.md files exist:
```
ERROR: Phase {target} has completed work
Found executed plans:
- {list of SUMMARY.md files}
Cannot remove phases with completed work.
```
Exit.
</step>
<step name="gather_phase_info">
Collect information about the phase being removed:
1. Extract phase name from ROADMAP.md heading: `### Phase {target}: {Name}`
2. Find phase directory: `.planning/phases/{target}-{slug}/`
3. Find all subsequent phases (integer and decimal) that need renumbering
**Subsequent phase detection:**
For integer phase removal (e.g., 17):
- Find all phases > 17 (integers: 18, 19, 20...)
- Find all decimal phases >= 17.0 and < 18.0 (17.1, 17.2...) → these become 16.x
- Find all decimal phases for subsequent integers (18.1, 19.1...) → renumber with their parent
For decimal phase removal (e.g., 17.1):
- Find all decimal phases > 17.1 and < 18 (17.2, 17.3...) → renumber down
- Integer phases unchanged
List all phases that will be renumbered.
</step>
<step name="confirm_removal">
Present removal summary and confirm:
```
Removing Phase {target}: {Name}
This will:
- Delete: .planning/phases/{target}-{slug}/
- Renumber {N} subsequent phases:
- Phase 18 → Phase 17
- Phase 18.1 → Phase 17.1
- Phase 19 → Phase 18
[etc.]
Proceed? (y/n)
```
Wait for confirmation.
</step>
<step name="delete_phase_directory">
Delete the target phase directory if it exists:
```bash
TARGET_PHASE_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists ".planning/phases/{target}-{slug}" --raw)
if [ "$TARGET_PHASE_EXISTS" = "true" ]; then
rm -rf ".planning/phases/{target}-{slug}"
echo "Deleted: .planning/phases/{target}-{slug}/"
fi
```
If directory doesn't exist, note: "No directory to delete (phase not yet created)"
</step>
<step name="renumber_directories">
Rename all subsequent phase directories:
For each phase directory that needs renumbering (in reverse order to avoid conflicts):
```bash
# Example: renaming 18-dashboard to 17-dashboard
mv ".planning/phases/18-dashboard" ".planning/phases/17-dashboard"
```
Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting.
Also rename decimal phase directories:
- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17)
- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1)
</step>
<step name="rename_files_in_directories">
Rename plan files inside renumbered directories:
For each renumbered directory, rename files that contain the phase number:
```bash
# Inside 17-dashboard (was 18-dashboard):
mv "18-01-PLAN.md" "17-01-PLAN.md"
mv "18-02-PLAN.md" "17-02-PLAN.md"
mv "18-01-SUMMARY.md" "17-01-SUMMARY.md" # if exists
# etc.
```
Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed).
</step>
<step name="update_roadmap">
Update ROADMAP.md:
1. **Remove the phase section entirely:**
- Delete from `### Phase {target}:` to the next phase heading (or section end)
2. **Remove from phase list:**
- Delete line `- [ ] **Phase {target}: {Name}**` or similar
3. **Remove from Progress table:**
- Delete the row for Phase {target}
4. **Renumber all subsequent phases:**
- `### Phase 18:` → `### Phase 17:`
- `- [ ] **Phase 18:` → `- [ ] **Phase 17:`
- Table rows: `| 18. Dashboard |` → `| 17. Dashboard |`
- Plan references: `18-01:` → `17-01:`
5. **Update dependency references:**
- `**Depends on:** Phase 18` → `**Depends on:** Phase 17`
- For the phase that depended on the removed phase:
- `**Depends on:** Phase 17` (removed) → `**Depends on:** Phase 16`
6. **Renumber decimal phases:**
- `### Phase 17.1:` → `### Phase 16.1:` (if integer 17 removed)
- Update all references consistently
Write updated ROADMAP.md.
</step>
<step name="update_state">
Update STATE.md:
1. **Update total phase count:**
- `Phase: 16 of 20` → `Phase: 16 of 19`
2. **Recalculate progress percentage:**
- New percentage based on completed plans / new total plans
Do NOT add a "Roadmap Evolution" note - the git commit is the record.
Write updated STATE.md.
</step>
<step name="update_file_contents">
Search for and update phase references inside plan files:
```bash
# Find files that reference the old phase numbers
grep -r "Phase 18" .planning/phases/17-*/ 2>/dev/null
grep -r "Phase 19" .planning/phases/18-*/ 2>/dev/null
# etc.
```
Update any internal references to reflect new numbering.
</step>
<step name="commit">
Stage and commit the removal:
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
```
The commit message preserves the historical record of what was removed.
</step>
<step name="completion">
Present completion summary:
```
Phase {target} ({original-name}) removed.
Changes:
- Deleted: .planning/phases/{target}-{slug}/
- Renumbered: Phases {first-renumbered}-{last-old} → {first-renumbered-1}-{last-new}
- Updated: ROADMAP.md, STATE.md
- Committed: chore: remove phase {target} ({original-name})
Current roadmap: {total-remaining} phases
Current position: Phase {current} of {new-total}
---
## What's Next
Would you like to:
- `/gsd:progress` — see updated roadmap status
- Continue with current phase
- Review roadmap
---
```
</step>
</process>
<anti_patterns>
- Don't remove completed phases (have SUMMARY.md files)
- Don't remove current or past phases
- Don't leave gaps in numbering - always renumber
- Don't add "removed phase" notes to STATE.md - git commit is the record
- Don't ask about each decimal phase - just renumber them
- Don't modify completed phase directories
</anti_patterns>
<edge_cases>
**Removing a decimal phase (e.g., 17.1):**
- Only affects other decimals in same series (17.2 → 17.1, 17.3 → 17.2)
- Integer phases unchanged
- Simpler operation
**No subsequent phases to renumber:**
- Removing the last phase (e.g., Phase 20 when that's the end)
- Just delete and update ROADMAP.md, no renumbering needed
**Phase directory doesn't exist:**
- Phase may be in ROADMAP.md but directory not created yet
- Skip directory deletion, proceed with ROADMAP.md updates
**Decimal phases under removed integer:**
- Removing Phase 17 when 17.1, 17.2 exist
- 17.1 → 16.1, 17.2 → 16.2
- They maintain their position in execution order (after current last integer)
</edge_cases>
<success_criteria>
Phase removal is complete when:
- [ ] Target phase validated as future/unstarted
- [ ] Phase directory deleted (if existed)
- [ ] All subsequent phase directories renumbered
- [ ] Files inside directories renamed ({old}-01-PLAN.md → {new}-01-PLAN.md)
- [ ] ROADMAP.md updated (section removed, all references renumbered)
- [ ] STATE.md updated (phase count, progress percentage)
- [ ] Dependency references updated in subsequent phases
- [ ] Changes committed with descriptive message
- [ ] No gaps in phase numbering
- [ ] User informed of changes
</success_criteria>

View File

@@ -20,9 +20,12 @@ Instantly restore full project context so "Where were we?" has an immediate, com
Check if this is an existing project:
```bash
ls .planning/STATE.md 2>/dev/null && echo "Project exists"
ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists"
ls .planning/PROJECT.md 2>/dev/null && echo "Project file exists"
STATE_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/STATE.md --raw)
ROADMAP_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/ROADMAP.md --raw)
PROJECT_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/PROJECT.md --raw)
[ "$STATE_EXISTS" = "true" ] && echo "Project exists"
[ "$ROADMAP_EXISTS" = "true" ] && echo "Roadmap exists"
[ "$PROJECT_EXISTS" = "true" ] && echo "Project file exists"
```
**If STATE.md exists:** Proceed to load_state
@@ -72,7 +75,8 @@ for plan in .planning/phases/*/*-PLAN.md; do
done 2>/dev/null
# Check for interrupted agents
if [ -f .planning/current-agent-id.txt ] && [ -s .planning/current-agent-id.txt ]; then
AGENT_FILE_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/current-agent-id.txt --raw)
if [ "$AGENT_FILE_EXISTS" = "true" ] && [ -s .planning/current-agent-id.txt ]; then
AGENT_ID=$(cat .planning/current-agent-id.txt | tr -d '\n')
echo "Interrupted agent: $AGENT_ID"
fi

View File

@@ -1,15 +1,15 @@
<purpose>
Verify phase goal achievement through goal-backward analysis. Check that the codebase actually delivers what the phase promised, not just that tasks were completed.
Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, not just that tasks completed.
This workflow is executed by a verification subagent spawned from execute-phase.md.
Executed by a verification subagent spawned from execute-phase.md.
</purpose>
<core_principle>
**Task completion ≠ Goal achievement**
A task "create chat component" can be marked complete when the component is a placeholder. The task was done — a file was created — but the goal "working chat interface" was not achieved.
A task "create chat component" can be marked complete when the component is a placeholder. The task was done — but the goal "working chat interface" was not achieved.
Goal-backward verification starts from the outcome and works backwards:
Goal-backward verification:
1. What must be TRUE for the goal to be achieved?
2. What must EXIST for those truths to hold?
3. What must be WIRED for those artifacts to function?
@@ -25,219 +25,61 @@ Then verify each level against the actual codebase.
<process>
<step name="load_context" priority="first">
**Gather all verification context:**
```bash
# Phase directory (match both zero-padded and unpadded)
PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}")
PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
PHASE_DIR=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "${PHASE_ARG}" --raw)
# Phase goal from ROADMAP
grep -A 5 "Phase ${PHASE_NUM}" .planning/ROADMAP.md
# Requirements mapped to this phase
grep -E "^| ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
# All SUMMARY files (claims to verify)
ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
# All PLAN files (for must_haves in frontmatter)
ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
ls "$PHASE_DIR"/*-SUMMARY.md "$PHASE_DIR"/*-PLAN.md 2>/dev/null
```
**Extract phase goal:** Parse ROADMAP.md for this phase's goal/description. This is the outcome to verify, not the tasks.
**Extract requirements:** If REQUIREMENTS.md exists, find requirements mapped to this phase. These become additional verification targets.
Extract **phase goal** from ROADMAP.md (the outcome to verify, not tasks) and **requirements** from REQUIREMENTS.md if it exists.
</step>
<step name="establish_must_haves">
**Determine what must be verified.**
**Option A: Must-haves in PLAN frontmatter**
Check if any PLAN.md has `must_haves` in frontmatter:
```bash
grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
```
If found, extract and use:
```yaml
must_haves:
truths:
- "User can see existing messages"
- "User can send a message"
artifacts:
- path: "src/components/Chat.tsx"
provides: "Message list rendering"
key_links:
- from: "Chat.tsx"
to: "api/chat"
via: "fetch in useEffect"
```
If found, extract truths, artifacts (with paths), and key_links (from/to/via).
**Option B: Derive from phase goal**
If no must_haves in frontmatter, derive using goal-backward process:
1. **State the goal:** Take phase goal from ROADMAP.md
2. **Derive truths:** Ask "What must be TRUE for this goal to be achieved?"
- List 3-7 observable behaviors from user perspective
- Each truth should be testable by a human using the app
3. **Derive artifacts:** For each truth, ask "What must EXIST?"
- Map truths to concrete files (components, routes, schemas)
- Be specific: `src/components/Chat.tsx`, not "chat component"
4. **Derive key links:** For each artifact, ask "What must be CONNECTED?"
- Identify critical wiring (component calls API, API queries DB)
- These are where stubs hide
5. **Document derived must-haves** before proceeding to verification.
<!-- Goal-backward derivation expertise is baked into the gsd-verifier agent -->
If no must_haves in frontmatter:
1. State the goal from ROADMAP.md
2. Derive **truths** (3-7 observable behaviors, each testable)
3. Derive **artifacts** (concrete file paths for each truth)
4. Derive **key links** (critical wiring where stubs hide)
5. Document derived must-haves before proceeding
</step>
<step name="verify_truths">
**For each observable truth, determine if codebase enables it.**
For each observable truth, determine if the codebase enables it.
A truth is achievable if the supporting artifacts exist, are substantive, and are wired correctly.
**Status:** ✓ VERIFIED (all supporting artifacts pass) | ✗ FAILED (artifact missing/stub/unwired) | ? UNCERTAIN (needs human)
**Verification status:**
- ✓ VERIFIED: All supporting artifacts pass all checks
- ✗ FAILED: One or more supporting artifacts missing, stub, or unwired
- ? UNCERTAIN: Can't verify programmatically (needs human)
For each truth: identify supporting artifacts → check artifact status → check wiring → determine truth status.
**For each truth:**
1. Identify supporting artifacts (which files make this truth possible?)
2. Check artifact status (see verify_artifacts step)
3. Check wiring status (see verify_wiring step)
4. Determine truth status based on supporting infrastructure
**Example:**
Truth: "User can see existing messages"
Supporting artifacts:
- Chat.tsx (renders messages)
- /api/chat GET (provides messages)
- Message model (defines schema)
If Chat.tsx is a stub → Truth FAILED
If /api/chat GET returns hardcoded [] → Truth FAILED
If Chat.tsx exists, is substantive, calls API, renders response → Truth VERIFIED
**Example:** Truth "User can see existing messages" depends on Chat.tsx (renders), /api/chat GET (provides), Message model (schema). If Chat.tsx is a stub or API returns hardcoded [] → FAILED. If all exist, are substantive, and connected → VERIFIED.
</step>
<step name="verify_artifacts">
**For each required artifact, verify three levels:**
For each required artifact, verify three levels:
### Level 1: Existence
**Level 1 — Existence:** File/directory exists. If MISSING → record and continue.
```bash
check_exists() {
local path="$1"
if [ -f "$path" ]; then
echo "EXISTS"
elif [ -d "$path" ]; then
echo "EXISTS (directory)"
else
echo "MISSING"
fi
}
```
**Level 2 — Substantive:** Real implementation, not a stub.
- Line minimums: Component 15+, API route 10+, Hook/util 10+, Schema 5+
- Stub detection: `TODO|FIXME|placeholder|not implemented|coming soon`, empty returns (`return null|return {}|return []`), placeholder content
- Export check: `export (default )?(function|const|class)` exists
- SUBSTANTIVE = adequate length + no stubs + has exports. STUB = too short OR stub patterns OR no exports. PARTIAL = mixed.
If MISSING → artifact fails, record and continue to next artifact.
### Level 2: Substantive
Check that the file has real implementation, not a stub.
**Line count check:**
```bash
check_length() {
local path="$1"
local min_lines="$2"
local lines=$(wc -l < "$path" 2>/dev/null || echo 0)
[ "$lines" -ge "$min_lines" ] && echo "SUBSTANTIVE ($lines lines)" || echo "THIN ($lines lines)"
}
```
Minimum lines by type:
- Component: 15+ lines
- API route: 10+ lines
- Hook/util: 10+ lines
- Schema model: 5+ lines
**Stub pattern check:**
```bash
check_stubs() {
local path="$1"
# Universal stub patterns
local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented|coming soon" "$path" 2>/dev/null || echo 0)
# Empty returns
local empty=$(grep -c -E "return null|return undefined|return \{\}|return \[\]" "$path" 2>/dev/null || echo 0)
# Placeholder content
local placeholder=$(grep -c -E "will be here|placeholder|lorem ipsum" "$path" 2>/dev/null || echo 0)
local total=$((stubs + empty + placeholder))
[ "$total" -gt 0 ] && echo "STUB_PATTERNS ($total found)" || echo "NO_STUBS"
}
```
**Export check (for components/hooks):**
```bash
check_exports() {
local path="$1"
grep -E "^export (default )?(function|const|class)" "$path" && echo "HAS_EXPORTS" || echo "NO_EXPORTS"
}
```
**Combine level 2 results:**
- SUBSTANTIVE: Adequate length + no stubs + has exports
- STUB: Too short OR has stub patterns OR no exports
- PARTIAL: Mixed signals (length OK but has some stubs)
### Level 3: Wired
Check that the artifact is connected to the system.
**Import check (is it used?):**
```bash
check_imported() {
local artifact_name="$1"
local search_path="${2:-src/}"
# Find imports of this artifact
local imports=$(grep -r "import.*$artifact_name" "$search_path" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l)
[ "$imports" -gt 0 ] && echo "IMPORTED ($imports times)" || echo "NOT_IMPORTED"
}
```
**Usage check (is it called?):**
```bash
check_used() {
local artifact_name="$1"
local search_path="${2:-src/}"
# Find usages (function calls, component renders, etc.)
local uses=$(grep -r "$artifact_name" "$search_path" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "import" | wc -l)
[ "$uses" -gt 0 ] && echo "USED ($uses times)" || echo "NOT_USED"
}
```
**Combine level 3 results:**
- WIRED: Imported AND used
- ORPHANED: Exists but not imported/used
- PARTIAL: Imported but not used (or vice versa)
### Final artifact status
**Level 3 — Wired:** Connected to the system.
- Import: `grep -r "import.*$artifact_name" src/ --include="*.ts" --include="*.tsx"` → IMPORTED
- Usage: same grep excluding import lines → USED
- WIRED = imported AND used. ORPHANED = exists but not imported/used. PARTIAL = imported but unused.
| Exists | Substantive | Wired | Status |
|--------|-------------|-------|--------|
@@ -245,370 +87,88 @@ check_used() {
| ✓ | ✓ | ✗ | ⚠️ ORPHANED |
| ✓ | ✗ | - | ✗ STUB |
| ✗ | - | - | ✗ MISSING |
Record status and evidence for each artifact.
</step>
<step name="verify_wiring">
**Verify key links between artifacts.**
Key links are critical connections — if broken, goal fails even with all artifacts present.
Key links are critical connections. If broken, the goal fails even with all artifacts present.
| Pattern | Check | Status |
|---------|-------|--------|
| Component → API | fetch/axios call to API path, response used (await/.then/setState) | WIRED / PARTIAL (call but unused response) / NOT_WIRED |
| API → Database | Prisma/DB query on model, result returned via res.json() | WIRED / PARTIAL (query but not returned) / NOT_WIRED |
| Form → Handler | onSubmit with real implementation (fetch/axios/mutate/dispatch), not console.log/empty | WIRED / STUB (log-only/empty) / NOT_WIRED |
| State → Render | useState variable appears in JSX (`{stateVar}` or `{stateVar.property}`) | WIRED / NOT_WIRED |
### Pattern: Component → API
Check if component actually calls the API:
```bash
verify_component_api_link() {
local component="$1"
local api_path="$2"
# Check for fetch/axios call to the API
local has_call=$(grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component" 2>/dev/null)
if [ -n "$has_call" ]; then
# Check if response is used
local uses_response=$(grep -A 5 "fetch\|axios" "$component" | grep -E "await|\.then|setData|setState" 2>/dev/null)
if [ -n "$uses_response" ]; then
echo "WIRED: $component → $api_path (call + response handling)"
else
echo "PARTIAL: $component → $api_path (call exists but response not used)"
fi
else
echo "NOT_WIRED: $component → $api_path (no call found)"
fi
}
```
### Pattern: API → Database
Check if API route queries database:
```bash
verify_api_db_link() {
local route="$1"
local model="$2"
# Check for Prisma/DB call
local has_query=$(grep -E "prisma\.$model|db\.$model|$model\.(find|create|update|delete)" "$route" 2>/dev/null)
if [ -n "$has_query" ]; then
# Check if result is returned
local returns_result=$(grep -E "return.*json.*\w+|res\.json\(\w+" "$route" 2>/dev/null)
if [ -n "$returns_result" ]; then
echo "WIRED: $route → database ($model)"
else
echo "PARTIAL: $route → database (query exists but result not returned)"
fi
else
echo "NOT_WIRED: $route → database (no query for $model)"
fi
}
```
### Pattern: Form → Handler
Check if form submission does something:
```bash
verify_form_handler_link() {
local component="$1"
# Find onSubmit handler
local has_handler=$(grep -E "onSubmit=\{|handleSubmit" "$component" 2>/dev/null)
if [ -n "$has_handler" ]; then
# Check if handler has real implementation
local handler_content=$(grep -A 10 "onSubmit.*=" "$component" | grep -E "fetch|axios|mutate|dispatch" 2>/dev/null)
if [ -n "$handler_content" ]; then
echo "WIRED: form → handler (has API call)"
else
# Check for stub patterns
local is_stub=$(grep -A 5 "onSubmit" "$component" | grep -E "console\.log|preventDefault\(\)$|\{\}" 2>/dev/null)
if [ -n "$is_stub" ]; then
echo "STUB: form → handler (only logs or empty)"
else
echo "PARTIAL: form → handler (exists but unclear implementation)"
fi
fi
else
echo "NOT_WIRED: form → handler (no onSubmit found)"
fi
}
```
### Pattern: State → Render
Check if state is actually rendered:
```bash
verify_state_render_link() {
local component="$1"
local state_var="$2"
# Check if state variable exists
local has_state=$(grep -E "useState.*$state_var|\[$state_var," "$component" 2>/dev/null)
if [ -n "$has_state" ]; then
# Check if state is used in JSX
local renders_state=$(grep -E "\{.*$state_var.*\}|\{$state_var\." "$component" 2>/dev/null)
if [ -n "$renders_state" ]; then
echo "WIRED: state → render ($state_var displayed)"
else
echo "NOT_WIRED: state → render ($state_var exists but not displayed)"
fi
else
echo "N/A: state → render (no state var $state_var)"
fi
}
```
### Aggregate key link results
For each key link in must_haves:
- Run appropriate verification function
- Record status and evidence
- WIRED / PARTIAL / STUB / NOT_WIRED
Record status and evidence for each key link.
</step>
<step name="verify_requirements">
**Check requirements coverage if REQUIREMENTS.md exists.**
If REQUIREMENTS.md exists:
```bash
# Find requirements mapped to this phase
grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
```
For each requirement:
1. Parse requirement description
2. Identify which truths/artifacts support it
3. Determine status based on supporting infrastructure
**Requirement status:**
- ✓ SATISFIED: All supporting truths verified
- ✗ BLOCKED: One or more supporting truths failed
- ? NEEDS HUMAN: Can't verify requirement programmatically
For each requirement: parse description → identify supporting truths/artifacts → status: ✓ SATISFIED / ✗ BLOCKED / ? NEEDS HUMAN.
</step>
<step name="scan_antipatterns">
**Scan for anti-patterns across phase files.**
Extract files modified in this phase from SUMMARY.md, scan each:
Identify files modified in this phase:
```bash
# Extract files from SUMMARY.md
grep -E "^\- \`" "$PHASE_DIR"/*-SUMMARY.md | sed 's/.*`\([^`]*\)`.*/\1/' | sort -u
```
| Pattern | Search | Severity |
|---------|--------|----------|
| TODO/FIXME/XXX/HACK | `grep -n -E "TODO\|FIXME\|XXX\|HACK"` | ⚠️ Warning |
| Placeholder content | `grep -n -iE "placeholder\|coming soon\|will be here"` | 🛑 Blocker |
| Empty returns | `grep -n -E "return null\|return \{\}\|return \[\]\|=> \{\}"` | ⚠️ Warning |
| Log-only functions | Functions containing only console.log | ⚠️ Warning |
Run anti-pattern detection:
```bash
scan_antipatterns() {
local files="$@"
echo "## Anti-Patterns Found"
echo ""
for file in $files; do
[ -f "$file" ] || continue
# TODO/FIXME comments
grep -n -E "TODO|FIXME|XXX|HACK" "$file" 2>/dev/null | while read line; do
echo "| $file | $(echo $line | cut -d: -f1) | TODO/FIXME | ⚠️ Warning |"
done
# Placeholder content
grep -n -E "placeholder|coming soon|will be here" "$file" -i 2>/dev/null | while read line; do
echo "| $file | $(echo $line | cut -d: -f1) | Placeholder | 🛑 Blocker |"
done
# Empty implementations
grep -n -E "return null|return \{\}|return \[\]|=> \{\}" "$file" 2>/dev/null | while read line; do
echo "| $file | $(echo $line | cut -d: -f1) | Empty return | ⚠️ Warning |"
done
# Console.log only implementations
grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|function|=>)" | while read line; do
echo "| $file | - | Log-only function | ⚠️ Warning |"
done
done
}
```
Categorize findings:
- 🛑 Blocker: Prevents goal achievement (placeholder renders, empty handlers)
- ⚠️ Warning: Indicates incomplete (TODO comments, console.log)
- ℹ️ Info: Notable but not problematic
Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️ Info (notable).
</step>
<step name="identify_human_verification">
**Flag items that need human verification.**
**Always needs human:** Visual appearance, user flow completion, real-time behavior (WebSocket/SSE), external service integration, performance feel, error message clarity.
Some things can't be verified programmatically:
**Needs human if uncertain:** Complex wiring grep can't trace, dynamic state-dependent behavior, edge cases.
**Always needs human:**
- Visual appearance (does it look right?)
- User flow completion (can you do the full task?)
- Real-time behavior (WebSocket, SSE updates)
- External service integration (payments, email)
- Performance feel (does it feel fast?)
- Error message clarity
**Needs human if uncertain:**
- Complex wiring that grep can't trace
- Dynamic behavior depending on state
- Edge cases and error states
**Format for human verification:**
```markdown
## Human Verification Required
### 1. {Test Name}
**Test:** {What to do}
**Expected:** {What should happen}
**Why human:** {Why can't verify programmatically}
```
Format each as: Test Name → What to do → Expected result → Why can't verify programmatically.
</step>
<step name="determine_status">
**Calculate overall verification status.**
**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
**Status: passed**
- All truths VERIFIED
- All artifacts pass level 1-3
- All key links WIRED
- No blocker anti-patterns
- (Human verification items are OK — will be prompted)
**gaps_found:** Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker found.
**Status: gaps_found**
- One or more truths FAILED
- OR one or more artifacts MISSING/STUB
- OR one or more key links NOT_WIRED
- OR blocker anti-patterns found
**human_needed:** All automated checks pass but human verification items remain.
**Status: human_needed**
- All automated checks pass
- BUT items flagged for human verification
- Can't determine goal achievement without human
**Calculate score:**
```
score = (verified_truths / total_truths)
```
**Score:** `verified_truths / total_truths`
</step>
<step name="generate_fix_plans">
**If gaps_found, recommend fix plans.**
If gaps_found:
Group related gaps into fix plans:
1. **Cluster related gaps:** API stub + component unwired → "Wire frontend to backend". Multiple missing → "Complete core implementation". Wiring only → "Connect existing components".
1. **Identify gap clusters:**
- API stub + component not wired → "Wire frontend to backend"
- Multiple artifacts missing → "Complete core implementation"
- Wiring issues only → "Connect existing components"
2. **Generate plan per cluster:** Objective, 2-3 tasks (files/action/verify each), re-verify step. Keep focused: single concern per plan.
2. **Generate plan recommendations:**
```markdown
### {phase}-{next}-PLAN.md: {Fix Name}
**Objective:** {What this fixes}
**Tasks:**
1. {Task to fix gap 1}
- Files: {files to modify}
- Action: {specific fix}
- Verify: {how to confirm fix}
2. {Task to fix gap 2}
- Files: {files to modify}
- Action: {specific fix}
- Verify: {how to confirm fix}
3. Re-verify phase goal
- Run verification again
- Confirm all must-haves pass
**Estimated scope:** {Small / Medium}
```
3. **Keep plans focused:**
- 2-3 tasks per plan
- Single concern per plan
- Include verification task
4. **Order by dependency:**
- Fix missing artifacts before wiring
- Fix stubs before integration
- Verify after all fixes
3. **Order by dependency:** Fix missing → fix stubs → fix wiring → verify.
</step>
<step name="create_report">
**Generate VERIFICATION.md using template.**
```bash
REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
```
Fill template sections:
1. **Frontmatter:** phase, verified timestamp, status, score
2. **Goal Achievement:** Truth verification table
3. **Required Artifacts:** Artifact verification table
4. **Key Link Verification:** Wiring verification table
5. **Requirements Coverage:** If REQUIREMENTS.md exists
6. **Anti-Patterns Found:** Scan results table
7. **Human Verification Required:** Items needing human
8. **Gaps Summary:** Critical and non-critical gaps
9. **Recommended Fix Plans:** If gaps_found
10. **Verification Metadata:** Approach, timing, counts
Fill template sections: frontmatter (phase/timestamp/status/score), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
See ~/.claude/get-shit-done/templates/verification-report.md for complete template.
</step>
<step name="return_to_orchestrator">
**Return results to execute-phase orchestrator.**
Return status (`passed` | `gaps_found` | `human_needed`), score (N/M must-haves), report path.
**Return format:**
If gaps_found: list gaps + recommended fix plan names.
If human_needed: list items requiring human testing.
```markdown
## Verification Complete
**Status:** {passed | gaps_found | human_needed}
**Score:** {N}/{M} must-haves verified
**Report:** .planning/phases/{phase_dir}/{phase}-VERIFICATION.md
{If passed:}
All must-haves verified. Phase goal achieved. Ready to proceed.
{If gaps_found:}
### Gaps Found
{N} critical gaps blocking goal achievement:
1. {Gap 1 summary}
2. {Gap 2 summary}
### Recommended Fixes
{N} fix plans recommended:
1. {phase}-{next}-PLAN.md: {name}
2. {phase}-{next+1}-PLAN.md: {name}
{If human_needed:}
### Human Verification Required
{N} items need human testing:
1. {Item 1}
2. {Item 2}
Automated checks passed. Awaiting human verification.
```
The orchestrator will:
- If `passed`: Continue to update_roadmap
- If `gaps_found`: Create and execute fix plans, then re-verify
- If `human_needed`: Present items to user, collect responses
Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
</step>
</process>

View File

@@ -21,22 +21,10 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
<process>
<step name="resolve_model_profile" priority="first">
Read model profile for agent spawning:
```bash
MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
PLANNER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-planner --raw)
CHECKER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-plan-checker --raw)
```
Default to "balanced" if not set.
**Model lookup table:**
| Agent | quality | balanced | budget |
|-------|---------|----------|--------|
| gsd-planner | opus | opus | sonnet |
| gsd-plan-checker | sonnet | sonnet | haiku |
Store resolved models for use in Task calls below.
</step>
<step name="check_active_session">
@@ -92,9 +80,7 @@ Continue to `create_uat_file`.
Parse $ARGUMENTS as phase number (e.g., "4") or plan number (e.g., "04-02").
```bash
# Find phase directory (match both zero-padded and unpadded)
PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}")
PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
PHASE_DIR=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "${PHASE_ARG}" --raw)
# Find SUMMARY files
ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
@@ -304,21 +290,9 @@ Clear Current Test section:
[testing complete]
```
**Check planning config:**
```bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
```
**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
**If `COMMIT_PLANNING_DOCS=true` (default):**
Commit the UAT file:
```bash
git add ".planning/phases/XX-name/{phase}-UAT.md"
git commit -m "test({phase}): complete UAT - {passed} passed, {issues} issues"
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "test({phase}): complete UAT - {passed} passed, {issues} issues" --files ".planning/phases/XX-name/{phase}-UAT.md"
```
Present summary: