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:
234
get-shit-done/workflows/audit-milestone.md
Normal file
234
get-shit-done/workflows/audit-milestone.md
Normal 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>
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
470
get-shit-done/workflows/help.md
Normal file
470
get-shit-done/workflows/help.md
Normal 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>
|
||||
213
get-shit-done/workflows/insert-phase.md
Normal file
213
get-shit-done/workflows/insert-phase.md
Normal 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>
|
||||
@@ -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.
|
||||
|
||||
363
get-shit-done/workflows/new-milestone.md
Normal file
363
get-shit-done/workflows/new-milestone.md
Normal 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>
|
||||
937
get-shit-done/workflows/new-project.md
Normal file
937
get-shit-done/workflows/new-project.md
Normal 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>
|
||||
254
get-shit-done/workflows/plan-milestone-gaps.md
Normal file
254
get-shit-done/workflows/plan-milestone-gaps.md
Normal 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>
|
||||
400
get-shit-done/workflows/plan-phase.md
Normal file
400
get-shit-done/workflows/plan-phase.md
Normal 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>
|
||||
354
get-shit-done/workflows/progress.md
Normal file
354
get-shit-done/workflows/progress.md
Normal 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>
|
||||
258
get-shit-done/workflows/quick.md
Normal file
258
get-shit-done/workflows/quick.md
Normal 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>
|
||||
323
get-shit-done/workflows/remove-phase.md
Normal file
323
get-shit-done/workflows/remove-phase.md
Normal 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>
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user