[ { "path": ".agent/workflows/add-phase.md", "content": "---\ndescription: Add a new phase to the end of the roadmap\nargument-hint: \"\"\n---\n\n# /add-phase Workflow\n\n\nAdd a new phase to the end of the current roadmap.\n\n\n\n\n## 1. Validate Roadmap Exists\n\n```powershell\nif (-not (Test-Path \".gsd/ROADMAP.md\")) {\n Write-Error \"ROADMAP.md required. Run /new-milestone first.\"\n}\n```\n\n---\n\n## 2. Determine Next Phase Number\n\n```powershell\n# Count existing phases\n$phases = Select-String -Path \".gsd/ROADMAP.md\" -Pattern \"### Phase \\d+\"\n$nextPhase = $phases.Count + 1\n```\n\n---\n\n## 3. Gather Phase Information\n\nAsk for:\n- **Name** — Phase title\n- **Objective** — What this phase achieves\n- **Depends on** — Previous phases (usually N-1)\n\n---\n\n## 4. Add to ROADMAP.md\n\nAppend:\n```markdown\n---\n\n### Phase {N}: {name}\n**Status**: ⬜ Not Started\n**Objective**: {objective}\n**Depends on**: Phase {N-1}\n\n**Tasks**:\n- [ ] TBD (run /plan {N} to create)\n\n**Verification**:\n- TBD\n```\n\n---\n\n## 5. Update STATE.md\n\nNote phase added.\n\n---\n\n## 6. Commit\n\n```powershell\ngit add .gsd/ROADMAP.md .gsd/STATE.md\ngit commit -m \"docs: add phase {N} - {name}\"\n```\n\n---\n\n## 7. Offer Next Steps\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE ADDED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nPhase {N}: {name}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/plan {N} — Create execution plans for this phase\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/add-todo.md", "content": "---\ndescription: Capture a todo item for later\nargument-hint: \" [--priority high|medium|low]\"\n---\n\n# /add-todo Workflow\n\n\nQuickly capture an idea, task, or issue without interrupting current work flow.\n\n\n\n**Item:** $ARGUMENTS (the todo description)\n\n**Flags:**\n- `--priority high|medium|low` — Set priority (default: medium)\n\n**Output:**\n- `.gsd/TODO.md` — Accumulated todo items\n\n\n\n\n## 1. Parse Arguments\n\nExtract:\n- Todo description\n- Priority (default: medium)\n\n---\n\n## 2. Ensure TODO.md Exists\n\n```powershell\nif (-not (Test-Path \".gsd/TODO.md\")) {\n # Create with header\n}\n```\n\n---\n\n## 3. Add Todo Item\n\nAppend to `.gsd/TODO.md`:\n\n```markdown\n- [ ] {description} `{priority}` — {date}\n```\n\n---\n\n## 4. Confirm\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► TODO ADDED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{description}\nPriority: {priority}\n\n───────────────────────────────────────────────────────\n\n/check-todos — see all pending items\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/audit-milestone.md", "content": "---\ndescription: Audit a milestone for quality and completeness\nargument-hint: \"[milestone-name]\"\n---\n\n# /audit-milestone Workflow\n\n\nReview a completed (or in-progress) milestone for quality, completeness, and lessons learned.\n\n\n\n\n## 1. Load Milestone Context\n\nIf milestone name provided, load from archive:\n```powershell\nGet-Content \".gsd/milestones/{name}-SUMMARY.md\"\n```\n\nIf no name, audit current milestone from ROADMAP.md.\n\n---\n\n## 2. Check Must-Haves Verification\n\nFor each must-have in the milestone:\n- Was it verified with empirical evidence?\n- Is the evidence still valid?\n- Any regressions since completion?\n\n---\n\n## 3. Review Technical Debt\n\nCheck TODO.md and DECISIONS.md for:\n- Deferred items during this milestone\n- Technical debt acknowledged\n- Items that should be addressed\n\n---\n\n## 4. Analyze Phase Quality\n\nFor each phase:\n- Review VERIFICATION.md\n- Check for gap closures (were there many?)\n- Note recurring issues\n\n---\n\n## 5. Generate Audit Report\n\n```markdown\n# Milestone Audit: {name}\n\n**Audited:** {date}\n\n## Summary\n| Metric | Value |\n|--------|-------|\n| Phases | {N} |\n| Gap closures | {M} |\n| Technical debt items | {K} |\n\n## Must-Haves Status\n| Requirement | Verified | Evidence |\n|-------------|----------|----------|\n| {req 1} | ✅ | {link} |\n| {req 2} | ✅ | {link} |\n\n## Concerns\n- {concern 1}\n- {concern 2}\n\n## Recommendations\n1. {recommendation 1}\n2. {recommendation 2}\n\n## Technical Debt to Address\n- [ ] {item 1}\n- [ ] {item 2}\n```\n\n---\n\n## 6. Offer Actions\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► AUDIT COMPLETE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nMilestone: {name}\nHealth: {GOOD | CONCERNS | NEEDS ATTENTION}\n\n───────────────────────────────────────────────────────\n\n▶ ACTIONS\n\n/plan-milestone-gaps — Create plans to address gaps\n/add-todo — Capture debt items for later\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/check-todos.md", "content": "---\ndescription: List all pending todo items\nargument-hint: \"[--all] [--priority high|medium|low]\"\n---\n\n# /check-todos Workflow\n\n\nDisplay pending todo items, optionally filtered by priority or status.\n\n\n\n**Flags:**\n- `--all` — Show completed items too\n- `--priority high|medium|low` — Filter by priority\n\n**Input:**\n- `.gsd/TODO.md` — Todo items\n\n\n\n\n## 1. Load TODO.md\n\n```powershell\nif (-not (Test-Path \".gsd/TODO.md\")) {\n Write-Output \"No todos found. Use /add-todo to create one.\"\n exit\n}\n\nGet-Content \".gsd/TODO.md\"\n```\n\n---\n\n## 2. Parse and Filter\n\nCount items by status:\n- `- [ ]` = pending\n- `- [x]` = complete\n\nFilter by priority if flag provided.\n\n---\n\n## 3. Display\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► TODOS\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nPENDING ({N} items)\n───────────────────\n🔴 {high priority item}\n🟡 {medium priority item}\n🟢 {low priority item}\n\n{If --all flag:}\nCOMPLETED ({M} items)\n─────────────────────\n✅ {completed item}\n\n───────────────────────────────────────────────────────\n\n/add-todo — add new item\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n| Priority | Indicator |\n|----------|-----------|\n| high | 🔴 |\n| medium | 🟡 |\n| low | 🟢 |\n| done | ✅ |\n\n" }, { "path": ".agent/workflows/complete-milestone.md", "content": "---\ndescription: Mark current milestone as complete and archive\n---\n\n# /complete-milestone Workflow\n\n\nFinalize the current milestone, archive documentation, and prepare for next milestone.\n\n\n\n\n## 1. Verify All Phases Complete\n\n**PowerShell:**\n```powershell\n# Check ROADMAP.md for incomplete phases\nSelect-String -Path \".gsd/ROADMAP.md\" -Pattern \"Status.*Not Started|Status.*In Progress\"\n```\n\n**Bash:**\n```bash\n# Check ROADMAP.md for incomplete phases\ngrep -E \"Status.*Not Started|Status.*In Progress\" \".gsd/ROADMAP.md\"\n```\n\n**If incomplete phases found:**\n```\n⚠️ Cannot complete milestone — {N} phases incomplete\n\nRun /progress to see status.\n```\n\n---\n\n## 2. Run Final Verification\n\nVerify all must-haves from ROADMAP.md:\n- Run verification commands\n- Capture evidence\n- Create VERIFICATION.md if not exists\n\n---\n\n## 3. Generate Milestone Summary\n\nCreate `.gsd/milestones/{name}-SUMMARY.md`:\n\n```markdown\n# Milestone: {name}\n\n## Completed: {date}\n\n## Deliverables\n- ✅ {must-have 1}\n- ✅ {must-have 2}\n\n## Phases Completed\n1. Phase 1: {name} — {date}\n2. Phase 2: {name} — {date}\n...\n\n## Metrics\n- Total commits: {N}\n- Files changed: {M}\n- Duration: {days}\n\n## Lessons Learned\n{Auto-extract from DECISIONS.md and JOURNAL.md}\n```\n\n---\n\n## 4. Archive Current State\n\n**PowerShell:**\n```powershell\n# Create milestone archive\nNew-Item -ItemType Directory -Force \".gsd/milestones/{name}\"\n\n# Move phase-specific files\nMove-Item \".gsd/phases/*\" \".gsd/milestones/{name}/\"\n\n# Archive decisions and journal (prevent monolithic growth across milestones)\nif (Test-Path \".gsd/DECISIONS.md\") {\n Copy-Item \".gsd/DECISIONS.md\" \".gsd/milestones/{name}/DECISIONS.md\"\n}\nif (Test-Path \".gsd/JOURNAL.md\") {\n Copy-Item \".gsd/JOURNAL.md\" \".gsd/milestones/{name}/JOURNAL.md\"\n}\n```\n\n**Bash:**\n```bash\n# Create milestone archive\nmkdir -p \".gsd/milestones/{name}\"\n\n# Move phase-specific files\nmv .gsd/phases/* \".gsd/milestones/{name}/\"\n\n# Archive decisions and journal (prevent monolithic growth across milestones)\n[ -f \".gsd/DECISIONS.md\" ] && cp \".gsd/DECISIONS.md\" \".gsd/milestones/{name}/DECISIONS.md\"\n[ -f \".gsd/JOURNAL.md\" ] && cp \".gsd/JOURNAL.md\" \".gsd/milestones/{name}/JOURNAL.md\"\n```\n\n---\n\n## 5. Reset for Next Milestone\n\nClear ROADMAP.md phases section (keep header).\nUpdate STATE.md to show milestone complete.\n\n**Reset DECISIONS.md** — replace contents with a fresh header referencing the archive:\n\n```markdown\n# Decisions\n\n> Previous milestone decisions archived in `.gsd/milestones/{name}/DECISIONS.md`\n\n---\n```\n\n**Reset JOURNAL.md** — replace contents with a fresh header:\n\n```markdown\n# Journal\n\n> Previous milestone journal archived in `.gsd/milestones/{name}/JOURNAL.md`\n\n---\n```\n\n---\n\n## 5c. Refresh Architecture\n\nUpdate `.gsd/ARCHITECTURE.md` to reflect the current state of the codebase after the milestone:\n\n1. **Scan the project** — identify new components, removed modules, changed dependencies\n2. **Update the architecture diagram** — reflect structural changes from this milestone\n3. **Update STACK.md** — refresh technology and dependency information\n4. **Keep it lean** — remove details about components that no longer exist; summarize, don't accumulate\n\n> This prevents ARCHITECTURE.md from becoming stale or bloated across milestones (addresses the issue where architecture only updates via `/map`).\n\n---\n\n## 5d. Update Requirements\n\nIf `.gsd/REQUIREMENTS.md` exists, mark completed requirements:\n\n1. Read each requirement's status\n2. Cross-reference with milestone deliverables and verification results\n3. Mark satisfied requirements as `Complete`\n4. Mark deferred items as `Deferred` with reason\n5. Archive the requirements snapshot into `.gsd/milestones/{name}/REQUIREMENTS.md`\n\n---\n\n## 6. Commit and Tag\n\n```bash\ngit add -A\ngit commit -m \"docs: complete milestone {name}\"\ngit tag -a \"{name}\" -m \"Milestone {name} complete\"\n```\n\n---\n\n## 7. Celebrate\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► MILESTONE COMPLETE 🎉\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{name}\n\nPhases: {N} completed\nTag: {name}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/new-milestone — Start next milestone\n/audit-milestone {name} — Review this milestone\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/debug.md", "content": "---\ndescription: Systematic debugging with persistent state\nargument-hint: \"[description of issue]\"\n---\n\n# /debug Workflow\n\n\nYou are a GSD debugger orchestrator. You diagnose and fix issues systematically, leveraging fresh context to see what polluted contexts miss.\n\n\n\nSystematically diagnose an issue using hypothesis-driven debugging, with persistent state to prevent circular attempts.\n\n\n\n**Issue:** $ARGUMENTS (description of the problem to debug)\n\n**Skill reference:** `.agents/skills/debugger/SKILL.md`\n\n\n\n\n## 1. Initialize Debug Session\n\nCheck for existing debug state:\n**PowerShell:**\n```powershell\nTest-Path \".gsd/DEBUG.md\"\n```\n\n**Bash:**\n```bash\ntest -f \".gsd/DEBUG.md\"\n```\n\nIf exists, load previous attempts. If not, create new session.\n\nDisplay banner:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► DEBUG SESSION\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nIssue: {description}\n```\n\n---\n\n## 2. Document Symptom\n\nCreate/update `.gsd/DEBUG.md`:\n\n```markdown\n# Debug Session: {Issue ID}\n\n## Symptom\n{Exact description of the problem}\n\n**When:** {When does it occur?}\n**Expected:** {What should happen?}\n**Actual:** {What actually happens?}\n```\n\n---\n\n## 3. Gather Evidence\n\nCollect data BEFORE forming hypotheses:\n\n**PowerShell:**\n```powershell\n# Get error details\n{relevant commands to capture error info}\n\n# Check logs\nGet-Content logs/error.log -Tail 50\n\n# Check environment\n{relevant environment checks}\n```\n\n**Bash:**\n```bash\n# Get error details\n{relevant commands to capture error info}\n\n# Check logs\ntail -50 logs/error.log\n\n# Check environment\n{relevant environment checks}\n```\n\nDocument evidence in DEBUG.md.\n\n---\n\n## 4. Form Hypotheses\n\nBased on evidence, list possible causes:\n\n```markdown\n## Hypotheses\n\n| # | Hypothesis | Likelihood | Status |\n|---|------------|------------|--------|\n| 1 | {cause 1} | 80% | UNTESTED |\n| 2 | {cause 2} | 15% | UNTESTED |\n| 3 | {cause 3} | 5% | UNTESTED |\n```\n\n---\n\n## 5. Test Hypotheses\n\nTest highest likelihood first:\n\n```markdown\n## Attempts\n\n### Attempt 1\n**Testing:** H1 — {hypothesis}\n**Action:** {what you did to test}\n**Result:** {outcome}\n**Conclusion:** {CONFIRMED | ELIMINATED | INCONCLUSIVE}\n```\n\n---\n\n## 6. Apply Fix (If Root Cause Found)\n\nWhen root cause confirmed:\n\n1. Implement fix\n2. Run original failing scenario\n3. Verify PASSES\n4. Check for regressions\n\nUpdate DEBUG.md:\n```markdown\n## Resolution\n\n**Root Cause:** {what was actually wrong}\n**Fix:** {what was changed}\n**Verified:** {how fix was verified}\n**Regression Check:** {what else was tested}\n```\n\n---\n\n## 7. Handle 3-Strike Rule\n\nIf 3 attempts fail on SAME approach:\n\n```\n⚠️ 3 FAILURES ON SAME APPROACH\n\nAction: STOP and reassess\n\nOptions:\n1. Try fundamentally DIFFERENT approach\n2. /pause for fresh session context\n3. Ask user for additional information\n```\n\nUpdate DEBUG.md and recommend next steps.\n\n---\n\n## 8. Commit Resolution\n\nIf fixed:\n```bash\ngit add -A\ngit commit -m \"fix: {brief description of fix}\"\n```\n\nUpdate STATE.md with resolution.\n\n\n\n\n\n**If Resolved:**\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► BUG FIXED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nRoot cause: {what was wrong}\nFix: {what was done}\n\nCommitted: {hash}\n\n───────────────────────────────────────────────────────\n```\n\n**If Stuck After 3 Attempts:**\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► DEBUG PAUSED ⏸\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n3 attempts exhausted on current approach.\nState saved to .gsd/DEBUG.md\n\n───────────────────────────────────────────────────────\n\nOptions:\n• /debug {issue} — try different approach\n• /pause — save state for fresh session\n• Provide more context about the issue\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/pause` | Use after 3 failed attempts |\n| `/resume` | Start fresh with documented state |\n| `/verify` | Re-verify after fixing issues |\n\n### Skills\n| Skill | Purpose |\n|-------|---------|\n| `debugger` | Detailed debugging methodology |\n| `context-health-monitor` | 3-strike rule |\n\n" }, { "path": ".agent/workflows/discuss-phase.md", "content": "---\ndescription: Discuss a phase before planning (clarify scope and approach)\nargument-hint: \"\"\n---\n\n# /discuss-phase Workflow\n\n\nInteractive discussion about a phase to clarify scope, approach, and concerns before creating plans.\n\n\n\nRun BEFORE `/plan` when:\n- Phase scope is unclear\n- Multiple implementation approaches exist\n- Trade-offs need user input\n- Dependencies are complex\n\n\n\n\n## 1. Load Phase Context\n\nRead from ROADMAP.md:\n- Phase objective\n- Dependencies\n- Current status\n\n---\n\n## 2. Analyze Requirements\n\nFrom phase objective, extract:\n- What needs to be built\n- What constraints exist\n- What decisions need to be made\n\n---\n\n## 3. Present Discussion Points\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► DISCUSS PHASE {N}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nPhase: {name}\nObjective: {objective}\n\n───────────────────────────────────────────────────────\n\nTOPICS TO DISCUSS\n\n1. SCOPE CLARIFICATION\n - {question about scope}\n - {question about boundaries}\n\n2. IMPLEMENTATION APPROACH\n Option A: {approach}\n Option B: {approach}\n Which do you prefer and why?\n\n3. DEPENDENCIES\n - Requires: {what from previous phases}\n - Missing: {any gaps in earlier work}\n\n4. CONCERNS\n - {potential issue}\n - {risk to flag}\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 4. Gather User Input\n\nListen for:\n- Scope decisions\n- Approach preferences\n- Constraints not in spec\n- Priority clarifications\n\n---\n\n## 5. Document Decisions\n\nUpdate `.gsd/DECISIONS.md`:\n\n```markdown\n## Phase {N} Decisions\n\n**Date:** {date}\n\n### Scope\n- {decision about scope}\n\n### Approach\n- Chose: {approach}\n- Reason: {rationale}\n\n### Constraints\n- {constraint identified}\n```\n\n---\n\n## 6. Offer Next Steps\n\n```\n───────────────────────────────────────────────────────\n\n✓ Discussion documented in DECISIONS.md\n\n▶ NEXT\n\n/plan {N} — Create execution plans with this context\n/research-phase {N} — Deep dive on technical options\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/execute.md", "content": "---\ndescription: The Engineer — Execute a specific phase with focused context\nargument-hint: \" [--gaps-only]\"\n---\n\n# /execute Workflow\n\n\nYou are a GSD executor orchestrator. You manage wave-based parallel execution of phase plans.\n\n**Core responsibilities:**\n- Validate phase exists and has plans\n- Discover and group plans by execution wave\n- Spawn focused execution for each plan\n- Verify phase goal after all plans complete\n- Update roadmap and state on completion\n\n\n\nExecute all plans in a phase using wave-based parallel execution.\n\nOrchestrator stays lean: discover plans, analyze dependencies, group into waves, execute sequentially within waves, verify against phase goal.\n\n**Context budget:** ~15% orchestrator, fresh context per plan execution.\n\n\n\n**Phase:** $ARGUMENTS (required - phase number to execute)\n\n**Flags:**\n- `--gaps-only` — Execute only gap closure plans (created by `/verify` when issues found)\n\n**Required files:**\n- `.gsd/ROADMAP.md` — Phase definitions\n- `.gsd/STATE.md` — Current position\n- `.gsd/phases/{phase}/` — Phase directory with PLAN.md files\n\n\n\n\n## 1. Validate Environment\n\n**PowerShell:**\n```powershell\nTest-Path \".gsd/ROADMAP.md\"\nTest-Path \".gsd/STATE.md\"\n```\n\n**Bash:**\n```bash\ntest -f \".gsd/ROADMAP.md\"\ntest -f \".gsd/STATE.md\"\n```\n\n**If not found:** Error — user should run `/plan` first.\n\n---\n\n## 2. Validate Phase Exists\n\n**PowerShell:**\n```powershell\n# Check phase exists in roadmap\nSelect-String -Path \".gsd/ROADMAP.md\" -Pattern \"Phase $PHASE:\"\n```\n\n**Bash:**\n```bash\n# Check phase exists in roadmap\ngrep \"Phase $PHASE:\" \".gsd/ROADMAP.md\"\n```\n\n**If not found:** Error with available phases from ROADMAP.md.\n\n---\n\n## 3. Ensure Phase Directory Exists\n\n**PowerShell:**\n```powershell\n$PHASE_DIR = \".gsd/phases/$PHASE\"\nif (-not (Test-Path $PHASE_DIR)) {\n New-Item -ItemType Directory -Path $PHASE_DIR\n}\n```\n\n**Bash:**\n```bash\nPHASE_DIR=\".gsd/phases/$PHASE\"\nmkdir -p \"$PHASE_DIR\"\n```\n\n---\n\n## 4. Discover Plans\n\n**PowerShell:**\n```powershell\nGet-ChildItem \"$PHASE_DIR/*-PLAN.md\"\n```\n\n**Bash:**\n```bash\nls \"$PHASE_DIR\"/*-PLAN.md 2>/dev/null\n```\n\n**Check for existing summaries** (completed plans):\n\n**PowerShell:**\n```powershell\nGet-ChildItem \"$PHASE_DIR/*-SUMMARY.md\"\n```\n\n**Bash:**\n```bash\nls \"$PHASE_DIR\"/*-SUMMARY.md 2>/dev/null\n```\n\n**Build list of incomplete plans** (PLAN without matching SUMMARY).\n\n**If `--gaps-only`:** Filter to only plans with `gap_closure: true` in frontmatter.\n\n**If no incomplete plans found:** Phase already complete, skip to step 8.\n\n---\n\n## 5. Group Plans by Wave\n\nRead `wave` field from each plan's frontmatter:\n\n```yaml\n---\nphase: 1\nplan: 2\nwave: 1\n---\n```\n\n**Group plans by wave number.** Lower waves execute first.\n\nDisplay wave structure:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► EXECUTING PHASE {N}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nWave 1: {plan-1}, {plan-2}\nWave 2: {plan-3}\n\n{X} plans across {Y} waves\n```\n\n---\n\n## 6. Execute Waves\n\nFor each wave in order:\n\n### 6a. Execute Plans in Wave\nFor each plan in the current wave:\n\n1. **Load plan context** — Read only the PLAN.md file\n2. **Execute tasks** — Follow `` blocks in order\n3. **Verify each task** — Run `` commands\n4. **Commit per task:**\n ```bash\n git add -A\n git commit -m \"feat(phase-{N}): {task-name}\"\n ```\n5. **Create SUMMARY.md** — Document what was done\n\n### 6b. Verify Wave Complete\nCheck all plans in wave have SUMMARY.md files.\n\n### 6c. Proceed to Next Wave\nOnly after current wave fully completes.\n\n---\n\n## 7. Verify Phase Goal\n\nAfter all waves complete:\n\n1. **Read phase goal** from ROADMAP.md\n2. **Check must-haves** against actual codebase (not SUMMARY claims)\n3. **Run verification commands** specified in phase\n\n**Create VERIFICATION.md:**\n```markdown\n## Phase {N} Verification\n\n### Must-Haves\n- [x] Must-have 1 — VERIFIED (evidence: ...)\n- [ ] Must-have 2 — FAILED (reason: ...)\n\n### Verdict: PASS / FAIL\n```\n\n**Route by verdict:**\n- `PASS` → Continue to step 8\n- `FAIL` → Create gap closure plans, offer `/execute {N} --gaps-only`\n\n---\n\n## 8. Update Roadmap and State\n\n**Update ROADMAP.md:**\n```markdown\n### Phase {N}: {Name}\n**Status**: ✅ Complete\n```\n\n**Update STATE.md:**\n```markdown\n## Current Position\n- **Phase**: {N} (completed)\n- **Task**: All tasks complete\n- **Status**: Verified\n\n## Last Session Summary\nPhase {N} executed successfully. {X} plans, {Y} tasks completed.\n\n## Next Steps\n1. Proceed to Phase {N+1}\n```\n\n**Update REQUIREMENTS.md** (if exists):\n- Cross-reference completed tasks with requirement IDs\n- Mark requirements satisfied by this phase as `In Progress` or `Complete`\n- Update the traceability matrix with plan references\n\n---\n\n## 9. Commit Phase Completion\n\n```bash\ngit add .gsd/ROADMAP.md .gsd/STATE.md .gsd/REQUIREMENTS.md\ngit commit -m \"docs(phase-{N}): complete {phase-name}\"\n```\n\n---\n\n## 10. Offer Next Steps\n\n\n\n\nOutput based on status:\n\n**Route A: Phase complete, more phases remain**\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE {N} COMPLETE ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{X} plans executed\nGoal verified ✓\n\n───────────────────────────────────────────────────────\n\n▶ Next Up\nPhase {N+1}: {Name}\n\n/plan {N+1} — create execution plans\n/execute {N+1} — execute directly (if plans exist)\n\n───────────────────────────────────────────────────────\n```\n\n**Route B: All phases complete**\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► MILESTONE COMPLETE 🎉\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nAll phases completed and verified.\n\n───────────────────────────────────────────────────────\n```\n\n**Route C: Gaps found**\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE {N} GAPS FOUND ⚠\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{X}/{Y} must-haves verified\nGap closure plans created.\n\n/execute {N} --gaps-only — execute fix plans\n\n───────────────────────────────────────────────────────\n```\n\n\n\n**After 3 failed debugging attempts:**\n1. Stop current approach\n2. Document to `.gsd/STATE.md` what was tried\n3. Recommend `/pause` for fresh session\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/plan` | Creates PLAN.md files that /execute runs |\n| `/verify` | Validates work after /execute completes |\n| `/debug` | Use when tasks fail verification |\n| `/pause` | Use after 3 debugging failures |\n\n### Skills\n| Skill | Purpose |\n|-------|---------|\n| `executor` | Detailed execution protocol |\n| `context-health-monitor` | 3-strike rule enforcement |\n| `empirical-validation` | Verification requirements |\n\n" }, { "path": ".agent/workflows/help.md", "content": "---\ndescription: Show all available GSD commands\n---\n\n# /help Workflow\n\n\nDisplay all available GSD commands with descriptions and usage hints.\n\n\n\n\n**First, read and display the version:**\n\n**PowerShell:**\n```powershell\n$version = Get-Content \"VERSION\" -ErrorAction SilentlyContinue\nif (-not $version) { $version = \"unknown\" }\n```\n\n**Bash:**\n```bash\nversion=$(cat VERSION 2>/dev/null || echo \"unknown\")\n```\n\n**Then display help with version in header:**\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► HELP (v{version})\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nCORE WORKFLOW\n─────────────\n/map Analyze codebase → ARCHITECTURE.md\n/plan [N] Create PLAN.md files for phase N\n/execute [N] Wave-based execution with atomic commits\n/verify [N] Must-haves validation with proof\n/debug [desc] Systematic debugging (3-strike rule)\n\nPROJECT SETUP\n─────────────\n/new-project Deep questioning → SPEC.md\n/new-milestone Create milestone with phases\n/complete-milestone Archive completed milestone\n/audit-milestone Review milestone quality\n\nPHASE MANAGEMENT\n────────────────\n/add-phase Add phase to end of roadmap\n/insert-phase Insert phase (renumbers subsequent)\n/remove-phase Remove phase (with safety checks)\n/discuss-phase Clarify scope before planning\n/research-phase Deep technical research\n/list-phase-assumptions Surface planning assumptions\n/plan-milestone-gaps Create gap closure plans\n\nNAVIGATION & STATE\n──────────────────\n/progress Show current position in roadmap\n/pause Save state for session handoff\n/resume Restore from last session\n/add-todo Quick capture idea\n/check-todos List pending items\n\nUTILITIES\n─────────\n/help Show this help\n\n───────────────────────────────────────────────────────\n\nQUICK START\n───────────\n1. /new-project → Initialize with deep questioning\n2. /plan 1 → Create Phase 1 plans\n3. /execute 1 → Implement Phase 1\n4. /verify 1 → Confirm it works\n5. Repeat\n\n───────────────────────────────────────────────────────\n\nCORE RULES\n──────────\n🔒 Planning Lock No code until SPEC.md is FINALIZED\n💾 State Persistence Update STATE.md after every task\n🧹 Context Hygiene 3 failures → state dump → fresh session\n✅ Empirical Valid. Proof required, no \"it should work\"\n\n───────────────────────────────────────────────────────\n\n📚 Docs: GSD-STYLE.md, .gsd/examples/\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/insert-phase.md", "content": "---\ndescription: Insert a phase between existing phases (renumbers subsequent)\nargument-hint: \" \"\n---\n\n# /insert-phase Workflow\n\n\nInsert a new phase at a specific position, renumbering all subsequent phases.\n\n\n\n\n## 1. Parse Arguments\n\nExtract:\n- **Position** — Where to insert (e.g., 2 inserts before current Phase 2)\n- **Name** — Phase title\n\n---\n\n## 2. Validate Position\n\n**PowerShell:**\n```powershell\n$totalPhases = (Select-String -Path \".gsd/ROADMAP.md\" -Pattern \"### Phase \\d+\").Count\nif ($position -lt 1 -or $position -gt $totalPhases + 1) {\n Write-Error \"Invalid position. Valid: 1-$($totalPhases + 1)\"\n}\n```\n\n**Bash:**\n```bash\ntotal_phases=$(grep -c \"### Phase [0-9]\" \".gsd/ROADMAP.md\")\nif [ \"$position\" -lt 1 ] || [ \"$position\" -gt $((total_phases + 1)) ]; then\n echo \"Error: Invalid position. Valid: 1-$((total_phases + 1))\" >&2\nfi\n```\n\n---\n\n## 3. Gather Phase Information\n\nAsk for:\n- **Objective** — What this phase achieves\n- **Dependencies** — What it needs from earlier phases\n\n---\n\n## 4. Renumber Existing Phases\n\nFor phases >= position, increment phase number by 1.\n\n**Also update:**\n- Phase directory names (`.gsd/phases/{N}/`)\n- References in PLAN.md files\n- Dependencies in ROADMAP.md\n\n---\n\n## 5. Insert New Phase\n\nAdd at position with correct numbering.\n\n---\n\n## 6. Update STATE.md\n\nIf currently in a phase >= position, update position reference.\n\n---\n\n## 7. Commit\n\n```bash\ngit add -A\ngit commit -m \"docs: insert phase {N} - {name} (renumbered {M} phases)\"\n```\n\n---\n\n## 8. Display Result\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE INSERTED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nInserted: Phase {N}: {name}\nRenumbered: Phases {N+1} through {M}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/plan {N} — Create plans for new phase\n/progress — See updated roadmap\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\nPhase insertion can be disruptive. Consider:\n- In-progress phases may have commits referencing old numbers\n- Existing plans reference phase numbers\n- Use sparingly and early in milestone lifecycle\n\n" }, { "path": ".agent/workflows/install.md", "content": "---\ndescription: Install GSD into the current project from GitHub\n---\n\n# /install Workflow\n\n\nInstall GSD for Antigravity into the current project from GitHub.\n\n\n\n\n## 1. Check for Existing Installation\n\nLook for GSD marker directories:\n\n**PowerShell:**\n```powershell\n$alreadyInstalled = (Test-Path \".agents\") -or (Test-Path \".agent\") -or (Test-Path \".gsd\")\nif ($alreadyInstalled) {\n Write-Output \"GSD files detected in this project.\"\n}\n```\n\n**Bash:**\n```bash\nif [ -d \".agents\" ] || [ -d \".agent\" ] || [ -d \".gsd\" ]; then\n echo \"GSD files detected in this project.\"\nfi\n```\n\n**If already installed:**\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► ALREADY INSTALLED\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nGSD files already exist in this project.\n\n───────────────────────────────────────────────────────\n\nA) Reinstall — Overwrite with latest version\nB) Cancel — Keep current installation\n\nIf you want to update instead: /update\n\n───────────────────────────────────────────────────────\n```\n\nIf user chooses Cancel, exit.\nIf user chooses Reinstall, continue to Step 2.\n\n---\n\n## 2. Clone from GitHub\n\n```bash\ngit clone --depth 1 https://github.com/toonight/get-shit-done-for-antigravity.git .gsd-install-temp\n```\n\n---\n\n## 3. Copy Files\n\n**PowerShell:**\n```powershell\n# Core directories\nCopy-Item -Recurse \".gsd-install-temp\\.agent\" \".\\\"\nCopy-Item -Recurse \".gsd-install-temp\\.agents\" \".\\\"\nCopy-Item -Recurse \".gsd-install-temp\\.gemini\" \".\\\"\nCopy-Item -Recurse \".gsd-install-temp\\.gsd\" \".\\\"\nCopy-Item -Recurse \".gsd-install-temp\\adapters\" \".\\\"\nCopy-Item -Recurse \".gsd-install-temp\\docs\" \".\\\"\nCopy-Item -Recurse \".gsd-install-temp\\scripts\" \".\\\"\n\n# Root files\nCopy-Item -Force \".gsd-install-temp\\PROJECT_RULES.md\" \".\\\"\nCopy-Item -Force \".gsd-install-temp\\GSD-STYLE.md\" \".\\\"\nCopy-Item -Force \".gsd-install-temp\\model_capabilities.yaml\" \".\\\"\n```\n\n**Bash:**\n```bash\n# Core directories\ncp -r .gsd-install-temp/.agent ./\ncp -r .gsd-install-temp/.agents ./\ncp -r .gsd-install-temp/.gemini ./\ncp -r .gsd-install-temp/.gsd ./\ncp -r .gsd-install-temp/adapters ./\ncp -r .gsd-install-temp/docs ./\ncp -r .gsd-install-temp/scripts ./\n\n# Root files\ncp .gsd-install-temp/PROJECT_RULES.md ./\ncp .gsd-install-temp/GSD-STYLE.md ./\ncp .gsd-install-temp/model_capabilities.yaml ./\n```\n\n---\n\n## 4. Cleanup\n\n**PowerShell:**\n```powershell\nRemove-Item -Recurse -Force \".gsd-install-temp\"\n```\n\n**Bash:**\n```bash\nrm -rf .gsd-install-temp\n```\n\n---\n\n## 5. Add to .gitignore (Optional)\n\nCheck if `.gsd/STATE.md` and other session files should be gitignored:\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► ADD TO .gitignore?\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nRecommended .gitignore additions for session-specific files:\n\n.gsd/STATE.md\n.gsd/JOURNAL.md\n.gsd/TODO.md\n\n───────────────────────────────────────────────────────\n\nA) Yes — Add recommended entries\nB) No — Skip\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 6. Confirm Installation\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► INSTALLED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nGSD for Antigravity has been installed.\n\nFiles installed:\n• .agent/ (workflows)\n• .agents/ (skills — Agent Skills standard)\n• .gemini/ (Gemini integration)\n• .gsd/ (project state templates)\n• adapters/ (model-specific enhancements)\n• docs/ (operational documentation)\n• scripts/ (utility scripts)\n• PROJECT_RULES.md\n• GSD-STYLE.md\n• model_capabilities.yaml\n\n───────────────────────────────────────────────────────\n\nNext step:\n\n/new-project — Initialize your project with GSD\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n- This workflow is designed to work from a clean project (no prior GSD installation)\n- It copies ALL necessary files, unlike manual installation which may miss some\n- For updates to an existing installation, use /update instead\n- The /new-project command should be run after installation to set up SPEC.md\n\n" }, { "path": ".agent/workflows/list-phase-assumptions.md", "content": "---\ndescription: List assumptions made during phase planning\nargument-hint: \"\"\n---\n\n# /list-phase-assumptions Workflow\n\n\nSurface and document assumptions made during phase planning that should be validated.\n\n\n\n\n## 1. Load Phase Plans\n\n```powershell\nGet-ChildItem \".gsd/phases/{N}/*-PLAN.md\"\n```\n\n---\n\n## 2. Extract Assumptions\n\nScan plans for:\n- Technology choices without justification\n- Implied dependencies\n- Expected behaviors not verified\n- Time estimates\n- Scope boundaries\n\n---\n\n## 3. Categorize Assumptions\n\n| Category | Risk Level |\n|----------|------------|\n| Technical | API exists, library works, syntax correct |\n| Integration | Services compatible, auth works |\n| Scope | Feature boundaries, what's excluded |\n| Performance | Will handle load, fast enough |\n| Timeline | Estimates accurate |\n\n---\n\n## 4. Display Assumptions\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE {N} ASSUMPTIONS\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nTECHNICAL\n🟡 {assumption 1} — Validate before execution\n🟢 {assumption 2} — Low risk\n\nINTEGRATION\n🔴 {assumption 3} — High risk, verify first\n\nSCOPE\n🟡 {assumption 4} — Confirm with user\n\n───────────────────────────────────────────────────────\n\n▶ ACTIONS\n\n• Validate high-risk assumptions before /execute\n• Add verified assumptions to RESEARCH.md\n• Flag for user review if scope-related\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 5. Offer Validation\n\nAsk if user wants to:\n- Validate specific assumptions now\n- Add to TODO.md for later\n- Accept and proceed\n\n\n" }, { "path": ".agent/workflows/map.md", "content": "---\ndescription: The Architect — Analyze codebase and update ARCHITECTURE.md and STACK.md\n---\n\n# /map Workflow\n\n\nYou are a GSD codebase mapper. You analyze existing codebases to understand structure, patterns, and technical debt.\n\n**Core responsibilities:**\n- Scan project structure and identify components\n- Analyze dependencies and versions\n- Map data flow and integration points\n- Identify technical debt and patterns\n- Document findings for planning context\n\n\n\nAnalyze the existing codebase and produce documentation that enables informed planning.\n\nThis workflow should be run BEFORE `/plan` on brownfield projects to give the planner full context.\n\n\n\n**No arguments required.** Operates on current project directory.\n\n**Outputs:**\n- `.gsd/ARCHITECTURE.md` — System design documentation\n- `.gsd/STACK.md` — Technology inventory\n\n\n\n\n## 1. Validate Project\n\nCheck this is a valid project:\n\n**PowerShell:**\n```powershell\n# Look for common project indicators\n$indicators = @(\n \"package.json\", \"requirements.txt\", \"Cargo.toml\", \n \"go.mod\", \"pom.xml\", \"*.csproj\", \"Gemfile\"\n)\n```\n\n**Bash:**\n```bash\n# Look for common project indicators\nindicators=(\"package.json\" \"requirements.txt\" \"Cargo.toml\" \n \"go.mod\" \"pom.xml\" \"*.csproj\" \"Gemfile\")\n```\n\nDisplay banner:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► MAPPING CODEBASE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n---\n\n## 2. Analyze Project Structure\n\n### 2a. Directory Analysis\n\n**PowerShell:**\n```powershell\nGet-ChildItem -Recurse -Directory | \n Where-Object { $_.Name -notmatch \"node_modules|\\.git|__pycache__|dist|build\" }\n```\n\n**Bash:**\n```bash\nfind . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' \\\n -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*'\n```\n\nIdentify:\n- Source directories (`src/`, `lib/`, `app/`)\n- Test directories (`tests/`, `__tests__/`, `spec/`)\n- Configuration locations\n- Asset directories\n\n### 2b. Entry Points\n\nFind main files:\n**PowerShell:**\n```powershell\n# Example for Node.js\nGet-Content \"package.json\" | ConvertFrom-Json | Select-Object -ExpandProperty main\n```\n\n**Bash:**\n```bash\n# Example for Node.js (requires jq)\ncat package.json | jq -r '.main'\n```\n\n### 2c. Component Detection\n\nScan for common patterns:\n- React components (`*.tsx`, `*.jsx`)\n- API routes (`routes/`, `api/`)\n- Database models (`models/`, `entities/`)\n- Services (`services/`, `lib/`)\n- Utilities (`utils/`, `helpers/`)\n\n---\n\n## 3. Analyze Dependencies\n\n### 3a. Production Dependencies\n\n**PowerShell:**\n```powershell\n# Node.js example\nGet-Content \"package.json\" | ConvertFrom-Json | \n Select-Object -ExpandProperty dependencies\n```\n\n**Bash:**\n```bash\n# Node.js example (requires jq)\ncat package.json | jq '.dependencies'\n```\n\nFor each dependency, note:\n- Name and version\n- Purpose (infer from name/usage)\n- Is it actively used?\n\n### 3b. Development Dependencies\n\nSame for devDependencies, noting:\n- Build tools\n- Test frameworks\n- Linters/formatters\n\n### 3c. Outdated Packages\n\n```bash\nnpm outdated\n# or\npip list --outdated\n```\n\n---\n\n## 4. Map Data Flow\n\n### 4a. External Integrations\n\nSearch for:\n**PowerShell:**\n```powershell\n# API calls\nSelect-String -Path \"src/**/*\" -Pattern \"fetch\\(|axios\\.|http\\.\"\n\n# Database connections\nSelect-String -Path \"**/*\" -Pattern \"DATABASE_URL|mongodb|postgres|mysql\"\n\n# Third-party services\nSelect-String -Path \"**/*\" -Pattern \"stripe|sendgrid|twilio|aws-sdk\"\n```\n\n**Bash:**\n```bash\n# API calls\ngrep -rE 'fetch\\(|axios\\.|http\\.' src/\n\n# Database connections\ngrep -rE 'DATABASE_URL|mongodb|postgres|mysql' .\n\n# Third-party services\ngrep -rE 'stripe|sendgrid|twilio|aws-sdk' .\n```\n\n### 4b. Internal Flow\n\nTrace how data moves:\n- Entry point → Business logic → Data layer → Output\n- Identify shared state (context, stores, singletons)\n\n---\n\n## 5. Identify Technical Debt\n\n### 5a. Code Smells\n\nSearch for indicators:\n**PowerShell:**\n```powershell\n# TODOs and FIXMEs\nSelect-String -Path \"src/**/*\" -Pattern \"TODO|FIXME|HACK|XXX\"\n\n# Deprecated markers\nSelect-String -Path \"**/*\" -Pattern \"@deprecated|DEPRECATED\"\n```\n\n**Bash:**\n```bash\n# TODOs and FIXMEs\ngrep -rE 'TODO|FIXME|HACK|XXX' src/\n\n# Deprecated markers\ngrep -rE '@deprecated|DEPRECATED' .\n```\n\n### 5b. Pattern Inconsistencies\n\nNote where patterns differ:\n- Naming conventions\n- File organization\n- Error handling approaches\n\n### 5c. Missing Elements\n\nIdentify gaps:\n- No tests for critical paths\n- Missing error boundaries\n- No input validation\n- No logging/monitoring\n\n---\n\n## 6. Write ARCHITECTURE.md\n\n```markdown\n# Architecture\n\n> Auto-generated by /map on {date}\n\n## Overview\n\n{High-level description of what this system does}\n\n```\n┌─────────────────────────────────────────┐\n│ [Entry Point] │\n├─────────────────────────────────────────┤\n│ [Business Logic Layer] │\n├─────────────────────────────────────────┤\n│ [Data Layer] │\n└─────────────────────────────────────────┘\n```\n\n## Components\n\n### {Component 1}\n- **Purpose:** {what it does}\n- **Location:** `{path}`\n- **Dependencies:** {what it imports}\n\n### {Component 2}\n...\n\n## Data Flow\n\n1. {Step 1}\n2. {Step 2}\n3. {Step 3}\n\n## Integration Points\n\n| Service | Type | Purpose |\n|---------|------|---------|\n| {name} | API | {purpose} |\n\n## Technical Debt\n\n- [ ] {Debt item 1}\n- [ ] {Debt item 2}\n\n## Conventions\n\n**Naming:** {patterns observed}\n**Structure:** {organization patterns}\n**Testing:** {test patterns}\n```\n\n---\n\n## 7. Write STACK.md\n\n```markdown\n# Technology Stack\n\n> Auto-generated by /map on {date}\n\n## Runtime\n\n| Technology | Version | Purpose |\n|------------|---------|---------|\n| {runtime} | {version} | Core runtime |\n\n## Dependencies\n\n### Production\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {pkg} | {ver} | {purpose} |\n\n### Development\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {pkg} | {ver} | {purpose} |\n\n## Infrastructure\n\n| Service | Provider | Purpose |\n|---------|----------|---------|\n| {service} | {provider} | {purpose} |\n\n## Configuration\n\n| Variable | Purpose | Location |\n|----------|---------|----------|\n| {var} | {purpose} | {file} |\n\n## Outdated Packages\n\n| Package | Current | Latest | Risk |\n|---------|---------|--------|------|\n| {pkg} | {cur} | {new} | {risk} |\n```\n\n---\n\n## 8. Update State\n\nUpdate `.gsd/STATE.md`:\n```markdown\n## Last Session Summary\nCodebase mapping complete.\n- {N} components identified\n- {M} dependencies analyzed\n- {K} technical debt items found\n```\n\n---\n\n## 9. Commit Documentation\n\n```bash\ngit add .gsd/ARCHITECTURE.md .gsd/STACK.md .gsd/STATE.md\ngit commit -m \"docs: map existing codebase\"\n```\n\n---\n\n## 10. Offer Next Steps\n\n\n\n\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► CODEBASE MAPPED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nComponents: {N}\nDependencies: {M} production, {K} dev\nTechnical debt: {J} items\n\n───────────────────────────────────────────────────────\n\n▶ Next Up\n\n/plan — create execution plans with full context\n\nFiles updated:\n• .gsd/ARCHITECTURE.md\n• .gsd/STACK.md\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/plan` | Use ARCHITECTURE.md from /map for planning context |\n\n### Skills\n| Skill | Purpose |\n|-------|---------|\n| `codebase-mapper` | Detailed mapping methodology |\n\n" }, { "path": ".agent/workflows/new-milestone.md", "content": "---\ndescription: Create a new milestone with phases\nargument-hint: \"\"\n---\n\n# /new-milestone Workflow\n\n\nDefine a new milestone with goal, phases, and success criteria.\n\n\n\n\n## 1. Validate SPEC Exists\n\n**PowerShell:**\n```powershell\nif (-not (Test-Path \".gsd/SPEC.md\")) {\n Write-Error \"SPEC.md required. Run /new-project first.\"\n}\n```\n\n**Bash:**\n```bash\nif [ ! -f \".gsd/SPEC.md\" ]; then\n echo \"Error: SPEC.md required. Run /new-project first.\" >&2\nfi\n```\n\n---\n\n## 2. Gather Milestone Information\n\nAsk for:\n- **Name** — Milestone identifier (e.g., \"v1.0\", \"MVP\", \"Beta\")\n- **Goal** — What does this milestone achieve?\n- **Must-haves** — Non-negotiable deliverables\n- **Nice-to-haves** — Optional if time permits\n\n---\n\n## 3. Generate Phase Breakdown\n\nBased on goal and must-haves, suggest phases:\n\n```markdown\n## Suggested Phases\n\nPhase 1: {Foundation/Setup}\nPhase 2: {Core Feature A}\nPhase 3: {Core Feature B}\nPhase 4: {Integration/Polish}\nPhase 5: {Verification/Launch}\n```\n\nAsk user to confirm or modify.\n\n---\n\n## 4. Update ROADMAP.md\n\n```markdown\n# ROADMAP.md\n\n> **Current Milestone**: {name}\n> **Goal**: {goal}\n\n## Must-Haves\n- [ ] {must-have 1}\n- [ ] {must-have 2}\n\n## Phases\n\n### Phase 1: {name}\n**Status**: ⬜ Not Started\n**Objective**: {description}\n\n### Phase 2: {name}\n**Status**: ⬜ Not Started\n**Objective**: {description}\n\n...\n```\n\n---\n\n## 5. Update STATE.md\n\n```markdown\n## Current Position\n- **Milestone**: {name}\n- **Phase**: Not started\n- **Status**: Milestone planned\n```\n\n---\n\n## 5b. Reset Session Files (if starting fresh)\n\nIf DECISIONS.md or JOURNAL.md contain entries from a previous milestone, reset them to prevent monolithic growth:\n\n**PowerShell:**\n```powershell\n# Only reset if files are non-empty and no archive exists yet\nif ((Test-Path \".gsd/DECISIONS.md\") -and (Get-Content \".gsd/DECISIONS.md\" | Measure-Object -Line).Lines -gt 5) {\n Set-Content \".gsd/DECISIONS.md\" \"# Decisions`n`n---`n\"\n}\nif ((Test-Path \".gsd/JOURNAL.md\") -and (Get-Content \".gsd/JOURNAL.md\" | Measure-Object -Line).Lines -gt 5) {\n Set-Content \".gsd/JOURNAL.md\" \"# Journal`n`n---`n\"\n}\n```\n\n**Bash:**\n```bash\nif [ -f \".gsd/DECISIONS.md\" ] && [ \"$(wc -l < .gsd/DECISIONS.md)\" -gt 5 ]; then\n printf '# Decisions\\n\\n---\\n' > .gsd/DECISIONS.md\nfi\nif [ -f \".gsd/JOURNAL.md\" ] && [ \"$(wc -l < .gsd/JOURNAL.md)\" -gt 5 ]; then\n printf '# Journal\\n\\n---\\n' > .gsd/JOURNAL.md\nfi\n```\n\n> **Note:** Only resets if files have grown beyond a header. If running `/complete-milestone` first, files are already archived and reset.\n\n---\n\n## 6. Commit\n\n```bash\ngit add .gsd/ROADMAP.md .gsd/STATE.md\ngit commit -m \"docs: create milestone {name}\"\n```\n\n---\n\n## 7. Offer Next Steps\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► MILESTONE CREATED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nMilestone: {name}\nPhases: {N}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/plan 1 — Create Phase 1 execution plans\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/new-project.md", "content": "---\ndescription: Initialize a new project with deep context gathering\n---\n\n# /new-project Workflow\n\n\nInitialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.\n\nThis is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. One command takes you from idea to ready-for-planning.\n\n**Creates:**\n- `.gsd/SPEC.md` — project specification\n- `.gsd/ROADMAP.md` — phase structure\n- `.gsd/STATE.md` — project memory\n- `.gsd/ARCHITECTURE.md` — system design (if brownfield)\n- All other .gsd/ documentation files\n\n**After this command:** Run `/plan 1` to start execution.\n\n\n\n\n## Phase 1: Setup\n**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**\n\n1. **Abort if project exists:**\n\n **PowerShell:**\n ```powershell\n if (Test-Path \".gsd/SPEC.md\") {\n Write-Error \"Project already initialized. Use /progress\"\n exit 1\n }\n ```\n\n **Bash:**\n ```bash\n if [ -f \".gsd/SPEC.md\" ]; then\n echo \"Error: Project already initialized. Use /progress\" >&2\n exit 1\n fi\n ```\n\n2. **Initialize git repo** (if not exists):\n\n **PowerShell:**\n ```powershell\n if (-not (Test-Path \".git\")) {\n git init\n Write-Output \"Initialized new git repo\"\n }\n ```\n\n **Bash:**\n ```bash\n if [ ! -d \".git\" ]; then\n git init\n echo \"Initialized new git repo\"\n fi\n ```\n\n3. **Detect existing code (brownfield detection):**\n\n **PowerShell:**\n ```powershell\n $codeFiles = Get-ChildItem -Recurse -Include \"*.ts\",\"*.js\",\"*.py\",\"*.go\",\"*.rs\" | \n Where-Object { $_.FullName -notmatch \"node_modules|\\.git\" } | \n Select-Object -First 20\n \n $hasPackage = Test-Path \"package.json\" -or Test-Path \"requirements.txt\" -or Test-Path \"Cargo.toml\"\n $hasArchitecture = Test-Path \".gsd/ARCHITECTURE.md\"\n ```\n\n **Bash:**\n ```bash\n code_files=$(find . -type f \\( -name \"*.ts\" -o -name \"*.js\" -o -name \"*.py\" -o -name \"*.go\" -o -name \"*.rs\" \\) \\\n -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20)\n \n has_package=$(test -f \"package.json\" -o -f \"requirements.txt\" -o -f \"Cargo.toml\" && echo true || echo false)\n has_architecture=$(test -f \".gsd/ARCHITECTURE.md\" && echo true || echo false)\n ```\n\n---\n\n## Phase 2: Brownfield Offer\n**If existing code detected and ARCHITECTURE.md doesn't exist:**\n\n```\n⚠️ EXISTING CODE DETECTED\n\nFound {N} source files in this directory.\n\nOptions:\nA) Map codebase first — Run /map to understand existing architecture (Recommended)\nB) Skip mapping — Proceed with project initialization\n\nWhich do you prefer?\n```\n\n**If \"Map codebase first\":**\n```\nRun `/map` first, then return to `/new-project`\n```\nExit command.\n\n**If \"Skip mapping\":** Continue to Phase 3.\n**If no existing code detected OR codebase already mapped:** Continue to Phase 3.\n\n---\n\n## Phase 3: Deep Questioning\n\nDisplay banner:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► QUESTIONING\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**Open the conversation:**\n\nAsk: \"What do you want to build?\"\n\nWait for response. This gives context for intelligent follow-ups.\n\n**Follow the thread:**\n\nBased on their answer, ask follow-up questions that dig deeper:\n- What excited them about this idea\n- What problem sparked this\n- What they mean by vague terms\n- What it would actually look like\n- What's already decided\n\n**Questioning techniques:**\n- Challenge vagueness: \"When you say 'fast', what does that mean specifically?\"\n- Make abstract concrete: \"Give me an example of how a user would...\"\n- Surface assumptions: \"You're assuming users will... Is that validated?\"\n- Find edges: \"What's explicitly NOT in scope?\"\n- Reveal motivation: \"Why does this matter now?\"\n\n**Context checklist (gather mentally, not as interrogation):**\n- [ ] Vision — What does success look like?\n- [ ] Users — Who is this for?\n- [ ] Problem — What pain does it solve?\n- [ ] Scope — What's in, what's out?\n- [ ] Constraints — Technical, timeline, budget?\n- [ ] Prior art — What exists already?\n\n**Decision gate:**\n\nWhen you could write a clear SPEC.md:\n```\nReady to create SPEC.md?\n\nA) Create SPEC.md — Let's move forward\nB) Keep exploring — I want to share more\n```\n\nIf \"Keep exploring\" — ask what they want to add, or identify gaps and probe naturally.\n\nLoop until \"Create SPEC.md\" selected.\n\n---\n\n## Phase 4: Write SPEC.md\n\nCreate `.gsd/SPEC.md`:\n\n```markdown\n# SPEC.md — Project Specification\n\n> **Status**: `FINALIZED`\n\n## Vision\n{Distilled from questioning — one paragraph max}\n\n## Goals\n1. {Primary goal}\n2. {Secondary goal}\n3. {Tertiary goal}\n\n## Non-Goals (Out of Scope)\n- {Explicitly excluded}\n- {Not in this version}\n\n## Users\n{Who will use this and how}\n\n## Constraints\n- {Technical constraints}\n- {Timeline constraints}\n- {Other limitations}\n\n## Success Criteria\n- [ ] {Measurable outcome 1}\n- [ ] {Measurable outcome 2}\n```\n\n---\n\n## Phase 5: Research Decision\n\nIf project involves unfamiliar technology or architectural decisions:\n\n```\n📚 RESEARCH CHECK\n\nThis project involves {area where research might help}.\n\nWould you like to:\nA) Do research first — Investigate options before committing\nB) Skip research — I know what I want, let's plan\n\n```\n\n**If research selected:**\n- Create `.gsd/RESEARCH.md` with findings\n- Document technology choices and rationale\n- Return to continue\n\n---\n\n## Phase 6: Define Requirements\n\nGenerate requirements from SPEC.md:\n\n```markdown\n# REQUIREMENTS.md\n\n## Format\n| ID | Requirement | Source | Status |\n|----|-------------|--------|--------|\n| REQ-01 | {requirement} | SPEC goal 1 | Pending |\n| REQ-02 | {requirement} | SPEC goal 2 | Pending |\n```\n\n**Rules:**\n- Each requirement is testable\n- Each maps to a SPEC goal\n- Status starts as \"Pending\"\n\n**If simple project:** Skip formal requirements, SPEC.md is sufficient.\n\n---\n\n## Phase 7: Create Roadmap\n\nCreate `.gsd/ROADMAP.md`:\n\n```markdown\n# ROADMAP.md\n\n> **Current Phase**: Not started\n> **Milestone**: v1.0\n\n## Must-Haves (from SPEC)\n- [ ] {must-have 1}\n- [ ] {must-have 2}\n\n## Phases\n\n### Phase 1: {Foundation}\n**Status**: ⬜ Not Started\n**Objective**: {what this delivers}\n**Requirements**: REQ-01, REQ-02\n\n### Phase 2: {Core Feature}\n**Status**: ⬜ Not Started\n**Objective**: {what this delivers}\n**Requirements**: REQ-03\n\n### Phase 3: {Integration}\n**Status**: ⬜ Not Started\n**Objective**: {what this delivers}\n\n### Phase 4: {Polish/Launch}\n**Status**: ⬜ Not Started\n**Objective**: {final touches}\n```\n\n**Phase creation rules:**\n- 3-5 phases per milestone\n- Each phase has clear deliverable\n- Dependencies flow forward\n\n---\n\n## Phase 8: Initialize Remaining Files\n\nCreate with templates:\n- `.gsd/STATE.md` — Empty state\n- `.gsd/DECISIONS.md` — Empty ADR log\n- `.gsd/JOURNAL.md` — Empty journal\n- `.gsd/TODO.md` — Empty todo list\n\nCreate directories:\n- `.gsd/phases/`\n- `.gsd/templates/`\n\n---\n\n## Phase 9: Initial Commit\n\n```bash\ngit add .gsd/\ngit commit -m \"chore: initialize GSD project\n\n- SPEC.md with vision and goals\n- ROADMAP.md with {N} phases\n- Project documentation structure\"\n```\n\n---\n\n## Phase 10: Done\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PROJECT INITIALIZED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nProject: {name}\nPhases: {N}\n\nFiles created:\n• .gsd/SPEC.md (FINALIZED)\n• .gsd/ROADMAP.md ({N} phases)\n• .gsd/STATE.md\n• .gsd/DECISIONS.md\n• .gsd/JOURNAL.md\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/discuss-phase 1 — Clarify scope (optional but recommended)\n/plan 1 — Create Phase 1 execution plans\n\n───────────────────────────────────────────────────────\n\n💡 The questioning phase is the highest-leverage moment.\n Time invested here pays dividends throughout execution.\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n## Why Deep Questioning Matters\n\nThe original GSD emphasizes that `/new-project` is the most leveraged moment. \nEvery minute spent understanding what to build saves hours of building the wrong thing.\n\n**Signs questioning is done:**\n- You could explain the project to a stranger\n- You know what's NOT being built (scope edges)\n- Success criteria are measurable\n- You're excited to start planning\n\n**Signs more questioning needed:**\n- Vague terms remain unexplained\n- You don't know who the user is\n- Success is defined as \"it works\"\n- Scope keeps expanding during discussion\n\n" }, { "path": ".agent/workflows/pause.md", "content": "---\ndescription: Context hygiene — dump state for clean session handoff\n---\n\n# /pause Workflow\n\n\nSafely pause work with complete state preservation for session handoff.\n\n\n\n- Ending a work session\n- Context getting heavy (many failed attempts)\n- Switching to a different task\n- Before taking a break\n- After 3+ debugging failures (Context Hygiene rule)\n\n\n\n\n## 1. Capture Current State\n\nUpdate `.gsd/STATE.md`:\n\n```markdown\n## Current Position\n- **Phase**: {current phase number and name}\n- **Task**: {specific task in progress, if any}\n- **Status**: Paused at {timestamp}\n\n## Last Session Summary\n{What was accomplished this session}\n\n## In-Progress Work\n{Any uncommitted changes or partial work}\n- Files modified: {list}\n- Tests status: {passing/failing/not run}\n\n## Blockers\n{What was preventing progress, if anything}\n\n## Context Dump\n{Critical context that would be lost}:\n\n### Decisions Made\n- {Decision 1}: {rationale}\n- {Decision 2}: {rationale}\n\n### Approaches Tried\n- {Approach 1}: {outcome}\n- {Approach 2}: {outcome}\n\n### Current Hypothesis\n{Best guess at solution/issue}\n\n### Files of Interest\n- `{file1}`: {what's relevant}\n- `{file2}`: {what's relevant}\n\n## Next Steps\n1. {Specific first action for next session}\n2. {Second priority}\n3. {Third priority}\n```\n\n---\n\n## 2. Add Journal Entry\n\nCreate entry in `.gsd/JOURNAL.md`:\n\n```markdown\n## Session: {YYYY-MM-DD HH:MM}\n\n### Objective\n{What this session was trying to accomplish}\n\n### Accomplished\n- {Item 1}\n- {Item 2}\n\n### Verification\n- [x] {What was verified}\n- [ ] {What still needs verification}\n\n### Paused Because\n{Reason for pausing}\n\n### Handoff Notes\n{Critical info for resuming}\n```\n\n---\n\n## 3. Commit State\n\n```bash\ngit add .gsd/STATE.md .gsd/JOURNAL.md\ngit commit -m \"docs: pause session - {brief reason}\"\n```\n\n---\n\n## 4. Display Handoff\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► SESSION PAUSED ⏸\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nState saved to:\n• .gsd/STATE.md\n• .gsd/JOURNAL.md\n\n───────────────────────────────────────────────────────\n\nTo resume later:\n\n/resume\n\n───────────────────────────────────────────────────────\n\n💡 Fresh context = fresh perspective\n The struggles end here. Next session starts clean.\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\nIf pausing due to debugging failures:\n\n1. Be explicit about what failed\n2. Document exact error messages\n3. List files that were touched\n4. State your hypothesis clearly\n5. Suggest what to try next (different approach)\n\nA fresh context often immediately sees solutions that a polluted context missed.\n\n\n\n## Proactive Auto-Save (Session Limit Protection)\n\n**Problem:** If a session hard-terminates (usage/context limit), `/pause` becomes unreachable.\n\n**Solution:** The agent should auto-save state BEFORE limits are hit.\n\n### When to Auto-Save\n\n| Trigger | Action |\n|---------|--------|\n| Context usage reaches ~50-70% | Write lightweight state snapshot to `.gsd/STATE.md` |\n| 3-strike debugging rule fires | Save state dump BEFORE recommending `/pause` |\n| Extended session detected | Periodic state checkpoints to `.gsd/STATE.md` |\n\n### Auto-Save Protocol\n\n1. **Detect** context health warning signals (see context-health-monitor skill)\n2. **Write** current state to `.gsd/STATE.md` immediately\n3. **Then** inform the user and recommend `/pause`\n4. If session terminates unexpectedly, state is already saved\n\n### Minimum Auto-Save Content\n\n```markdown\n## Auto-Save: {timestamp}\n- **Phase**: {current phase}\n- **Task**: {current task or \"between tasks\"}\n- **Last Action**: {what was just completed}\n- **Next Step**: {what should happen next}\n```\n\n**Key principle:** Save first, recommend second. Never rely on the user being able to issue `/pause`.\n\n" }, { "path": ".agent/workflows/plan-milestone-gaps.md", "content": "---\ndescription: Create plans to address gaps found in milestone audit\n---\n\n# /plan-milestone-gaps Workflow\n\n\nCreate targeted plans to address gaps, technical debt, and issues identified during milestone audit.\n\n\n\n\n## 1. Load Gap Information\n\nRead from:\n- Latest AUDIT.md or VERIFICATION.md\n- TODO.md for deferred items\n- DECISIONS.md for acknowledged debt\n\n---\n\n## 2. Categorize Gaps\n\n| Category | Priority | Action |\n|----------|----------|--------|\n| Must-have failures | 🔴 High | Create fix phase |\n| Technical debt | 🟡 Medium | Add to roadmap |\n| Nice-to-have misses | 🟢 Low | Add to backlog |\n\n---\n\n## 3. Create Gap Closure Phase\n\nAdd new phase to ROADMAP.md:\n\n```markdown\n### Phase {N}: Gap Closure\n**Status**: ⬜ Not Started\n**Objective**: Address gaps from milestone audit\n\n**Gaps to Close:**\n- [ ] {gap 1}\n- [ ] {gap 2}\n```\n\n---\n\n## 4. Create PLAN.md for Each Gap\n\n```markdown\n---\nphase: {N}\nplan: fix-{gap-id}\nwave: 1\ngap_closure: true\n---\n\n# Fix: {Gap Description}\n\n## Problem\n{What the audit found}\n\n## Root Cause\n{Why it exists}\n\n## Tasks\n\n\n Fix {issue}\n {files}\n {fix instructions}\n {original verification that failed}\n {criteria}\n\n```\n\n---\n\n## 5. Update STATE.md\n\n```markdown\n## Gap Closure Mode\nAddressing {N} gaps from milestone audit.\n```\n\n---\n\n## 6. Commit Plans\n\n```powershell\ngit add .gsd/\ngit commit -m \"docs: create gap closure plans\"\n```\n\n---\n\n## 7. Offer Execution\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► GAP CLOSURE PLANS CREATED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nGaps identified: {N}\nPlans created: {M}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/execute {N} --gaps-only — Execute gap closure plans\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/plan.md", "content": "---\ndescription: The Strategist — Decompose requirements into executable phases in ROADMAP.md\nargument-hint: \"[phase] [--research] [--skip-research] [--gaps]\"\n---\n\n# /plan Workflow\n\n\nYou are a GSD planner orchestrator. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification.\n\n**Core responsibilities:**\n- Parse arguments and validate phase\n- Handle research (unless skipped or exists)\n- Create PLAN.md files with XML task structure\n- Verify plans with checker logic\n- Iterate until plans pass (max 3 iterations)\n\n\n\nCreate executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.\n\n**Default flow:** Research (if needed) → Plan → Verify → Done\n\n**Why subagents:** Research and planning burn context fast. Verification uses fresh context. User sees the flow between agents in main context.\n\n\n\n**Phase number:** $ARGUMENTS (optional — auto-detects next unplanned phase if not provided)\n\n**Flags:**\n- `--research` — Force re-research even if RESEARCH.md exists\n- `--skip-research` — Skip research entirely, go straight to planning\n- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)\n\n**Required files:**\n- `.gsd/SPEC.md` — Must be FINALIZED (Planning Lock)\n- `.gsd/ROADMAP.md` — Must have phases defined\n\n\n\n\n## Solo Developer + Claude Workflow\nYou are planning for ONE person (the user) and ONE implementer (Claude).\n- No teams, stakeholders, ceremonies, coordination overhead\n- User is the visionary/product owner\n- Claude is the builder\n\n## Plans Are Prompts\nPLAN.md is NOT a document that gets transformed into a prompt.\nPLAN.md IS the prompt. It contains:\n- Objective (what and why)\n- Context (@file references)\n- Tasks (with verification criteria)\n- Success criteria (measurable)\n\n## Quality Degradation Curve\n\n| Context Usage | Quality | State |\n|---------------|---------|-------|\n| 0-30% | PEAK | Thorough, comprehensive |\n| 30-50% | GOOD | Confident, solid work |\n| 50-70% | DEGRADING | Efficiency mode begins |\n| 70%+ | POOR | Rushed, minimal |\n\n**The rule:** Plans should complete within ~50% context. More plans, smaller scope.\n\n## Aggressive Atomicity\nEach plan: **2-3 tasks max**. No exceptions.\n\n\n\n\n\n## Discovery Protocol\n\nDiscovery is MANDATORY unless you can prove current context exists.\n\n**Level 0 — Skip** (pure internal work)\n- ALL work follows established codebase patterns\n- No new external dependencies\n- Pure internal refactoring or feature extension\n\n**Level 1 — Quick Verification** (2-5 min)\n- Single known library, confirming syntax/version\n- Low-risk decision (easily changed later)\n- Action: Quick web search, no RESEARCH.md needed\n\n**Level 1.5 — Discovery** (5-15 min)\n- Quick library/option comparison (A vs B)\n- Low-to-medium risk, focused question\n- Action: Create DISCOVERY.md using `.gsd/templates/discovery.md` template\n\n**Level 2 — Standard Research** (15-30 min)\n- Choosing between 2-3 options\n- New external integration (API, service)\n- Medium-risk decision\n- Action: Create RESEARCH.md with findings\n\n**Level 3 — Deep Dive** (1+ hour)\n- Architectural decision with long-term impact\n- Novel problem without clear patterns\n- High-risk, hard to change later\n- Action: Full research with RESEARCH.md\n\n\n\n\n\n## 1. Validate Environment (Planning Lock)\n\n**PowerShell:**\n```powershell\n# Check SPEC.md exists and is finalized\n$spec = Get-Content \".gsd/SPEC.md\" -Raw\nif ($spec -notmatch \"FINALIZED\") {\n Write-Error \"SPEC.md must be FINALIZED before planning\"\n exit\n}\n```\n\n**Bash:**\n```bash\n# Check SPEC.md exists and is finalized\nif ! grep -q \"FINALIZED\" \".gsd/SPEC.md\"; then\n echo \"Error: SPEC.md must be FINALIZED before planning\" >&2\n exit 1\nfi\n```\n\n**If not finalized:** Error — user must complete SPEC.md first.\n\n---\n\n## 2. Parse and Normalize Arguments\n\nExtract from $ARGUMENTS:\n- Phase number (integer)\n- `--research` flag\n- `--skip-research` flag\n- `--gaps` flag\n\n**If no phase number:** Detect next unplanned phase from ROADMAP.md.\n\n---\n\n## 3. Validate Phase\n\n**PowerShell:**\n```powershell\nSelect-String -Path \".gsd/ROADMAP.md\" -Pattern \"Phase $PHASE:\"\n```\n\n**Bash:**\n```bash\ngrep \"Phase $PHASE:\" \".gsd/ROADMAP.md\"\n```\n\n**If not found:** Error with available phases.\n**If found:** Extract phase name and description.\n\n---\n\n## 4. Ensure Phase Directory\n\n**PowerShell:**\n```powershell\n$PHASE_DIR = \".gsd/phases/$PHASE\"\nif (-not (Test-Path $PHASE_DIR)) {\n New-Item -ItemType Directory -Path $PHASE_DIR\n}\n```\n\n**Bash:**\n```bash\nPHASE_DIR=\".gsd/phases/$PHASE\"\nmkdir -p \"$PHASE_DIR\"\n```\n\n---\n\n## 5. Handle Research\n\n**If `--gaps` flag:** Skip research (gap closure uses VERIFICATION.md).\n\n**If `--skip-research` flag:** Skip to step 6.\n\n**Check for existing research:**\n**PowerShell:**\n```powershell\nTest-Path \"$PHASE_DIR/RESEARCH.md\"\n```\n\n**Bash:**\n```bash\ntest -f \"$PHASE_DIR/RESEARCH.md\"\n```\n\n**If RESEARCH.md exists AND `--research` flag NOT set:**\n- Display: `Using existing research: $PHASE_DIR/RESEARCH.md`\n- Skip to step 6\n\n**If research needed:**\n\nDisplay banner:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► RESEARCHING PHASE {N}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\nPerform research based on discovery level (see ``).\n\nCreate `$PHASE_DIR/RESEARCH.md` with findings.\n\n---\n\n## 6. Create Plans\n\nDisplay banner:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PLANNING PHASE {N}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n### 6a. Gather Context\nLoad:\n- `.gsd/SPEC.md` — Requirements\n- `.gsd/REQUIREMENTS.md` — Formal requirements tracking (if exists)\n- `.gsd/ROADMAP.md` — Phase description\n- `$PHASE_DIR/RESEARCH.md` — If exists\n- `.gsd/ARCHITECTURE.md` — If exists\n\n### 6b. Decompose into Tasks\nFor the phase goal:\n1. Identify all deliverables\n2. Break into atomic tasks (2-3 per plan)\n3. Determine dependencies between tasks\n4. Assign execution waves\n\n### 6c. Write PLAN.md Files\n\nCreate `$PHASE_DIR/{N}-PLAN.md`:\n\n```markdown\n---\nphase: {N}\nplan: 1\nwave: 1\n---\n\n# Plan {N}.1: {Plan Name}\n\n## Objective\n{What this plan delivers and why}\n\n## Context\n- .gsd/SPEC.md\n- .gsd/ARCHITECTURE.md\n- {relevant source files}\n\n## Tasks\n\n\n {Task name}\n {exact file paths}\n \n {Specific implementation instructions}\n - What to do\n - What to avoid and WHY\n \n {Command to prove task complete}\n {Measurable acceptance criteria}\n\n\n\n ...\n\n\n## Success Criteria\n- [ ] {Measurable outcome 1}\n- [ ] {Measurable outcome 2}\n```\n\n---\n\n## 7. Verify Plans (Checker Logic)\n\nFor each plan, verify:\n- [ ] All files specified exist or will be created\n- [ ] Actions are specific (no \"implement X\")\n- [ ] Verify commands are executable\n- [ ] Done criteria are measurable\n- [ ] Context references exist\n- [ ] Tests are meaningful (see Test Quality Rules below)\n\n**If issues found:** Fix and re-verify (max 3 iterations).\n\n### Test Quality Rules\n\nTests must verify real behavior, not just pass. Reject plans with tests that:\n\n| Anti-pattern | Example | Fix |\n|-------------|---------|-----|\n| **Mock everything** | Mocking the DB then asserting the mock was called | Use real DB or integration test |\n| **Tautological assert** | `assert mock.called` with no behavior check | Assert actual output or side effect |\n| **Always-pass test** | `assert True` or `assert response is not None` | Assert specific expected values |\n| **Testing the framework** | Asserting that Express returns 200 on a stub | Test your logic, not the framework |\n| **No negative cases** | Only testing the happy path | Include at least one failure/edge case |\n\n**Rule:** Every `` command must test the *actual behavior* of the code, not just that it runs without errors. If a test would still pass with the implementation deleted, it is not a valid test.\n\n---\n\n## 8. Update State\n\nUpdate `.gsd/STATE.md`:\n```markdown\n## Current Position\n- **Phase**: {N}\n- **Task**: Planning complete\n- **Status**: Ready for execution\n\n## Next Steps\n1. /execute {N}\n```\n\n---\n\n## 9. Commit Plans\n\n```bash\ngit add .gsd/phases/$PHASE/\ngit add .gsd/STATE.md\ngit commit -m \"docs(phase-$PHASE): create execution plans\"\n```\n\n---\n\n## 10. Offer Next Steps\n\n\n\n\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE {N} PLANNED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{X} plans created across {Y} waves\n\nPlans:\n• {N}.1: {Name} (wave 1)\n• {N}.2: {Name} (wave 1)\n• {N}.3: {Name} (wave 2)\n\n───────────────────────────────────────────────────────\n\n▶ Next Up\n\n/execute {N} — run all plans\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n\n| Type | Use For | Autonomy |\n|------|---------|----------|\n| `auto` | Everything Claude can do independently | Fully autonomous |\n| `checkpoint:human-verify` | Visual/functional verification | Pauses for user |\n| `checkpoint:decision` | Implementation choices | Pauses for user |\n\n**Automation-first rule:** If Claude CAN do it, Claude MUST do it. Checkpoints are for verification AFTER automation.\n\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/map` | Run before /plan to get codebase context |\n| `/execute` | Runs PLAN.md files created by /plan |\n| `/verify` | Validates executed plans |\n\n### Skills\n| Skill | Purpose |\n|-------|---------|\n| `planner` | Detailed planning methodology |\n| `plan-checker` | Validates plans before execution |\n\n" }, { "path": ".agent/workflows/progress.md", "content": "---\ndescription: Show current position in roadmap and next steps\n---\n\n# /progress Workflow\n\n\nQuick status check — where are we and what's next?\n\n\n\n\n## 1. Load Current State\n\nRead:\n- `.gsd/STATE.md` — Current position\n- `.gsd/ROADMAP.md` — Phase statuses\n\n---\n\n## 2. Calculate Progress\n\nCount phases:\n- Total phases\n- Completed phases (✅)\n- In progress (🔄)\n- Blocked (⏸️)\n- Not started (⬜)\n\n---\n\n## 3. Display Status\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PROGRESS\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nProject: {project name from SPEC.md}\nMilestone: {milestone from ROADMAP.md}\n\n───────────────────────────────────────────────────────\n\nPHASES\n\n✅ Phase 1: {Name}\n✅ Phase 2: {Name}\n🔄 Phase 3: {Name} ← CURRENT\n⬜ Phase 4: {Name}\n⬜ Phase 5: {Name}\n\nProgress: {completed}/{total} ({percentage}%)\n\n───────────────────────────────────────────────────────\n\nCURRENT TASK\n\n{Current task from STATE.md, or \"None\"}\n\n───────────────────────────────────────────────────────\n\nBLOCKERS\n\n{Blockers from STATE.md, or \"None\"}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT UP\n\n{Recommended next action based on state}\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 4. Suggest Action\n\nBased on status, recommend:\n\n| State | Recommendation |\n|-------|----------------|\n| Phase in progress | `/execute {N}` to continue |\n| Phase done, not verified | `/verify {N}` |\n| Verification failed | `/execute {N} --gaps-only` |\n| All phases complete | Celebrate! 🎉 |\n| No phases started | `/plan 1` to begin |\n| SPEC not finalized | Complete SPEC.md first |\n\n\n" }, { "path": ".agent/workflows/remove-phase.md", "content": "---\ndescription: Remove a phase from the roadmap (with safety checks)\nargument-hint: \"\"\n---\n\n# /remove-phase Workflow\n\n\nRemove a phase from the roadmap, with safety checks for in-progress or completed work.\n\n\n\n\n## 1. Validate Phase Exists\n\n**PowerShell:**\n```powershell\n$phase = Select-String -Path \".gsd/ROADMAP.md\" -Pattern \"### Phase $N:\"\nif (-not $phase) {\n Write-Error \"Phase $N not found in ROADMAP.md\"\n}\n```\n\n**Bash:**\n```bash\nif ! grep -q \"### Phase $N:\" \".gsd/ROADMAP.md\"; then\n echo \"Error: Phase $N not found in ROADMAP.md\" >&2\nfi\n```\n\n---\n\n## 2. Check Phase Status\n\n**PowerShell:**\n```powershell\n$status = Select-String -Path \".gsd/ROADMAP.md\" -Pattern \"Phase $N:.*\\n.*Status: (.*)\"\n```\n\n**Bash:**\n```bash\nstatus=$(grep -A1 \"Phase $N:\" \".gsd/ROADMAP.md\" | grep \"Status:\" | cut -d: -f2)\n```\n\n**Safety checks:**\n\n| Status | Action |\n|--------|--------|\n| ⬜ Not Started | Safe to remove |\n| 🔄 In Progress | Warn and confirm |\n| ✅ Complete | Error — archive instead |\n\n---\n\n## 3. Check for Dependencies\n\nAre other phases depending on this one?\n\n**PowerShell:**\n```powershell\nSelect-String -Path \".gsd/ROADMAP.md\" -Pattern \"Depends on.*Phase $N\"\n```\n\n**Bash:**\n```bash\ngrep \"Depends on.*Phase $N\" \".gsd/ROADMAP.md\"\n```\n\n**If dependencies exist:**\n```\n⚠️ Phase {M} depends on Phase {N}\n\nCannot remove. Consider:\n1. Update dependent phases first\n2. Use /insert-phase to restructure\n```\n\n---\n\n## 4. Confirm Removal\n\n```\n⚠️ CONFIRM REMOVAL\n\nPhase {N}: {name}\nStatus: {status}\n\nThis will:\n- Remove phase from ROADMAP.md\n- Delete .gsd/phases/{N}/ if exists\n- Renumber subsequent phases\n\nType \"REMOVE\" to confirm:\n```\n\n---\n\n## 5. Remove Phase\n\n1. Delete from ROADMAP.md\n2. Remove `.gsd/phases/{N}/` directory\n3. Renumber subsequent phases (N+1 becomes N, etc.)\n4. Update dependencies\n\n---\n\n## 6. Update STATE.md\n\nIf currently in removed phase, set to previous phase or \"Planning\".\n\n---\n\n## 7. Commit\n\n```bash\ngit add -A\ngit commit -m \"docs: remove phase {N} - {name}\"\n```\n\n---\n\n## 8. Display Result\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE REMOVED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nRemoved: Phase {N}: {name}\nRenumbered: {M} phases\n\n───────────────────────────────────────────────────────\n\n/progress — See updated roadmap\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/research-phase.md", "content": "---\ndescription: Deep technical research for a phase\nargument-hint: \" [--level 1|2|3]\"\n---\n\n# /research-phase Workflow\n\n\nConduct technical research to inform planning decisions for a phase.\n\n\n\n## Discovery Levels\n\n| Level | Time | Use When |\n|-------|------|----------|\n| 0 | 0 min | Already know, just doing it |\n| 1 | 2-5 min | Single library, confirming syntax |\n| 2 | 15-30 min | Choosing between options, new integration |\n| 3 | 1+ hour | Architectural decision, novel problem |\n\n**Default:** Level 2 unless specified.\n\n\n\n\n## 1. Load Phase Context\n\nRead:\n- Phase objective from ROADMAP.md\n- Relevant ARCHITECTURE.md sections\n- STACK.md for current technologies\n\n---\n\n## 2. Identify Research Questions\n\nWhat needs to be understood before planning?\n\n```markdown\n## Research Questions\n\n1. {Technical question 1}\n2. {Technical question 2}\n3. {Integration question}\n```\n\n---\n\n## 3. Conduct Research\n\nBased on discovery level:\n\n**Level 1:** Quick verification\n- Check official docs\n- Confirm API/syntax\n\n**Level 2:** Comparison research\n- Compare 2-3 options\n- Evaluate trade-offs\n- Make recommendation\n\n**Level 3:** Deep dive\n- Prototype if needed\n- Research edge cases\n- Document unknowns\n\n---\n\n## 4. Generate RESEARCH.md\n\nCreate `.gsd/phases/{N}/RESEARCH.md`:\n\n```markdown\n---\nphase: {N}\nlevel: {1|2|3}\nresearched_at: {date}\n---\n\n# Phase {N} Research\n\n## Questions Investigated\n1. {question}\n2. {question}\n\n## Findings\n\n### {Topic 1}\n{What was learned}\n\n**Sources:**\n- {URL}\n\n**Recommendation:** {what to do}\n\n### {Topic 2}\n...\n\n## Decisions Made\n| Decision | Choice | Rationale |\n|----------|--------|-----------|\n| {decision} | {choice} | {why} |\n\n## Patterns to Follow\n- {pattern 1}\n- {pattern 2}\n\n## Anti-Patterns to Avoid\n- {anti-pattern}: {why}\n\n## Dependencies Identified\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {pkg} | {ver} | {why} |\n\n## Risks\n- {risk}: {mitigation}\n\n## Ready for Planning\n- [x] Questions answered\n- [x] Approach selected\n- [x] Dependencies identified\n```\n\n---\n\n## 5. Commit Research\n\n```powershell\ngit add .gsd/phases/{N}/RESEARCH.md\ngit commit -m \"docs(phase-{N}): research complete\"\n```\n\n---\n\n## 6. Offer Next Steps\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► RESEARCH COMPLETE ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nPhase {N}: {name}\nLevel: {level}\n\nKey findings:\n• {finding 1}\n• {finding 2}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/plan {N} — Create plans informed by research\n\n───────────────────────────────────────────────────────\n```\n\n\n" }, { "path": ".agent/workflows/resume.md", "content": "---\ndescription: Restore context from previous session\n---\n\n# /resume Workflow\n\n\nStart a new session with full context from where we left off.\n\n\n\n\n## 1. Load Saved State\n\nRead `.gsd/STATE.md` completely.\n\n---\n\n## 2. Display Context\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► RESUMING SESSION\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nLAST POSITION\n─────────────\nPhase: {phase from STATE.md}\nTask: {task from STATE.md}\nStatus: {status when paused}\n\n───────────────────────────────────────────────────────\n\nCONTEXT FROM LAST SESSION\n─────────────────────────\n{Context dump content from STATE.md}\n\n───────────────────────────────────────────────────────\n\nBLOCKERS\n────────\n{Blockers from STATE.md, or \"None\"}\n\n───────────────────────────────────────────────────────\n\nNEXT STEPS (from last session)\n──────────────────────────────\n1. {First priority}\n2. {Second priority}\n3. {Third priority}\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 3. Load Recent Journal\n\nShow last entry from `.gsd/JOURNAL.md`:\n- What was accomplished\n- Handoff notes\n- Any issues encountered\n\n---\n\n## 4. Check for Conflicts\n\n```bash\n# Check for uncommitted changes\ngit status --porcelain\n```\n\n**If changes found:**\n```\n⚠️ UNCOMMITTED CHANGES DETECTED\n\n{list of modified files}\n\nThese may be from the previous session.\nReview before proceeding.\n```\n\n---\n\n## 5. Update State\n\nMark session as active in `.gsd/STATE.md`:\n```markdown\n**Status**: Active (resumed {timestamp})\n```\n\n---\n\n## 6. Suggest Action\n\n```\n───────────────────────────────────────────────────────\n\n▶ READY TO CONTINUE\n\nSuggested action based on state:\n\n{One of:}\n• /execute {N} — Continue phase execution\n• /verify {N} — Verify completed phase\n• /plan {N} — Create plans for phase\n• /progress — See full roadmap status\n\n───────────────────────────────────────────────────────\n\n💡 Fresh session = fresh perspective\n\nYou have all the context you need.\nThe previous struggles are documented.\nTime to solve this with fresh eyes.\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\nA resumed session has advantages:\n\n1. **No accumulated confusion** — You see the problem clearly\n2. **Documented failures** — You know what NOT to try\n3. **Hypothesis preserved** — Pick up where logic left off\n4. **Full context budget** — 200k tokens of fresh capacity\n\nOften the first thing a fresh context sees is the obvious solution that a tired context missed.\n\n" }, { "path": ".agent/workflows/sprint.md", "content": "---\ndescription: Create and manage a time-boxed sprint for quick focused work\nargument-hint: \"[new|status|close] [sprint-name]\"\n---\n\n# /sprint Workflow\n\n\nManage time-boxed sprints for quick, focused work outside the full milestone/phase cycle.\nSprints are ideal for bug fixes, small features, or exploratory work that doesn't warrant a full planning cycle.\n\n\n\n\n## 1. Parse Arguments\n\nExtract from $ARGUMENTS:\n- **Action**: `new` (default), `status`, or `close`\n- **Sprint name**: identifier for the sprint\n\n**If no arguments:** Default to `new` and ask for sprint details.\n\n---\n\n## 2a. Action: New Sprint\n\n### Gather Sprint Information\n\nAsk for:\n- **Name** — Sprint identifier (e.g., \"bugfix-auth\", \"spike-caching\")\n- **Goal** — One sentence describing the sprint goal\n- **Duration** — Timeframe (e.g., \"2 days\", \"1 week\")\n- **Scope** — Tasks included and explicitly excluded\n\n### Create Sprint File\n\nCreate `.gsd/SPRINT.md` using the template from `.gsd/templates/sprint.md`:\n\n```markdown\n# Sprint {N} — {Sprint Name}\n\n> **Duration**: {start-date} to {end-date}\n> **Status**: In Progress\n\n## Goal\n{One sentence goal}\n\n## Scope\n\n### Included\n- {Task 1}\n- {Task 2}\n\n### Explicitly Excluded\n- {Out of scope item}\n\n## Tasks\n\n| Task | Assignee | Status | Est. Hours |\n|------|----------|--------|------------|\n| {Task 1} | Claude | ⬜ Todo | — |\n| {Task 2} | Claude | ⬜ Todo | — |\n\n## Daily Log\n\n### {today's date}\n- Sprint created\n```\n\n### Update STATE.md\n\n```markdown\n## Current Position\n- **Sprint**: {name}\n- **Status**: Sprint in progress\n- **Milestone**: (paused if active)\n```\n\n### Commit\n\n```bash\ngit add .gsd/SPRINT.md .gsd/STATE.md\ngit commit -m \"docs: create sprint {name}\"\n```\n\n---\n\n## 2b. Action: Status\n\nRead `.gsd/SPRINT.md` and display:\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► SPRINT STATUS\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nSprint: {name}\nDuration: {start} to {end}\nTasks: {done}/{total} complete\n\n{task table}\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 2c. Action: Close\n\n### Verify Sprint Complete\n\nCheck all tasks are done or explicitly deferred.\n\n### Generate Retrospective\n\nAppend to `.gsd/SPRINT.md`:\n\n```markdown\n## Retrospective ({date})\n\n### What Went Well\n- {auto-extract from daily log}\n\n### What Could Improve\n- {identify blockers or friction}\n\n### Action Items\n- [ ] {carry-forward items}\n```\n\n### Archive Sprint\n\n**PowerShell:**\n```powershell\nNew-Item -ItemType Directory -Force \".gsd/sprints\"\nMove-Item \".gsd/SPRINT.md\" \".gsd/sprints/{name}-SPRINT.md\"\n```\n\n**Bash:**\n```bash\nmkdir -p .gsd/sprints\nmv .gsd/SPRINT.md \".gsd/sprints/{name}-SPRINT.md\"\n```\n\n### Update STATE.md\n\nRestore previous milestone position or mark as idle.\n\n### Commit\n\n```bash\ngit add .gsd/sprints/ .gsd/STATE.md\ngit commit -m \"docs: close sprint {name}\"\n```\n\n### Display Result\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► SPRINT CLOSED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nSprint: {name}\nTasks completed: {N}/{total}\n\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/resume — Return to milestone work\n/sprint new — Start another sprint\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/plan` | Full planning cycle (use for milestone work) |\n| `/execute` | Full execution cycle (use for milestone work) |\n| `/pause` | Pause current work for handoff |\n\n### Templates\n| Template | Purpose |\n|----------|---------|\n| `sprint.md` | Sprint document structure |\n\n" }, { "path": ".agent/workflows/update.md", "content": "---\ndescription: Update GSD to the latest version from GitHub\n---\n\n# /update Workflow\n\n\nUpdate GSD for Antigravity to the latest version from GitHub.\n\n\n\n\n## 1. Check Current Version\n\n**PowerShell:**\n```powershell\nif (Test-Path \"CHANGELOG.md\") {\n $version = Select-String -Path \"CHANGELOG.md\" -Pattern \"## \\[(\\d+\\.\\d+\\.\\d+)\\]\" | \n Select-Object -First 1\n Write-Output \"Current version: $($version.Matches.Groups[1].Value)\"\n}\n```\n\n**Bash:**\n```bash\nif [ -f \"CHANGELOG.md\" ]; then\n version=$(grep -oP '## \\[\\K[0-9]+\\.[0-9]+\\.[0-9]+' CHANGELOG.md | head -1)\n echo \"Current version: $version\"\nfi\n```\n\n---\n\n## 2. Fetch Latest from GitHub\n\n```bash\n# Clone latest to temp directory\ngit clone --depth 1 https://github.com/toonight/get-shit-done-for-antigravity.git .gsd-update-temp\n```\n\n---\n\n## 3. Compare Versions\n\n**PowerShell:**\n```powershell\n$remoteVersion = Select-String -Path \".gsd-update-temp/CHANGELOG.md\" -Pattern \"## \\[(\\d+\\.\\d+\\.\\d+)\\]\" | \n Select-Object -First 1\n\nWrite-Output \"Remote version: $($remoteVersion.Matches.Groups[1].Value)\"\n```\n\n**Bash:**\n```bash\nremote_version=$(grep -oP '## \\[\\K[0-9]+\\.[0-9]+\\.[0-9]+' .gsd-update-temp/CHANGELOG.md | head -1)\necho \"Remote version: $remote_version\"\n```\n\n**If same version:**\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► ALREADY UP TO DATE ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nVersion: {version}\n\nNo updates available.\n\n───────────────────────────────────────────────────────\n```\nExit after cleanup.\n\n---\n\n## 4. Show Changes\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► UPDATE AVAILABLE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nCurrent: {current-version}\nLatest: {remote-version}\n\nChanges:\n{Extract from CHANGELOG.md}\n\n───────────────────────────────────────────────────────\n\nUpdate now?\nA) Yes — Apply updates\nB) No — Cancel\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 5. Apply Updates\n\n**If user confirms:**\n\n**PowerShell:**\n```powershell\n# Backup current\nCopy-Item -Recurse \".agent\" \".agent.backup\"\nCopy-Item -Recurse \".agents\" \".agents.backup\"\nCopy-Item -Recurse \".gsd/templates\" \".gsd/templates.backup\"\n\n# Update workflows (preserve user's .gsd docs)\nCopy-Item -Recurse -Force \".gsd-update-temp/.agent/*\" \".agent/\"\n\n# Update skills (Agent Skills standard)\nCopy-Item -Recurse -Force \".gsd-update-temp/.agents/*\" \".agents/\"\n\n# Update templates only\nCopy-Item -Recurse -Force \".gsd-update-temp/.gsd/templates/*\" \".gsd/templates/\"\n\n# Update root files\nCopy-Item -Force \".gsd-update-temp/GSD-STYLE.md\" \"./\"\nCopy-Item -Force \".gsd-update-temp/CHANGELOG.md\" \"./\"\nCopy-Item -Force \".gsd-update-temp/PROJECT_RULES.md\" \"./\"\nCopy-Item -Force \".gsd-update-temp/VERSION\" \"./\"\n```\n\n**Bash:**\n```bash\n# Backup current\ncp -r .agent .agent.backup\ncp -r .agents .agents.backup\ncp -r .gsd/templates .gsd/templates.backup\n\n# Update workflows (preserve user's .gsd docs)\ncp -r .gsd-update-temp/.agent/* .agent/\n\n# Update skills (Agent Skills standard)\ncp -r .gsd-update-temp/.agents/* .agents/\n\n# Update templates only\ncp -r .gsd-update-temp/.gsd/templates/* .gsd/templates/\n\n# Update root files\ncp .gsd-update-temp/GSD-STYLE.md ./\ncp .gsd-update-temp/CHANGELOG.md ./\ncp .gsd-update-temp/PROJECT_RULES.md ./\ncp .gsd-update-temp/VERSION ./\n```\n\n---\n\n## 6. Cleanup\n\n**PowerShell:**\n```powershell\nRemove-Item -Recurse -Force \".gsd-update-temp\"\nRemove-Item -Recurse -Force \".agent.backup\"\nRemove-Item -Recurse -Force \".agents.backup\"\nRemove-Item -Recurse -Force \".gsd/templates.backup\"\n```\n\n**Bash:**\n```bash\nrm -rf .gsd-update-temp\nrm -rf .agent.backup\nrm -rf .agents.backup\nrm -rf .gsd/templates.backup\n```\n\n---\n\n## 7. Confirm\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► UPDATED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nUpdated to version {remote-version}\n\n───────────────────────────────────────────────────────\n\n/whats-new — See what changed\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\nThese user files are NEVER overwritten:\n- .gsd/SPEC.md\n- .gsd/ROADMAP.md\n- .gsd/STATE.md\n- .gsd/ARCHITECTURE.md\n- .gsd/STACK.md\n- .gsd/DECISIONS.md\n- .gsd/JOURNAL.md\n- .gsd/TODO.md\n- .gsd/phases/*\n- .gemini/GEMINI.md\n\n" }, { "path": ".agent/workflows/verify.md", "content": "---\ndescription: The Auditor — Validate work against spec with empirical evidence\nargument-hint: \"\"\n---\n\n# /verify Workflow\n\n\nYou are a GSD verifier. You validate implemented work against spec requirements using empirical evidence.\n\n**Core principle:** No \"trust me, it works.\" Every verification produces proof.\n\n**Core responsibilities:**\n- Extract testable deliverables from phase\n- Walk through each requirement\n- Collect empirical evidence (commands, screenshots)\n- Create verification report\n- Generate fix plans if issues found\n\n\n\nConfirm that implemented work meets spec requirements with documented proof.\n\nThe verifier checks the CODEBASE, not SUMMARY claims.\n\n\n\n**Phase:** $ARGUMENTS (required — phase number to verify)\n\n**Required files:**\n- `.gsd/SPEC.md` — Original requirements\n- `.gsd/ROADMAP.md` — Phase definition with must-haves\n- `.gsd/phases/{phase}/*-SUMMARY.md` — What was implemented\n\n\n\n\n## 1. Load Verification Context\n\nRead:\n- Phase definition from `.gsd/ROADMAP.md`\n- Original requirements from `.gsd/SPEC.md`\n- All SUMMARY.md files from `.gsd/phases/{phase}/`\n\n---\n\n## 2. Extract Must-Haves\n\nFrom the phase definition, identify **must-haves** — requirements that MUST be true for the phase to be complete.\n\n```markdown\n### Must-Haves for Phase {N}\n1. {Requirement 1} — How to verify\n2. {Requirement 2} — How to verify\n3. {Requirement 3} — How to verify\n```\n\n---\n\n## 3. Verify Each Must-Have\n\nFor each must-have:\n\n### 3a. Determine Verification Method\n\n| Type | Method | Evidence |\n|------|--------|----------|\n| API/Backend | Run curl or test command | Command output |\n| UI | Use browser tool | Screenshot |\n| Build | Run build command | Success output |\n| Tests | Run test suite | Test results |\n| File exists | Check filesystem | File listing |\n| Code behavior | Run specific scenario | Output |\n\n### 3b. Execute Verification\n\nRun the verification command/action.\n\n// turbo\n```bash\n# Example: Run tests\nnpm test\n```\n\n### 3c. Record Evidence\n\nFor each must-have, record:\n- **Status:** PASS / FAIL\n- **Evidence:** Command output, screenshot path, etc.\n- **Notes:** Any observations\n\n---\n\n## 4. Create Verification Report\n\nWrite `.gsd/phases/{phase}/VERIFICATION.md`:\n\n```markdown\n---\nphase: {N}\nverified_at: {timestamp}\nverdict: PASS | FAIL | PARTIAL\n---\n\n# Phase {N} Verification Report\n\n## Summary\n{X}/{Y} must-haves verified\n\n## Must-Haves\n\n### ✅ {Must-have 1}\n**Status:** PASS\n**Evidence:** \n```\n{command output or description}\n```\n\n### ❌ {Must-have 2}\n**Status:** FAIL\n**Reason:** {why it failed}\n**Expected:** {what should happen}\n**Actual:** {what happened}\n\n## Verdict\n{PASS | FAIL | PARTIAL}\n\n## Gap Closure Required\n{If FAIL, list what needs to be fixed}\n```\n\n---\n\n## 5. Handle Results\n\n### If PASS (all must-haves verified):\n\nUpdate `.gsd/STATE.md`:\n```markdown\n## Current Position\n- **Phase**: {N} (verified)\n- **Status**: ✅ Complete and verified\n```\n\nOutput:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE {N} VERIFIED ✓\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{X}/{X} must-haves verified\n\nAll requirements satisfied.\n\n───────────────────────────────────────────────────────\n\n▶ Next Up\n\n/execute {N+1} — proceed to next phase\n\n───────────────────────────────────────────────────────\n```\n\n### If FAIL (some must-haves failed):\n\n**Create gap closure plans:**\n\nFor each failed must-have, create a fix plan in `.gsd/phases/{phase}/`:\n\n```markdown\n---\nphase: {N}\nplan: fix-{issue}\nwave: 1\ngap_closure: true\n---\n\n# Fix Plan: {Issue Name}\n\n## Problem\n{What failed and why}\n\n## Tasks\n\n\n Fix {issue}\n {files to modify}\n {specific fix instructions}\n {how to verify the fix}\n {acceptance criteria}\n\n```\n\nOutput:\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► PHASE {N} GAPS FOUND ⚠\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n{X}/{Y} must-haves verified\n{Z} issues require fixes\n\nGap closure plans created.\n\n───────────────────────────────────────────────────────\n\n▶ Next Up\n\n/execute {N} --gaps-only — run fix plans\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 6. Commit Verification\n\n```bash\ngit add .gsd/phases/{phase}/VERIFICATION.md\ngit commit -m \"docs(phase-{N}): verification report\"\n```\n\n\n\n\n\n## Forbidden Phrases\n\nNever accept these as verification:\n- \"This should work\"\n- \"The code looks correct\"\n- \"I've made similar changes before\"\n- \"Based on my understanding\"\n- \"It follows the pattern\"\n\n## Required Evidence\n\n| Claim | Required Proof |\n|-------|----------------|\n| \"Tests pass\" | Actual test output |\n| \"API works\" | Curl command + response |\n| \"UI renders\" | Screenshot |\n| \"Build succeeds\" | Build output |\n| \"File created\" | `ls` or `dir` output |\n\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/execute` | Run before /verify to implement work |\n| `/execute --gaps-only` | Fix issues found by /verify |\n| `/debug` | Diagnose verification failures |\n\n### Skills\n| Skill | Purpose |\n|-------|---------|\n| `verifier` | Detailed verification methodology |\n| `empirical-validation` | Evidence requirements |\n\n" }, { "path": ".agent/workflows/web-search.md", "content": "---\ndescription: Search the web for information to inform decisions\nargument-hint: \" [--domain ]\"\n---\n\n# /web-search Workflow\n\n\nSearch the web to gather information for technical decisions, API documentation, library comparisons, or any research need.\n\n\n\n- Evaluating libraries or frameworks\n- Finding API documentation\n- Checking current best practices\n- Researching error messages\n- Comparing implementation approaches\n- Getting up-to-date information on tools/services\n\n\n\n\n## 1. Formulate Query\n\nParse the user's request into a focused search query.\n\n**Good queries:**\n- Specific: \"Next.js 14 app router authentication best practices\"\n- Targeted: \"Prisma vs Drizzle ORM comparison 2024\"\n- Actionable: \"how to fix CORS error Express.js\"\n\n**Bad queries:**\n- Too broad: \"how to code\"\n- Too vague: \"best database\"\n\n---\n\n## 2. Execute Search\n\nUse the `search_web` tool with:\n- Query: The formulated search query\n- Domain (optional): Prioritize specific site (e.g., `docs.python.org`)\n\n---\n\n## 3. Analyze Results\n\nFrom the search results:\n1. **Extract key information** relevant to the user's need\n2. **Note sources** for citations\n3. **Identify patterns** across multiple results\n4. **Flag contradictions** or outdated information\n\n---\n\n## 4. Summarize Findings\n\nPresent findings clearly:\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► WEB SEARCH RESULTS\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nQuery: {query}\n\n───────────────────────────────────────────────────────\n\nKEY FINDINGS\n────────────\n• {finding 1}\n• {finding 2}\n• {finding 3}\n\nRECOMMENDATION\n──────────────\n{actionable recommendation based on findings}\n\nSOURCES\n───────\n• {source 1}\n• {source 2}\n\n───────────────────────────────────────────────────────\n```\n\n---\n\n## 5. Offer Next Steps\n\nBased on findings:\n- Suggest follow-up searches if needed\n- Recommend adding to RESEARCH.md for project context\n- Offer to implement based on findings\n\n\n\n\n## Integration with GSD\n\n**During /research-phase:**\nUse `/web-search` to gather information for RESEARCH.md.\n\n**During /plan:**\nUse `/web-search` when discovery level 1-3 indicates research needed.\n\n**During /debug:**\nUse `/web-search` to find solutions to error messages.\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/research-phase` | Uses web-search for phase research |\n| `/plan` | May trigger web-search for discovery |\n| `/debug` | Search for error solutions |\n\n\n" }, { "path": ".agent/workflows/whats-new.md", "content": "---\ndescription: Show recent GSD changes and new features\n---\n\n# /whats-new Workflow\n\n\nDisplay recent changes, new features, and improvements to GSD for Antigravity.\n\n\n\n\n## 1. Read CHANGELOG.md\n\n```bash\n# Read the latest version section from CHANGELOG.md\nhead -50 CHANGELOG.md\n```\n\n## 2. Display Recent Changes\n\nDisplay the latest version(s) from CHANGELOG.md:\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► WHAT'S NEW\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nVERSION 1.2.0 — 2026-01-17\n══════════════════════════\n\n🌍 CROSS-PLATFORM SUPPORT\n\n• All 16 workflow files now have Bash equivalents\n• README with dual-syntax Getting Started\n• /web-search workflow for research\n\n───────────────────────────────────────────────────────\n\nVERSION 1.1.0 — 2026-01-17\n══════════════════════════\n\n📚 TEMPLATE PARITY & EXAMPLES\n\n• 14 new templates (DEBUG.md, UAT.md, etc.)\n• Examples directory with walkthroughs\n• /add-todo and /check-todos workflows\n• Cross-references between workflows\n\n───────────────────────────────────────────────────────\n\nVERSION 1.0.0 — 2026-01-17\n══════════════════════════\n\n🎉 INITIAL RELEASE\n\nFull port of GSD methodology to Google Antigravity.\n• 24 workflows, 8 skills, 14 templates\n• 4 core rules: Planning Lock, State Persistence,\n Context Hygiene, Empirical Validation\n\n───────────────────────────────────────────────────────\n\n📚 Full changelog: CHANGELOG.md\n\n───────────────────────────────────────────────────────\n```\n\n\n\n\n## Related\n\n### Workflows\n| Command | Relationship |\n|---------|--------------|\n| `/update` | Update GSD to latest version |\n| `/help` | List all commands |\n\n\n" }, { "path": ".agents/skills/codebase-mapper/SKILL.md", "content": "---\nname: codebase-mapper\ndescription: Analyzes existing codebases to understand structure, patterns, and technical debt\n---\n\n# GSD Codebase Mapper Agent\n\n\nYou are a GSD codebase mapper. You analyze existing codebases to produce documentation that enables informed planning.\n\n**Core responsibilities:**\n- Scan and understand project structure\n- Identify patterns and conventions\n- Map dependencies and integrations\n- Surface technical debt\n- Produce ARCHITECTURE.md and STACK.md\n\n\n## Analysis Domains\n\n### 1. Structure Analysis\nUnderstand how the project is organized:\n- Source directories and their purposes\n- Entry points (main files, index files)\n- Test locations and patterns\n- Configuration locations\n- Asset directories\n\n### 2. Dependency Analysis\nMap what the project depends on:\n- Runtime dependencies (production)\n- Development dependencies\n- Peer dependencies\n- Outdated packages\n- Security vulnerabilities\n\n### 3. Pattern Analysis\nIdentify how code is written:\n- Naming conventions\n- File organization patterns\n- Error handling approaches\n- State management patterns\n- API patterns\n\n### 4. Integration Analysis\nMap external connections:\n- APIs consumed\n- Databases used\n- Third-party services\n- Environment dependencies\n\n### 5. Technical Debt Analysis\nSurface issues to address:\n- TODOs and FIXMEs\n- Deprecated code\n- Missing tests\n- Inconsistent patterns\n- Known vulnerabilities\n\n---\n\n## Scanning Process\n\n### Phase 1: Project Type Detection\n\nIdentify project type from markers:\n```powershell\n# Node.js/JavaScript\nTest-Path \"package.json\"\n\n# Python\nTest-Path \"requirements.txt\" -or Test-Path \"pyproject.toml\"\n\n# Rust\nTest-Path \"Cargo.toml\"\n\n# Go\nTest-Path \"go.mod\"\n\n# .NET\nGet-ChildItem \"*.csproj\"\n```\n\n### Phase 2: Structure Scan\n\n```powershell\n# Get directory structure\nGet-ChildItem -Recurse -Directory | \n Where-Object { $_.Name -notmatch \"node_modules|\\.git|__pycache__|dist|build|\\.next\" } |\n Select-Object FullName\n```\n\n### Phase 3: Dependency Extraction\n\nFor each ecosystem:\n\n**Node.js:**\n```powershell\n$pkg = Get-Content \"package.json\" | ConvertFrom-Json\n$pkg.dependencies\n$pkg.devDependencies\n```\n\n**Python:**\n```powershell\nGet-Content \"requirements.txt\"\n```\n\n### Phase 4: Pattern Discovery\n\nSearch for common patterns:\n```powershell\n# Components\nGet-ChildItem -Recurse -Include \"*.tsx\",\"*.jsx\" | Select-Object Name\n\n# API routes\nGet-ChildItem -Recurse -Path \"**/api/**\" -Include \"*.ts\",\"*.js\"\n\n# Models/schemas\nSelect-String -Path \"**/*.ts\" -Pattern \"interface|type|schema\"\n```\n\n### Phase 5: Debt Discovery\n\n```powershell\n# TODOs\nSelect-String -Path \"src/**/*\" -Pattern \"TODO|FIXME|HACK|XXX\"\n\n# Deprecated\nSelect-String -Path \"**/*\" -Pattern \"@deprecated|DEPRECATED\"\n\n# Console statements (often debug leftovers)\nSelect-String -Path \"src/**/*\" -Pattern \"console\\.(log|debug|warn)\"\n```\n\n---\n\n## Output Format\n\n### ARCHITECTURE.md\n\n```markdown\n# Architecture\n\n> Generated by /map on {date}\n\n## Overview\n{High-level system description}\n\n## System Diagram\n```\n{ASCII or description of component relationships}\n```\n\n## Components\n\n### {Component Name}\n- **Purpose:** {what it does}\n- **Location:** `{path}`\n- **Dependencies:** {what it imports}\n- **Dependents:** {what imports it}\n\n## Data Flow\n{How data moves through the system}\n\n## Integration Points\n| External Service | Type | Purpose |\n|------------------|------|---------|\n| {service} | {API/DB/etc} | {purpose} |\n\n## Conventions\n- **Naming:** {patterns}\n- **Structure:** {organization}\n- **Testing:** {approach}\n\n## Technical Debt\n- [ ] {Debt item with location}\n```\n\n### STACK.md\n\n```markdown\n# Technology Stack\n\n> Generated by /map on {date}\n\n## Runtime\n| Technology | Version | Purpose |\n|------------|---------|---------|\n| {tech} | {version} | {purpose} |\n\n## Production Dependencies\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {pkg} | {version} | {purpose} |\n\n## Development Dependencies\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {pkg} | {version} | {purpose} |\n\n## Infrastructure\n| Service | Provider | Purpose |\n|---------|----------|---------|\n| {svc} | {provider} | {purpose} |\n\n## Configuration\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| {var} | {purpose} | {yes/no} |\n```\n\n---\n\n## Checklist\n\nBefore Completing Map:\n- [ ] Project type identified\n- [ ] All source directories documented\n- [ ] Entry points found\n- [ ] Dependencies extracted and categorized\n- [ ] Key patterns identified\n- [ ] Integrations mapped\n- [ ] Technical debt surfaced\n- [ ] ARCHITECTURE.md created\n- [ ] STACK.md created\n" }, { "path": ".agents/skills/context-compressor/SKILL.md", "content": "---\nname: context-compressor\ndescription: Strategies for compressing context to maximize token efficiency\n---\n\n# Context Compressor Skill\n\n\nYou are a context compression specialist. Your job is to maintain rich understanding while using minimal tokens.\n\n**Core principle:** Compress aggressively, decompress only when needed.\n\n\n---\n\n## Compression Strategies\n\n### Strategy 1: Summary Mode\n\n**When:** You've fully understood a file and may need to reference it later.\n\n**How:**\n```markdown\n## File Summary: src/auth/login.ts\n\n**Purpose:** Handles user login via email/password\n**Key functions:**\n- handleLogin(req, res) → Validates credentials, returns JWT\n- validateCredentials(email, password) → Checks against DB\n**Dependencies:** bcrypt, jose, database\n**Tokens saved:** ~400 (95 lines not reloaded)\n```\n\n**Use instead of:** Re-reading the full file\n\n---\n\n### Strategy 2: Outline Mode\n\n**When:** You need to understand a file's structure but not implementation details.\n\n**How:**\n```markdown\n## Outline: src/services/payment.ts (127 lines)\n\n- L1-15: Imports and types\n- L17-35: PaymentService class\n - L20: constructor(config)\n - L25: processPayment(amount, method)\n - L45: refund(transactionId)\n - L67: getHistory(userId)\n- L90-127: Helper functions\n```\n\n**Tokens:** ~50 vs ~500 for full file\n\n---\n\n### Strategy 3: Diff-Only Mode\n\n**When:** You've already seen a file and need to understand changes.\n\n**How:**\n```markdown\n## Changes to: src/config.ts\n\nAdded:\n- L45: TOKEN_BUDGET_THRESHOLD = 0.5\n- L46: COMPRESSION_ENABLED = true\n\nModified:\n- L12: MAX_CONTEXT → increased from 100000 to 150000\n```\n\n**Use for:** Reviewing modifications, understanding updates\n\n---\n\n### Strategy 4: Reference Mode\n\n**When:** You need to track a file without loading it.\n\n**How:**\n```markdown\n## References\n\n| File | Last Seen | Summary | Load If |\n|------|-----------|---------|---------|\n| auth.ts | Task 2 | Login handling | Auth bugs |\n| db.ts | Task 1 | Postgres client | DB errors |\n| utils.ts | Never | Utility funcs | Helper needed |\n```\n\n**Cost:** ~10 tokens vs ~200+ per file\n\n---\n\n### Strategy 5: Progressive Disclosure\n\n**When:** Unsure how much detail is needed.\n\n**Process:**\n1. Start with outline (Level 1)\n2. If insufficient, load key functions (Level 2)\n3. If still stuck, load related code (Level 3)\n4. Full file only as last resort (Level 4)\n\n```\nL1: Outline → \"I see handleLogin at L25\"\nL2: Function → \"handleLogin validates then calls createToken\"\nL3: Related → \"createToken uses jose.sign with HS256\"\nL4: Full → Only for complex debugging\n```\n\n---\n\n## Compression Triggers\n\n### Automatic Compression Points\n\n| Trigger | Action |\n|---------|--------|\n| After understanding a file | Create summary |\n| Switching tasks | Compress previous context |\n| Budget at 50% | Aggressive outline mode |\n| Budget at 70% | Summary-only mode |\n| End of wave | Full compression pass |\n\n---\n\n## Decompression Protocol\n\nWhen you need details from compressed context:\n\n1. **Check summary first** — Often sufficient\n2. **Load specific section** — If summary incomplete\n3. **Full load as last resort** — And re-compress after\n\n```markdown\n## Decompression Log\n\n| File | Reason | Level | Tokens |\n|------|--------|-------|--------|\n| auth.ts | Debug login | L2 (func) | +150 |\n| db.ts | Check query | L3 (snippet) | +50 |\n```\n\n---\n\n## Compression Format Templates\n\n### Summary Template\n\n```markdown\n## 📦 [filename]\n**Purpose:** [one line]\n**Key exports:** [list]\n**Dependencies:** [list]\n**Patterns:** [notable patterns used]\n**Watch for:** [gotchas or edge cases]\n```\n\n### Outline Template\n\n```markdown\n## 📋 [filename] (N lines)\n- L[start]-[end]: [section name]\n - L[n]: [key item]\n - L[n]: [key item]\n```\n\n### Diff Template\n\n```markdown\n## Δ [filename]\n**+** [additions]\n**-** [removals]\n**~** [modifications]\n```\n\n---\n\n## Integration\n\nWorks with:\n- `token-budget` — Triggers compression at thresholds\n- `context-fetch` — Provides input for compression\n- `context-health-monitor` — Monitors compression effectiveness\n\n---\n\n## Anti-Patterns\n\n❌ **Keeping full files in mental context** — Compress after understanding\n❌ **Re-reading instead of referencing** — Use summaries\n❌ **Loading full file for one function** — Use outline + target\n❌ **Skipping compression \"to save time\"** — Costs more later\n\n---\n\n*Part of GSD v1.6 Token Optimization. See docs/token-optimization-guide.md for examples.*\n" }, { "path": ".agents/skills/context-fetch/SKILL.md", "content": "---\nname: context-fetch\ndescription: Search-first skill to reduce unnecessary file reads by searching before loading\n---\n\n# Context Fetch Skill\n\n\nYou are a context-efficient agent. Your job is to find relevant code with minimal file reads.\n\n**Core principle:** Search first, read targeted sections, never load full files blindly.\n\n\n---\n\n## When to Use\n\nActivate this skill **before**:\n- Starting any coding task\n- Beginning a refactor\n- Investigating a bug\n- Understanding unfamiliar code\n\n---\n\n## Process\n\n### Step 1: Define the Question\n\nWhat are you trying to find or understand?\n\nExamples:\n- \"Where is the login endpoint defined?\"\n- \"How does the caching layer work?\"\n- \"What calls the `processPayment` function?\"\n\n### Step 2: Identify Keywords\n\nExtract searchable terms:\n\n| Question | Keywords |\n|----------|----------|\n| Login endpoint | `login`, `auth`, `POST.*login` |\n| Caching layer | `cache`, `redis`, `memoize` |\n| Payment calls | `processPayment`, `payment` |\n\n### Step 3: Search Before Reading\n\n**PowerShell:**\n```powershell\n# Simple pattern search\nSelect-String -Path \"src/**/*.ts\" -Pattern \"login\" -Recurse\n\n# With ripgrep (if available)\nrg \"login\" --type ts\n```\n\n**Bash:**\n```bash\n# With ripgrep (recommended)\nrg \"login\" --type ts\n\n# With grep\ngrep -r \"login\" src/ --include=\"*.ts\"\n```\n\n### Step 4: Evaluate Results\n\nFrom search results, identify:\n\n1. **Primary candidates** — Files directly matching your question\n2. **Secondary candidates** — Files that reference primary candidates\n3. **Ignore list** — Files with keyword but unrelated context\n\n### Step 5: Targeted Reading\n\nOnly read what's justified:\n\n```powershell\n# Read specific line range (PowerShell)\nGet-Content \"src/auth/login.ts\" | Select-Object -Skip 49 -First 30\n\n# Read specific function (with view_code_item tool)\n# view_code_item: src/auth/login.ts -> handleLogin\n```\n\n---\n\n## Inputs\n\nWhen invoking this skill, provide:\n\n| Input | Description | Example |\n|-------|-------------|---------|\n| **Question** | What you're trying to find | \"Where is user validation?\" |\n| **Scope** | Directory or file pattern | `src/`, `*.service.ts` |\n| **Keywords** | Terms to search for | `validate`, `user`, `schema` |\n\n---\n\n## Outputs\n\nAfter executing this skill, report:\n\n1. **Candidate files** — Ranked by relevance\n2. **Relevant extracts** — Key snippets found\n3. **Next reads** — Specific files/line-ranges to read next\n4. **Skip list** — Files searched but not relevant\n\n---\n\n## Anti-Patterns\n\n### ❌ Loading Everything First\n\n```\n# BAD: Reading 5 full files to \"understand context\"\nRead: src/auth/login.ts (500 lines)\nRead: src/auth/register.ts (400 lines)\nRead: src/auth/types.ts (200 lines)\n```\n\n### ✅ Search Then Target\n\n```\n# GOOD: Search first, read only what's needed\nSearch: \"validatePassword\" in src/auth/\nFound: login.ts:45, register.ts:78\nRead: login.ts lines 40-60\n```\n\n### ❌ Broad Searches\n\n```\n# BAD: Searching for common terms\nSearch: \"function\" → 10,000 results\n```\n\n### ✅ Specific Searches\n\n```\n# GOOD: Searching for specific identifiers\nSearch: \"validateUserCredentials\" → 3 results\n```\n\n---\n\n## Context Efficiency Metrics\n\nTrack your efficiency:\n\n| Metric | Good | Poor |\n|--------|------|------|\n| Files searched | 10+ | <5 |\n| Files fully read | <3 | 10+ |\n| Lines read | <200 | 1000+ |\n| Targeted sections | Yes | No |\n\n---\n\n## Integration with GSD\n\nThis skill supports GSD's context management:\n\n- **Prevents context pollution** — Less irrelevant code loaded\n- **Supports wave execution** — Each wave starts with minimal context\n- **Enables model switching** — Less context = easier handoff\n\n---\n\n## Quick Reference\n\n```\n1. Define question → What am I looking for?\n2. Extract keywords → What terms to search?\n3. Search codebase → rg/grep/Select-String\n4. Evaluate results → Which files matter?\n5. Read targeted → Specific lines only\n6. Report findings → Candidates + extracts\n```\n\n---\n\n*Part of GSD methodology. See PROJECT_RULES.md for search-first discipline rules.*\n" }, { "path": ".agents/skills/context-health-monitor/SKILL.md", "content": "---\nname: context-health-monitor\ndescription: Monitors context complexity and triggers state dumps before quality degrades\n---\n\n# Context Health Monitor\n\n## Purpose\n\nPrevent \"Context Rot\" — the quality degradation that occurs as the agent processes more information in a single session.\n\n## When This Skill Activates\n\nThe agent should self-monitor for these warning signs:\n\n### Warning Signs\n\n| Signal | Threshold | Action |\n|--------|-----------|--------|\n| Repeated debugging | 3+ failed attempts | Trigger state dump |\n| Going in circles | Same approach tried twice | Stop and reassess |\n| Confusion indicators | \"I'm not sure\", backtracking | Document uncertainty |\n| Session length | Extended back-and-forth | Recommend `/pause` |\n\n## Behavior Rules\n\n### Rule 1: The 3-Strike Rule\n\nIf debugging the same issue fails 3 times:\n\n1. **STOP** attempting fixes\n2. **Document** in `.gsd/STATE.md`:\n - What was tried\n - What errors occurred\n - Current hypothesis\n3. **Recommend** user start fresh session\n4. **Do NOT** continue with more attempts\n\n### Rule 2: Circular Detection\n\nIf the same approach is being tried again:\n\n1. **Acknowledge** the repetition\n2. **List** what has already been tried\n3. **Propose** a fundamentally different approach\n4. **Or** recommend `/pause` for fresh perspective\n\n### Rule 3: Uncertainty Logging\n\nWhen uncertain about an approach:\n\n1. **State** the uncertainty clearly\n2. **Document** in `.gsd/DECISIONS.md`:\n - The uncertain decision\n - Why it's uncertain\n - Alternatives considered\n3. **Ask** user for guidance rather than guessing\n\n## State Dump Format\n\nWhen triggered, write to `.gsd/STATE.md`:\n\n```markdown\n## Context Health: State Dump\n\n**Triggered**: [date/time]\n**Reason**: [3 failures / circular / uncertainty]\n\n### What Was Attempted\n1. [Approach 1] — Result: [outcome]\n2. [Approach 2] — Result: [outcome]\n3. [Approach 3] — Result: [outcome]\n\n### Current Hypothesis\n[Best guess at root cause]\n\n### Recommended Next Steps\n1. [Fresh perspective action]\n2. [Alternative approach to try]\n\n### Files Involved\n- [file1.ext] — [what state it's in]\n- [file2.ext] — [what state it's in]\n```\n\n## Auto-Save Protocol\n\n**Critical:** When any warning signal triggers, the agent must save state BEFORE recommending `/pause` to the user. This ensures state persists even if the session hard-terminates.\n\n### Steps\n\n1. **Write** a state snapshot to `.gsd/STATE.md` immediately when a threshold is hit\n2. **Include** at minimum: current phase, current task, last action, next step\n3. **Then** inform the user of the situation and recommend `/pause`\n\n### Why\n\nSessions can terminate abruptly (usage limits, context limits, network errors). If the agent waits for the user to type `/pause`, it may never get the chance. By saving first and recommending second, state is always preserved.\n\n## Integration\n\nThis skill integrates with:\n- `/pause` — Triggers proper session handoff (includes proactive auto-save)\n- `/resume` — Loads the state dump context\n- Rule 3 in `GEMINI.md` — Context Hygiene enforcement\n" }, { "path": ".agents/skills/debugger/SKILL.md", "content": "---\nname: debugger\ndescription: Systematic debugging with persistent state and fresh context advantages\n---\n\n# GSD Debugger Agent\n\n\nYou are a GSD debugger. You systematically diagnose bugs using hypothesis testing, evidence gathering, and persistent state tracking.\n\nYour job: Find the root cause, not just make symptoms disappear.\n\n\n---\n\n## Core Philosophy\n\n### User = Reporter, AI = Investigator\n\n**User knows:**\n- What they expected to happen\n- What actually happened\n- Error messages they saw\n- When it started / if it ever worked\n\n**User does NOT know (don't ask):**\n- What's causing the bug\n- Which file has the problem\n- What the fix should be\n\nAsk about experience. Investigate the cause yourself.\n\n### Meta-Debugging: Your Own Code\n\nWhen debugging code you wrote, you're fighting your own mental model.\n\n**Why this is harder:**\n- You made the design decisions — they feel obviously correct\n- You remember intent, not what you actually implemented\n- Familiarity breeds blindness to bugs\n\n**The discipline:**\n1. **Treat your code as foreign** — Read it as if someone else wrote it\n2. **Question your design decisions** — Your implementations are hypotheses\n3. **Admit your mental model might be wrong** — Code behavior is truth\n4. **Prioritize code you touched** — If you modified 100 lines and something breaks, those are prime suspects\n\n---\n\n## Foundation Principles\n\n- **What do you know for certain?** Observable facts, not assumptions\n- **What are you assuming?** \"This library should work this way\" — verified?\n- **Strip away everything you think you know.** Build understanding from facts.\n\n---\n\n## Cognitive Biases to Avoid\n\n| Bias | Trap | Antidote |\n|------|------|----------|\n| **Confirmation** | Only look for supporting evidence | Actively seek disconfirming evidence |\n| **Anchoring** | First explanation becomes anchor | Generate 3+ hypotheses before investigating |\n| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel |\n| **Sunk Cost** | Spent 2 hours, keep going | Every 30 min: \"Would I still take this path?\" |\n\n---\n\n## Systematic Investigation\n\n**Change one variable:** Make one change, test, observe, document, repeat.\n\n**Complete reading:** Read entire functions, not just \"relevant\" lines.\n\n**Embrace not knowing:** \"I don't know\" = good (now you can investigate). \"It must be X\" = dangerous.\n\n---\n\n## When to Restart\n\nConsider starting over when:\n1. **2+ hours with no progress** — Tunnel-visioned\n2. **3+ \"fixes\" that didn't work** — Mental model is wrong\n3. **You can't explain current behavior** — Don't add changes on top\n4. **You're debugging the debugger** — Something fundamental is wrong\n5. **Fix works but you don't know why** — This is luck, not a fix\n\n**Restart protocol:**\n1. Close all files and terminals\n2. Write down what you know for certain\n3. Write down what you've ruled out\n4. List new hypotheses (different from before)\n5. Begin again from Phase 1\n\n---\n\n## Hypothesis Testing\n\n### Falsifiability Requirement\n\nA good hypothesis can be proven wrong.\n\n**Bad (unfalsifiable):**\n- \"Something is wrong with the state\"\n- \"The timing is off\"\n\n**Good (falsifiable):**\n- \"User state is reset because component remounts on route change\"\n- \"API call completes after unmount, causing state update on unmounted component\"\n\n### Forming Hypotheses\n\n1. **Observe precisely:** Not \"it's broken\" but \"counter shows 3 when clicking once\"\n2. **Ask \"What could cause this?\"** — List every possible cause\n3. **Make each specific:** Not \"state is wrong\" but \"state updates twice because handleClick fires twice\"\n4. **Identify evidence:** What would support/refute each hypothesis?\n\n---\n\n## Debugging Techniques\n\n### Rubber Duck Debugging\n**When:** Stuck, confused, mental model doesn't match reality.\n\nWrite or say:\n1. \"The system should do X\"\n2. \"Instead it does Y\"\n3. \"I think this is because Z\"\n4. \"The code path is: A → B → C → D\"\n5. \"I've verified that...\" (list what you tested)\n6. \"I'm assuming that...\" (list assumptions)\n\nOften you'll spot the bug mid-explanation.\n\n### Minimal Reproduction\n**When:** Complex system, many moving parts.\n\n1. Copy failing code to new file\n2. Remove one piece\n3. Test: Does it still reproduce? YES = keep removed. NO = put back.\n4. Repeat until bare minimum\n5. Bug is now obvious in stripped-down code\n\n### Working Backwards\n**When:** You know correct output, don't know why you're not getting it.\n\n1. Define desired output precisely\n2. What function produces this output?\n3. Test that function with expected input — correct output?\n - YES: Bug is earlier (wrong input)\n - NO: Bug is here\n4. Repeat backwards through call stack\n\n### Differential Debugging\n**When:** Something used to work and now doesn't.\n\n**Time-based:** What changed in code? Environment? Data? Config?\n\n**Environment-based:** Config values? Env vars? Network? Data volume?\n\n### Binary Search / Divide and Conquer\n**When:** Bug somewhere in a large codebase or long history.\n\n1. Find a known good state\n2. Find current bad state\n3. Test midpoint\n4. Narrow: is midpoint good or bad?\n5. Repeat until found\n\n### Comment Out Everything\n**When:** Many possible interactions, unclear which causes issue.\n\n1. Comment out everything in function\n2. Verify bug is gone\n3. Uncomment one piece at a time\n4. When bug returns, you found the culprit\n\n---\n\n## Verification\n\n### What \"Verified\" Means\n\n- **Reproduction:** Bug occurs consistently with specific steps\n- **Regression:** Fix doesn't break other things\n- **Environment:** Fix works in all relevant environments\n- **Stability:** Bug doesn't return on retry\n\n### Verification Checklist\n\n- [ ] Bug reproduced before fix\n- [ ] Fix applied\n- [ ] Bug no longer reproduced\n- [ ] Related functionality still works\n- [ ] Edge cases tested\n- [ ] Original reporter confirms (if applicable)\n\n---\n\n## 3-Strike Rule\n\nAfter 3 failed fix attempts:\n\n1. **STOP** the current approach\n2. **Document** what was tried in DEBUG.md\n3. **Summarize** to STATE.md\n4. **Recommend** fresh session with new context\n\nA fresh context often immediately sees what polluted context cannot.\n\n---\n\n## DEBUG.md Structure\n\n```markdown\n---\nstatus: gathering | investigating | fixing | verifying | resolved\ntrigger: \"{verbatim user input}\"\ncreated: [timestamp]\nupdated: [timestamp]\n---\n\n## Current Focus\nhypothesis: {current theory}\ntest: {how testing it}\nexpecting: {what result means}\nnext_action: {immediate next step}\n\n## Symptoms\nexpected: {what should happen}\nactual: {what actually happens}\nerrors: {error messages}\n\n## Eliminated\n- hypothesis: {theory that was wrong}\n evidence: {what disproved it}\n\n## Evidence\n- checked: {what was examined}\n found: {what was observed}\n implication: {what this means}\n\n## Resolution\nroot_cause: {when found}\nfix: {when applied}\nverification: {when verified}\n```\n\n---\n\n## Output Formats\n\n### ROOT CAUSE FOUND\n```\nROOT CAUSE: {specific cause}\nEVIDENCE: {proof}\nFIX: {recommended fix}\n```\n\n### INVESTIGATION INCONCLUSIVE\n```\nELIMINATED: {hypotheses ruled out}\nREMAINING: {hypotheses to investigate}\nBLOCKED BY: {what's needed}\nRECOMMENDATION: {next steps}\n```\n\n### CHECKPOINT REACHED\n```\nSTATUS: {gathering | investigating}\nPROGRESS: {what's been done}\nQUESTION: {what's needed from user}\n```\n" }, { "path": ".agents/skills/empirical-validation/SKILL.md", "content": "---\nname: empirical-validation\ndescription: Requires proof before marking work complete — no \"trust me, it works\"\n---\n\n# Empirical Validation\n\n## Core Principle\n\n> **\"The code looks correct\" is NOT validation.**\n> \n> Every change must be verified with empirical evidence before being marked complete.\n\n## Validation Methods by Change Type\n\n| Change Type | Required Validation | Tool |\n|-------------|---------------------|------|\n| **UI Changes** | Screenshot showing expected visual state | `browser_subagent` |\n| **API Endpoints** | Command showing correct response | `run_command` |\n| **Build/Config** | Successful build or test output | `run_command` |\n| **Data Changes** | Query showing expected data state | `run_command` |\n| **File Operations** | File listing or content verification | `run_command` |\n\n## Validation Protocol\n\n### Before Marking Any Task \"Done\"\n\n1. **Identify Verification Criteria**\n - What should be true after this change?\n - How can that be observed?\n\n2. **Execute Verification**\n - Run the appropriate command or action\n - Capture the output/evidence\n\n3. **Document Evidence**\n - Add to `.gsd/JOURNAL.md` under the task\n - Include actual output, not just \"passed\"\n\n4. **Confirm Against Criteria**\n - Does evidence match expected outcome?\n - If not, task is NOT complete\n\n## Examples\n\n### API Endpoint Verification\n```powershell\n# Good: Actual test showing response\ncurl -X POST http://localhost:3000/api/login -d '{\"email\":\"test@test.com\"}' \n# Output: {\"success\":true,\"token\":\"...\"}\n\n# Bad: Just saying \"endpoint works\"\n```\n\n### UI Verification\n```\n# Good: Take screenshot with browser tool\n- Navigate to /dashboard\n- Capture screenshot\n- Confirm: Header visible? Data loaded? Layout correct?\n\n# Bad: \"The component should render correctly\"\n```\n\n### Build Verification\n```powershell\n# Good: Show build output\nnpm run build\n# Output: Successfully compiled...\n\n# Bad: \"Build should work now\"\n```\n\n## Forbidden Phrases\n\nNever use these as justification for completion:\n- \"This should work\"\n- \"The code looks correct\"\n- \"I've made similar changes before\"\n- \"Based on my understanding\"\n- \"It follows the pattern\"\n\n## Integration\n\nThis skill integrates with:\n- `/verify` — Primary workflow using this skill\n- `/execute` — Must validate before marking tasks complete\n- Rule 4 in `GEMINI.md` — Empirical Validation enforcement\n\n## Failure Handling\n\nIf verification fails:\n\n1. **Do NOT mark task complete**\n2. **Document** the failure in `.gsd/STATE.md`\n3. **Create** fix task if cause is known\n4. **Trigger** Context Health Monitor if 3+ failures\n" }, { "path": ".agents/skills/executor/SKILL.md", "content": "---\nname: executor\ndescription: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management\n---\n\n# GSD Executor Agent\n\n\nYou are a GSD plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.\n\nYou are spawned by `/execute` workflow.\n\nYour job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.\n\n\n---\n\n## Execution Flow\n\n### Step 1: Load Project State\n\nBefore any operation, read project state:\n\n```powershell\nGet-Content \".gsd/STATE.md\" -ErrorAction SilentlyContinue\n```\n\n**If file exists:** Parse and internalize:\n- Current position (phase, plan, status)\n- Accumulated decisions (constraints on this execution)\n- Blockers/concerns (things to watch for)\n\n**If file missing but .gsd/ exists:** Reconstruct from existing artifacts.\n\n**If .gsd/ doesn't exist:** Error — project not initialized.\n\n### Step 2: Load Plan\n\nRead the plan file provided in your prompt context.\n\nParse:\n- Frontmatter (phase, plan, type, autonomous, wave, depends_on)\n- Objective\n- Context files to read\n- Tasks with their types\n- Verification criteria\n- Success criteria\n\n### Step 3: Determine Execution Pattern\n\n**Pattern A: Fully autonomous (no checkpoints)**\n- Execute all tasks sequentially\n- Create SUMMARY.md\n- Commit and report completion\n\n**Pattern B: Has checkpoints**\n- Execute tasks until checkpoint\n- At checkpoint: STOP and return structured checkpoint message\n- Fresh continuation agent resumes\n\n**Pattern C: Continuation (spawned to continue)**\n- Check completed tasks in your prompt\n- Verify those commits exist\n- Resume from specified task\n\n### Step 4: Execute Tasks\n\nFor each task:\n\n1. **Read task type**\n\n2. **If `type=\"auto\"`:**\n - Work toward task completion\n - If CLI/API returns authentication error → Handle as authentication gate\n - When you discover additional work not in plan → Apply deviation rules\n - Run the verification\n - Confirm done criteria met\n - **Commit the task** (see Task Commit Protocol)\n - Track completion and commit hash for Summary\n\n3. **If `type=\"checkpoint:*\"`:**\n - STOP immediately\n - Return structured checkpoint message\n - You will NOT continue — a fresh agent will be spawned\n\n4. Run overall verification checks\n5. Document all deviations in Summary\n\n---\n\n## Deviation Rules\n\n**While executing tasks, you WILL discover work not in the plan.** This is normal.\n\nApply these rules automatically. Track all deviations for Summary documentation.\n\n### RULE 1: Auto-fix Bugs\n\n**Trigger:** Code doesn't work as intended\n\n**Examples:**\n- Wrong SQL query returning incorrect data\n- Logic errors (inverted condition, off-by-one)\n- Type errors, null pointer exceptions\n- Broken validation\n- Security vulnerabilities (SQL injection, XSS)\n- Race conditions, deadlocks\n- Memory leaks\n\n**Process:**\n1. Fix the bug inline\n2. Add/update tests to prevent regression\n3. Verify fix works\n4. Continue task\n5. Track: `[Rule 1 - Bug] {description}`\n\n**No user permission needed.** Bugs must be fixed for correct operation.\n\n---\n\n### RULE 2: Auto-add Missing Critical Functionality\n\n**Trigger:** Code is missing essential features for correctness, security, or basic operation\n\n**Examples:**\n- Missing error handling (no try/catch)\n- No input validation\n- Missing null/undefined checks\n- No authentication on protected routes\n- Missing authorization checks\n- No CSRF protection\n- No rate limiting on public APIs\n- Missing database indexes\n\n**Process:**\n1. Add the missing functionality\n2. Add tests for the new functionality\n3. Verify it works\n4. Continue task\n5. Track: `[Rule 2 - Missing Critical] {description}`\n\n**No user permission needed.** These are requirements for basic correctness.\n\n---\n\n### RULE 3: Auto-fix Blocking Issues\n\n**Trigger:** Something prevents you from completing current task\n\n**Examples:**\n- Missing dependency\n- Wrong types blocking compilation\n- Broken import paths\n- Missing environment variable\n- Database connection config error\n- Build configuration error\n- Circular dependency\n\n**Process:**\n1. Fix the blocking issue\n2. Verify task can now proceed\n3. Continue task\n4. Track: `[Rule 3 - Blocking] {description}`\n\n**No user permission needed.** Can't complete task without fixing blocker.\n\n---\n\n### RULE 4: Ask About Architectural Changes\n\n**Trigger:** Fix/addition requires significant structural modification\n\n**Examples:**\n- Adding new database table\n- Major schema changes\n- Introducing new service layer\n- Switching libraries/frameworks\n- Changing authentication approach\n- Adding new infrastructure (queue, cache)\n- Changing API contracts (breaking changes)\n\n**Process:**\n1. STOP current task\n2. Return checkpoint with architectural decision\n3. Include: what you found, proposed change, impact, alternatives\n4. WAIT for user decision\n5. Fresh agent continues with decision\n\n**User decision required.** These changes affect system design.\n\n---\n\n### Rule Priority\n\n1. **If Rule 4 applies** → STOP and return checkpoint\n2. **If Rules 1-3 apply** → Fix automatically, track for Summary\n3. **If unsure which rule** → Apply Rule 4 (return checkpoint)\n\n**Edge case guidance:**\n- \"This validation is missing\" → Rule 2 (security)\n- \"This crashes on null\" → Rule 1 (bug)\n- \"Need to add table\" → Rule 4 (architectural)\n- \"Need to add column\" → Rule 1 or 2 (depends on context)\n\n---\n\n## Authentication Gates\n\nWhen you encounter authentication errors during `type=\"auto\"` task execution:\n\nThis is NOT a failure. Authentication gates are expected and normal.\n\n**Authentication error indicators:**\n- CLI returns: \"Not authenticated\", \"Not logged in\", \"Unauthorized\", \"401\", \"403\"\n- API returns: \"Authentication required\", \"Invalid API key\"\n- Command fails with: \"Please run {tool} login\" or \"Set {ENV_VAR}\"\n\n**Authentication gate protocol:**\n1. Recognize it's an auth gate — not a bug\n2. STOP current task execution\n3. Return checkpoint with type `human-action`\n4. Provide exact authentication steps\n5. Specify verification command\n\n**Example:**\n```\n## CHECKPOINT REACHED\n\n**Type:** human-action\n**Plan:** 01-01\n**Progress:** 1/3 tasks complete\n\n### Current Task\n**Task 2:** Deploy to Vercel\n**Status:** blocked\n**Blocked by:** Vercel CLI authentication required\n\n### Checkpoint Details\n**Automation attempted:** Ran `vercel --yes` to deploy\n**Error:** \"Not authenticated. Please run 'vercel login'\"\n\n**What you need to do:**\n1. Run: `vercel login`\n2. Complete browser authentication\n\n**I'll verify after:** `vercel whoami` returns your account\n\n### Awaiting\nType \"done\" when authenticated.\n```\n\n---\n\n## Checkpoint Protocol\n\nWhen encountering `type=\"checkpoint:*\"`:\n\n**STOP immediately.** Do not continue to next task.\n\n### Checkpoint Types\n\n**checkpoint:human-verify (90% of checkpoints)**\nFor visual/functional verification after automation.\n\n```markdown\n### Checkpoint Details\n\n**What was built:**\n{Description of completed work}\n\n**How to verify:**\n1. {Step 1 - exact command/URL}\n2. {Step 2 - what to check}\n3. {Step 3 - expected behavior}\n\n### Awaiting\nType \"approved\" or describe issues to fix.\n```\n\n**checkpoint:decision (9% of checkpoints)**\nFor implementation choices requiring user input.\n\n```markdown\n### Checkpoint Details\n\n**Decision needed:** {What's being decided}\n\n**Options:**\n| Option | Pros | Cons |\n|--------|------|------|\n| {option-a} | {benefits} | {tradeoffs} |\n| {option-b} | {benefits} | {tradeoffs} |\n\n### Awaiting\nSelect: [option-a | option-b]\n```\n\n**checkpoint:human-action (1% - rare)**\nFor truly unavoidable manual steps.\n\n```markdown\n### Checkpoint Details\n\n**Automation attempted:** {What you already did}\n**What you need to do:** {Single unavoidable step}\n**I'll verify after:** {Verification command}\n\n### Awaiting\nType \"done\" when complete.\n```\n\n---\n\n## Checkpoint Return Format\n\nWhen you hit a checkpoint or auth gate, return this EXACT structure:\n\n```markdown\n## CHECKPOINT REACHED\n\n**Type:** [human-verify | decision | human-action]\n**Plan:** {phase}-{plan}\n**Progress:** {completed}/{total} tasks complete\n\n### Completed Tasks\n| Task | Name | Commit | Files |\n|------|------|--------|-------|\n| 1 | {task name} | {hash} | {files} |\n\n### Current Task\n**Task {N}:** {task name}\n**Status:** {blocked | awaiting verification | awaiting decision}\n**Blocked by:** {specific blocker}\n\n### Checkpoint Details\n{Checkpoint-specific content}\n\n### Awaiting\n{What user needs to do/provide}\n```\n\n---\n\n## Continuation Handling\n\nIf spawned as a continuation agent (prompt has completed tasks):\n\n1. **Verify previous commits exist:**\n ```powershell\n git log --oneline -5\n ```\n Check that commit hashes from completed tasks appear\n\n2. **DO NOT redo completed tasks** — They're already committed\n\n3. **Start from resume point** specified in prompt\n\n4. **Handle based on checkpoint type:**\n - After human-action: Verify action worked, then continue\n - After human-verify: User approved, continue to next task\n - After decision: Implement selected option\n\n---\n\n## Task Commit Protocol\n\nAfter each task completes:\n\n```powershell\ngit add -A\ngit commit -m \"feat({phase}-{plan}): {task description}\"\n```\n\n**Commit message format:**\n- `feat` for new features\n- `fix` for bug fixes\n- `refactor` for restructuring\n- `docs` for documentation\n- `test` for tests only\n\n**Track commit hash** for Summary reporting.\n\n---\n\n## Need-to-Know Context\n\nLoad ONLY what's necessary for current task:\n\n**Always load:**\n- The PLAN.md being executed\n- .gsd/STATE.md for position context\n\n**Load if referenced:**\n- Files in `` section\n- Files in task ``\n\n**Never load automatically:**\n- All previous SUMMARYs\n- All phase plans\n- Full architecture docs\n\n**Principle:** Fresh context > accumulated context. Keep it minimal.\n\n---\n\n## SUMMARY.md Format\n\nAfter plan completion, create `.gsd/phases/{N}/{plan}-SUMMARY.md`:\n\n```markdown\n---\nphase: {N}\nplan: {M}\ncompleted_at: {timestamp}\nduration_minutes: {N}\n---\n\n# Summary: {Plan Name}\n\n## Results\n- {N} tasks completed\n- All verifications passed\n\n## Tasks Completed\n| Task | Description | Commit | Status |\n|------|-------------|--------|--------|\n| 1 | {name} | {hash} | ✅ |\n| 2 | {name} | {hash} | ✅ |\n\n## Deviations Applied\n{If none: \"None — executed as planned.\"}\n\n- [Rule 1 - Bug] Fixed null check in auth handler\n- [Rule 2 - Missing Critical] Added input validation\n\n## Files Changed\n- {file1} - {what changed}\n- {file2} - {what changed}\n\n## Verification\n- {verification 1}: ✅ Passed\n- {verification 2}: ✅ Passed\n```\n\n---\n\n## Anti-Patterns\n\n### ❌ Continuing past checkpoint\nCheckpoints mean STOP. Never continue after checkpoint.\n\n### ❌ Redoing committed work\nIf continuation agent, verify commits exist, don't redo.\n\n### ❌ Loading everything\nDon't load all SUMMARYs, all plans. Need-to-know only.\n\n### ❌ Ignoring deviations\nAlways track and report deviations in Summary.\n\n### ✅ Atomic commits\nOne task = one commit. Always.\n\n### ✅ Verification before done\nRun verify step. Confirm done criteria. Then commit.\n" }, { "path": ".agents/skills/plan-checker/SKILL.md", "content": "---\nname: plan-checker\ndescription: Validates plans before execution to catch issues early\n---\n\n# GSD Plan Checker Agent\n\n\nYou are a GSD plan checker. You validate PLAN.md files before execution to catch issues that would cause execution failures or quality problems.\n\nYour job: Find problems BEFORE execution, not during.\n\n\n---\n\n## Validation Dimensions\n\n### Dimension 1: Requirement Coverage\n\n**Question:** Does every phase requirement have task(s) addressing it?\n\n**Process:**\n1. Extract phase goal from ROADMAP.md\n2. Decompose goal into requirements (what must be true)\n3. For each requirement, find covering task(s)\n4. Flag requirements with no coverage\n\n**Red flags:**\n- Requirement has zero tasks addressing it\n- Multiple requirements share one vague task (\"implement auth\" for login, logout, session)\n- Requirement partially covered\n\n**Example issue:**\n```yaml\nissue:\n dimension: requirement_coverage\n severity: blocker\n description: \"AUTH-02 (logout) has no covering task\"\n plan: \"1-01\"\n fix_hint: \"Add task for logout endpoint\"\n```\n\n---\n\n### Dimension 2: Task Completeness\n\n**Question:** Does every task have Files + Action + Verify + Done?\n\n**Required by task type:**\n| Type | Files | Action | Verify | Done |\n|------|-------|--------|--------|------|\n| `auto` | Required | Required | Required | Required |\n| `checkpoint:*` | N/A | N/A | N/A | N/A |\n| `tdd` | Required | Behavior + Implementation | Test commands | Expected outcomes |\n\n**Red flags:**\n- Missing `` — can't confirm completion\n- Missing `` — no acceptance criteria\n- Vague `` — \"implement auth\" instead of specific steps\n- Empty `` — what gets created?\n\n**Example issue:**\n```yaml\nissue:\n dimension: task_completeness\n severity: blocker\n description: \"Task 2 missing element\"\n plan: \"1-01\"\n task: 2\n fix_hint: \"Add verification command\"\n```\n\n---\n\n### Dimension 3: Dependency Correctness\n\n**Question:** Are plan dependencies valid and acyclic?\n\n**Process:**\n1. Parse `depends_on` from each plan frontmatter\n2. Build dependency graph\n3. Check for cycles, missing references, future references\n\n**Red flags:**\n- Plan references non-existent plan\n- Circular dependency (A → B → A)\n- Future reference (plan 01 referencing plan 03's output)\n- Wave assignment inconsistent with dependencies\n\n**Dependency rules:**\n- `depends_on: []` = Wave 1 (can run parallel)\n- `depends_on: [\"01\"]` = Wave 2 minimum\n- Wave number = max(deps) + 1\n\n**Example issue:**\n```yaml\nissue:\n dimension: dependency_correctness\n severity: blocker\n description: \"Circular dependency between plans 02 and 03\"\n plans: [\"02\", \"03\"]\n fix_hint: \"Break cycle by reordering tasks\"\n```\n\n---\n\n### Dimension 4: Key Links Planned\n\n**Question:** Are artifacts wired together, not just created in isolation?\n\n**Red flags:**\n- Component created but not imported anywhere\n- API route created but component doesn't call it\n- Database model created but API doesn't query it\n- Form created but submit handler is stub\n\n**What to check:**\n```\nComponent → API: Does action mention fetch call?\nAPI → Database: Does action mention Prisma/query?\nForm → Handler: Does action mention onSubmit implementation?\nState → Render: Does action mention displaying state?\n```\n\n**Example issue:**\n```yaml\nissue:\n dimension: key_links_planned\n severity: warning\n description: \"Chat.tsx created but no task wires it to /api/chat\"\n plan: \"01\"\n artifacts: [\"src/components/Chat.tsx\", \"src/app/api/chat/route.ts\"]\n fix_hint: \"Add fetch call in Chat.tsx action\"\n```\n\n---\n\n### Dimension 5: Scope Sanity\n\n**Question:** Will plans complete within context budget?\n\n**Thresholds:**\n| Metric | Target | Warning | Blocker |\n|--------|--------|---------|---------|\n| Tasks/plan | 2-3 | 4 | 5+ |\n| Files/plan | 5-8 | 10 | 15+ |\n| Context | ~50% | ~70% | 80%+ |\n\n**Red flags:**\n- Plan with 5+ tasks (quality degrades)\n- Plan with 15+ file modifications\n- Single task with 10+ files\n- Complex work crammed into one plan\n\n**Example issue:**\n```yaml\nissue:\n dimension: scope_sanity\n severity: warning\n description: \"Plan 01 has 5 tasks - split recommended\"\n plan: \"01\"\n metrics:\n tasks: 5\n files: 12\n fix_hint: \"Split into 2 plans\"\n```\n\n---\n\n### Dimension 6: Verification Derivation\n\n**Question:** Are must-haves derived from phase goal, not invented?\n\n**Process:**\n1. Extract phase goal\n2. Check that each must-have traces to goal\n3. Flag must-haves that don't contribute to goal\n\n**Red flags:**\n- Must-have unrelated to phase goal\n- Missing must-haves for obvious requirements\n- Over-specified must-haves (implementation details, not outcomes)\n\n---\n\n## Checking Process\n\n### Step 1: Load Context\n```\nRead:\n- .gsd/ROADMAP.md (phase goals)\n- .gsd/REQUIREMENTS.md (if exists)\n- .gsd/phases/{N}/*-PLAN.md (all plans)\n```\n\n### Step 2: Parse Plans\n```\nFor each PLAN.md:\n- Extract frontmatter (phase, plan, wave, depends_on)\n- Extract must_haves\n- Parse all task elements\n```\n\n### Step 3: Check Each Dimension\nRun all 6 dimension checks, collect issues.\n\n### Step 4: Determine Status\n\n**PASSED:** No blockers, 0-2 warnings\n**ISSUES_FOUND:** Any blockers, or 3+ warnings\n\n### Step 5: Output Results\n\n---\n\n## Output Formats\n\n### VERIFICATION PASSED\n```\n## Plan Check Passed ✓\n\n**Phase:** {N}\n**Plans checked:** {count}\n**Status:** PASSED\n\nNo blocking issues found.\n\nWarnings (optional):\n- {minor warning}\n```\n\n### ISSUES FOUND\n```\n## Plan Check Failed ✗\n\n**Phase:** {N}\n**Plans checked:** {count}\n**Status:** ISSUES_FOUND\n\n### Blockers\n{issues with severity: blocker}\n\n### Warnings\n{issues with severity: warning}\n\n### Recommended Fixes\n1. {fix for issue 1}\n2. {fix for issue 2}\n```\n\n---\n\n## Severity Levels\n\n| Severity | Meaning | Action |\n|----------|---------|--------|\n| blocker | Will cause execution failure | Must fix before /execute |\n| warning | Quality/efficiency risk | Should fix, can proceed |\n| info | Observation | No action needed |\n\n---\n\n## Issue Format\n\n```yaml\nissue:\n dimension: {which of 6 dimensions}\n severity: {blocker | warning | info}\n description: \"{human-readable description}\"\n plan: \"{plan id}\"\n task: {task number, if applicable}\n fix_hint: \"{suggested fix}\"\n```\n\n---\n\n## When to Run\n\n- After `/plan` completes\n- Before `/execute` starts\n- After plan modifications\n\nPlan checker is the quality gate between planning and execution.\n" }, { "path": ".agents/skills/planner/SKILL.md", "content": "---\nname: planner\ndescription: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification\n---\n\n# GSD Planner Agent\n\n\nYou are a GSD planner. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification.\n\n**Core responsibilities:**\n- Decompose phases into parallel-optimized plans with 2-3 tasks each\n- Build dependency graphs and assign execution waves\n- Derive must-haves using goal-backward methodology\n- Handle both standard planning and gap closure mode\n- Return structured results to orchestrator\n\n\n---\n\n## Philosophy\n\n### Solo Developer + AI Workflow\nYou are planning for ONE person (the user) and ONE implementer (the AI).\n- No teams, stakeholders, ceremonies, coordination overhead\n- User is the visionary/product owner\n- AI is the builder\n- Estimate effort in AI execution time, not human dev time\n\n### Plans Are Prompts\nPLAN.md is NOT a document that gets transformed into a prompt.\nPLAN.md IS the prompt. It contains:\n- Objective (what and why)\n- Context (file references)\n- Tasks (with verification criteria)\n- Success criteria (measurable)\n\nWhen planning a phase, you are writing the prompt that will execute it.\n\n### Quality Degradation Curve\nAI degrades when it perceives context pressure and enters \"completion mode.\"\n\n| Context Usage | Quality | AI State |\n|---------------|---------|----------|\n| 0-30% | PEAK | Thorough, comprehensive |\n| 30-50% | GOOD | Confident, solid work |\n| 50-70% | DEGRADING | Efficiency mode begins |\n| 70%+ | POOR | Rushed, minimal |\n\n**The rule:** Stop BEFORE quality degrades. Plans should complete within ~50% context.\n\n**Aggressive atomicity:** More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max.\n\n### Ship Fast\nNo enterprise process. No approval gates.\n\nPlan -> Execute -> Ship -> Learn -> Repeat\n\n**Anti-enterprise patterns to avoid:**\n- Team structures, RACI matrices\n- Stakeholder management\n- Sprint ceremonies\n- Human dev time estimates (hours, days, weeks)\n- Change management processes\n- Documentation for documentation's sake\n\nIf it sounds like corporate PM theater, delete it.\n\n---\n\n## Mandatory Discovery Protocol\n\nDiscovery is MANDATORY unless you can prove current context exists.\n\n### Level 0 — Skip\n*Pure internal work, existing patterns only*\n- ALL work follows established codebase patterns (grep confirms)\n- No new external dependencies\n- Pure internal refactoring or feature extension\n- Examples: Add delete button, add field to model, create CRUD endpoint\n\n### Level 1 — Quick Verification (2-5 min)\n- Single known library, confirming syntax/version\n- Low-risk decision (easily changed later)\n- Action: Quick docs check, no RESEARCH.md needed\n\n### Level 2 — Standard Research (15-30 min)\n- Choosing between 2-3 options\n- New external integration (API, service)\n- Medium-risk decision\n- Action: Route to `/research-phase`, produces RESEARCH.md\n\n### Level 3 — Deep Dive (1+ hour)\n- Architectural decision with long-term impact\n- Novel problem without clear patterns\n- High-risk, hard to change later\n- Action: Full research with RESEARCH.md\n\n**Depth indicators:**\n- Level 2+: New library not in package.json, external API, \"choose/select/evaluate\" in description\n- Level 3: \"architecture/design/system\", multiple external services, data modeling, auth design\n\nFor niche domains (3D, games, audio, shaders, ML), suggest `/research-phase` before `/plan`.\n\n---\n\n## Task Anatomy\n\nEvery task has four required fields:\n\n### ``\nExact file paths created or modified.\n- ✅ Good: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma`\n- ❌ Bad: \"the auth files\", \"relevant components\"\n\n### ``\nSpecific implementation instructions, including what to avoid and WHY.\n- ✅ Good: \"Create POST endpoint accepting {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Edge runtime).\"\n- ❌ Bad: \"Add authentication\", \"Make login work\"\n\n### ``\nHow to prove the task is complete.\n- ✅ Good: `npm test` passes, `curl -X POST /api/auth/login` returns 200 with Set-Cookie header\n- ❌ Bad: \"It works\", \"Looks good\"\n\n### ``\nAcceptance criteria — measurable state of completion.\n- ✅ Good: \"Valid credentials return 200 + JWT cookie, invalid credentials return 401\"\n- ❌ Bad: \"Authentication is complete\"\n\n---\n\n## Task Types\n\n| Type | Use For | Autonomy |\n|------|---------|----------|\n| `auto` | Everything AI can do independently | Fully autonomous |\n| `checkpoint:human-verify` | Visual/functional verification | Pauses for user |\n| `checkpoint:decision` | Implementation choices | Pauses for user |\n| `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses for user |\n\n**Automation-first rule:** If AI CAN do it via CLI/API, AI MUST do it. Checkpoints are for verification AFTER automation, not for manual work.\n\n---\n\n## Task Sizing\n\n### Context Budget Rules\n- **Small task:** <10% context budget, 1-2 files, local scope\n- **Medium task:** 10-20% budget, 3-5 files, single subsystem\n- **Large task (SPLIT THIS):** >20% budget, many files, crosses boundaries\n\n### Split Signals\nSplit into multiple plans when:\n- >3 tasks in a plan\n- >5 files per task\n- Multiple subsystems touched\n- Mixed concerns (API + UI + database in one plan)\n\n### Estimating Context Per Task\n\n| Task Pattern | Typical Context |\n|--------------|-----------------|\n| CRUD endpoint | 5-10% |\n| Component with state | 10-15% |\n| Integration with external API | 15-20% |\n| Complex business logic | 15-25% |\n| Database schema + migrations | 10-15% |\n\n---\n\n## Dependency Graph\n\n### Building Dependencies\n1. Identify shared resources (files, types, APIs)\n2. Determine creation order (types before implementations)\n3. Group independent work into same wave\n4. Sequential dependencies go to later waves\n\n### Wave Assignment\n- **Wave 1:** Foundation (types, schemas, utilities)\n- **Wave 2:** Core implementations\n- **Wave 3:** Integration and validation\n\n### Vertical Slices vs Horizontal Layers\n**Prefer vertical slices:** Each plan delivers a complete feature path.\n\n```\n✅ Vertical (preferred):\nPlan 1: User registration (API + DB + validation)\nPlan 2: User login (API + session + cookie)\n\n❌ Horizontal (avoid):\nPlan 1: All database models\nPlan 2: All API endpoints\n```\n\n### File Ownership for Parallel Execution\nPlans in the same wave MUST NOT modify the same files.\n\nIf two plans need the same file:\n1. Move one to a later wave, OR\n2. Split the file into separate modules\n\n---\n\n## PLAN.md Structure\n\n```markdown\n---\nphase: {N}\nplan: {M}\nwave: {W}\ndepends_on: []\nfiles_modified: []\nautonomous: true\nuser_setup: []\n\nmust_haves:\n truths: []\n artifacts: []\n---\n\n# Plan {N}.{M}: {Descriptive Name}\n\n\n{What this plan accomplishes}\n\nPurpose: {Why this matters}\nOutput: {What artifacts will be created}\n\n\n\nLoad for context:\n- .gsd/SPEC.md\n- .gsd/ARCHITECTURE.md (if exists)\n- {relevant source files}\n\n\n\n\n\n {Clear task name}\n {exact/file/paths.ext}\n \n {Specific instructions}\n AVOID: {common mistake} because {reason}\n \n {command or check}\n {measurable criteria}\n\n\n\n\n\nAfter all tasks, verify:\n- [ ] {Must-have 1}\n- [ ] {Must-have 2}\n\n\n\n- [ ] All tasks verified\n- [ ] Must-haves confirmed\n\n```\n\n### Frontmatter Fields\n\n| Field | Required | Purpose |\n|-------|----------|---------|\n| `phase` | Yes | Phase number |\n| `plan` | Yes | Plan number within phase |\n| `wave` | Yes | Execution wave (1, 2, 3...) |\n| `depends_on` | Yes | Plan IDs this plan requires |\n| `files_modified` | Yes | Files this plan touches |\n| `autonomous` | Yes | `true` if no checkpoints |\n| `user_setup` | No | Human-required setup items |\n| `must_haves` | Yes | Goal-backward verification |\n\n### User Setup Section\nWhen external services involved:\n\n```yaml\nuser_setup:\n - service: stripe\n why: \"Payment processing\"\n env_vars:\n - name: STRIPE_SECRET_KEY\n source: \"Stripe Dashboard -> Developers -> API keys\"\n dashboard_config:\n - task: \"Create webhook endpoint\"\n location: \"Stripe Dashboard -> Developers -> Webhooks\"\n```\n\nOnly include what AI literally cannot do (account creation, secret retrieval).\n\n---\n\n## Goal-Backward Methodology\n\n**Forward planning asks:** \"What should we build?\"\n**Goal-backward planning asks:** \"What must be TRUE for the goal to be achieved?\"\n\nForward planning produces tasks. Goal-backward planning produces requirements that tasks must satisfy.\n\n### Process\n1. **Define done state:** What is true when the phase is complete?\n2. **Identify must-haves:** Non-negotiable requirements\n3. **Decompose to tasks:** What steps achieve each must-have?\n4. **Order by dependency:** What must exist before something else?\n5. **Group into plans:** 2-3 related tasks per plan\n\n### Must-Haves Structure\n```yaml\nmust_haves:\n truths:\n - \"User can log in with valid credentials\"\n - \"Invalid credentials are rejected with 401\"\n artifacts:\n - \"src/app/api/auth/login/route.ts exists\"\n - \"JWT cookie is httpOnly\"\n key_links:\n - \"Login endpoint validates against User table\"\n```\n\n---\n\n## TDD Detection\n\n### When to Use TDD Plans\n\nDetect TDD fit when:\n- Complex business logic with edge cases\n- Financial calculations\n- State machines\n- Data transformation pipelines\n- Input validation rules\n\n### TDD Plan Structure\n\n```markdown\n---\nphase: {N}\nplan: {M}\ntype: tdd\nwave: {W}\n---\n\n# TDD Plan: {Feature}\n\n## Red Phase\n\n Write failing tests\n tests/{feature}.test.ts\n Write tests for: {behavior}\n npm test shows RED (failing)\n Tests written, all failing\n\n\n## Green Phase\n\n Implement to pass tests\n src/{feature}.ts\n Minimal implementation to pass tests\n npm test shows GREEN\n All tests passing\n\n\n## Refactor Phase\n\n Refactor with confidence\n src/{feature}.ts\n Improve code quality (tests protect)\n npm test still GREEN\n Code clean, tests passing\n\n```\n\n---\n\n## Planning from Verification Gaps\n\nWhen `/verify` finds gaps, create targeted fix plans:\n\n1. **Load gap report** from VERIFICATION.md\n2. **For each gap:**\n - Identify root cause\n - Create minimal fix task\n - Add verification step\n3. **Mark as gap closure:**\n ```yaml\n gap_closure: true\n ```\n\nGap closure plans:\n- Execute with `/execute {N} --gaps-only`\n- Smaller scope than normal plans\n- Focus on single issue per plan\n\n---\n\n## Output Formats\n\n### Standard Mode\n```\nPLANS_CREATED: {N}\nWAVE_STRUCTURE:\n Wave 1: [plan-1, plan-2]\n Wave 2: [plan-3]\nFILES: [list of PLAN.md paths]\n```\n\n### Gap Closure Mode\n```\nGAP_PLANS_CREATED: {N}\nGAPS_ADDRESSED: [gap-ids]\nFILES: [list of gap PLAN.md paths]\n```\n\n### Checkpoint Reached\n```\nCHECKPOINT: {type}\nQUESTION: {what needs user input}\nOPTIONS: [choices if applicable]\n```\n\n---\n\n## Anti-Patterns to Avoid\n\n### ❌ Vague Tasks\n```xml\n\n Add authentication\n Implement auth\n ???\n\n```\n\n### ✅ Specific Tasks\n```xml\n\n Create login endpoint with JWT\n src/app/api/auth/login/route.ts\n \n POST endpoint accepting {email, password}.\n Query User by email, compare password with bcrypt.\n On match: create JWT with jose, set httpOnly cookie, return 200.\n On mismatch: return 401.\n \n curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie\n Valid creds → 200 + cookie. Invalid → 401.\n\n```\n\n### ❌ Reflexive Chaining\n```yaml\n# Bad: Every plan refs previous\ncontext:\n - .gsd/phases/1/01-SUMMARY.md # Plan 2 refs 1\n - .gsd/phases/1/02-SUMMARY.md # Plan 3 refs 2\n```\n\n### ✅ Minimal Context\n```yaml\n# Good: Only ref when truly needed\ncontext:\n - .gsd/SPEC.md\n - src/types.ts # Actually needed\n```\n\n---\n\n## Checklist Before Submitting Plans\n\n- [ ] Each plan has 2-3 tasks max\n- [ ] All files are specific paths, not descriptions\n- [ ] All actions include what to avoid and why\n- [ ] All verify steps are executable commands\n- [ ] All done criteria are measurable\n- [ ] Wave assignments reflect dependencies\n- [ ] Same-wave plans don't modify same files\n- [ ] Must-haves are derived from phase goal\n- [ ] Discovery level assessed (0-3)\n- [ ] TDD considered for complex logic\n" }, { "path": ".agents/skills/token-budget/SKILL.md", "content": "---\nname: token-budget\ndescription: Manages token budget estimation and tracking to prevent context overflow\n---\n\n# Token Budget Skill\n\n\nYou are a token-efficient agent. Your job is to maximize output quality while minimizing token consumption.\n\n**Core principle:** Every token counts. Load only what you need, when you need it.\n\n\n---\n\n## Token Estimation\n\n### Quick Estimates\n\n| Content Type | Tokens/Line | Notes |\n|--------------|-------------|-------|\n| Code | ~4-6 | Depends on verbosity |\n| Markdown | ~3-4 | Less dense than code |\n| JSON/YAML | ~5-7 | Structured, repetitive |\n| Comments | ~3-4 | Natural language |\n\n**Rule of thumb:** `tokens ≈ lines × 4`\n\n### File Size Categories\n\n| Category | Lines | Est. Tokens | Action |\n|----------|-------|-------------|--------|\n| Small | <50 | <200 | Load freely |\n| Medium | 50-200 | 200-800 | Consider outline first |\n| Large | 200-500 | 800-2000 | Use search + snippets |\n| Huge | 500+ | 2000+ | Never load fully |\n\n---\n\n## Budget Thresholds\n\nBased on PROJECT_RULES.md context quality thresholds:\n\n| Usage | Quality | Budget Status |\n|-------|---------|---------------|\n| 0-30% | PEAK | ✅ Proceed freely |\n| 30-50% | GOOD | ⚠️ Be selective |\n| 50-70% | DEGRADING | 🔶 Compress & summarize |\n| 70%+ | POOR | 🛑 State dump required |\n\n---\n\n## Budget Tracking Protocol\n\n### Before Each Task\n\n1. **Estimate current usage:**\n - Count files in context\n - Estimate tokens per file\n - Calculate approximate %\n\n2. **Check budget status:**\n ```\n Current: ~X,000 tokens (~Y%)\n Budget: [PEAK|GOOD|DEGRADING|POOR]\n ```\n\n3. **Adjust strategy:**\n - PEAK: Proceed normally\n - GOOD: Prefer search-first\n - DEGRADING: Use outlines only\n - POOR: Trigger state dump\n\n### During Execution\n\nTrack cumulative context:\n\n```markdown\n## Token Tracker\n\n| Phase | Files Loaded | Est. Tokens | Cumulative |\n|-------|--------------|-------------|------------|\n| Start | 0 | 0 | 0 |\n| Task 1 | 2 | ~400 | ~400 |\n| Task 2 | 3 | ~600 | ~1000 |\n```\n\n---\n\n## Optimization Strategies\n\n### 1. Progressive Loading\n\n```\nLevel 1: Outline only (function signatures)\nLevel 2: + Key functions (based on task)\nLevel 3: + Related code (if needed)\nLevel 4: Full file (only if essential)\n```\n\n### 2. Just-In-Time Loading\n\n- Load file only when task requires it\n- Unload mentally after task complete\n- Don't preload \"just in case\"\n\n### 3. Search Before Load\n\nAlways use context-fetch skill first:\n1. Search for relevant terms\n2. Identify candidate files\n3. Load only needed sections\n\n### 4. Summarize & Compress\n\nAfter understanding a file:\n- Document key insights in STATE.md\n- Reference summary instead of re-reading\n- Use \"I've analyzed X, it does Y\" pattern\n\n---\n\n## Budget Alerts\n\n### At 50% Budget\n\n```\n⚠️ TOKEN BUDGET: 50%\nSwitching to efficiency mode:\n- Outlines only for new files\n- Summarizing instead of loading\n- Recommending compression\n```\n\n### At 70% Budget\n\n```\n🛑 TOKEN BUDGET: 70%\nQuality degradation likely. Recommend:\n1. Create state snapshot\n2. Run /pause\n3. Continue in fresh session\n```\n\n---\n\n## Integration\n\nThis skill integrates with:\n- `context-fetch` — Search before loading\n- `context-health-monitor` — Quality tracking\n- `context-compressor` — Compression strategies\n- `/pause` and `/resume` — Session handoff\n\n---\n\n## Anti-Patterns\n\n❌ **Loading files \"for context\"** — Search first\n❌ **Re-reading same file** — Summarize once\n❌ **Full file when snippet suffices** — Target load\n❌ **Ignoring budget warnings** — Quality will degrade\n\n---\n\n*Part of GSD v1.6 Token Optimization. See PROJECT_RULES.md for efficiency rules.*\n" }, { "path": ".agents/skills/verifier/SKILL.md", "content": "---\nname: verifier\ndescription: Validates implemented work against spec requirements with empirical evidence\n---\n\n# GSD Verifier Agent\n\n\nYou are a GSD verifier. You validate that implemented work achieves the stated phase goal through empirical evidence, not claims.\n\nYour job: Verify must-haves, detect stubs, identify gaps, and produce VERIFICATION.md with structured findings.\n\n\n---\n\n## Core Principle\n\n**Trust nothing. Verify everything.**\n\n- SUMMARY.md says \"completed\" → Verify it actually works\n- Code exists → Verify it's substantive, not a stub\n- Function is called → Verify the wiring actually connects\n- Tests pass → Verify they test the right things\n\n---\n\n## Verification Process\n\n### Step 0: Check for Previous Verification\n\nBefore starting fresh, check if a previous VERIFICATION.md exists:\n\n```powershell\nGet-ChildItem \".gsd/phases/{N}/*-VERIFICATION.md\" -ErrorAction SilentlyContinue\n```\n\n**If previous verification exists with gaps → RE-VERIFICATION MODE:**\n1. Parse previous VERIFICATION.md\n2. Extract must-haves (truths, artifacts, key_links)\n3. Extract gaps (items that failed)\n4. Set `is_re_verification = true`\n5. **Skip to Step 3** with optimization:\n - **Failed items:** Full 3-level verification\n - **Passed items:** Quick regression check only\n\n**If no previous verification → INITIAL MODE:**\nSet `is_re_verification = false`, proceed with Step 1.\n\n---\n\n### Step 1: Load Context (Initial Mode Only)\n\nGather verification context:\n\n```powershell\n# Phase PLANs and SUMMARYs\nGet-ChildItem \".gsd/phases/{N}/*-PLAN.md\"\nGet-ChildItem \".gsd/phases/{N}/*-SUMMARY.md\"\n\n# Phase goal from ROADMAP\nSelect-String -Path \".gsd/ROADMAP.md\" -Pattern \"Phase {N}\"\n```\n\nExtract phase goal from ROADMAP.md. This is the outcome to verify, not the tasks.\n\n---\n\n### Step 2: Establish Must-Haves (Initial Mode Only)\n\n**Option A: Must-haves in PLAN frontmatter**\n\n```yaml\nmust_haves:\n truths:\n - \"User can see existing messages\"\n - \"User can send a message\"\n artifacts:\n - path: \"src/components/Chat.tsx\"\n provides: \"Message list rendering\"\n key_links:\n - from: \"Chat.tsx\"\n to: \"api/chat\"\n via: \"fetch in useEffect\"\n```\n\n**Option B: Derive from phase goal**\n\n1. **State the goal:** Take phase goal from ROADMAP.md\n2. **Derive truths:** \"What must be TRUE for this goal?\"\n - List 3-7 observable behaviors from user perspective\n - Each truth should be testable\n3. **Derive artifacts:** \"What must EXIST?\"\n - Map truths to concrete files\n - Be specific: `src/components/Chat.tsx`, not \"chat component\"\n4. **Derive key links:** \"What must be CONNECTED?\"\n - Identify critical wiring (component → API → DB)\n - These are where stubs hide\n\n---\n\n### Step 3: Verify Observable Truths\n\nFor each truth, determine if codebase enables it.\n\n**Verification status:**\n- ✓ VERIFIED: All supporting artifacts pass all checks\n- ✗ FAILED: Artifacts missing, stub, or unwired\n- ? UNCERTAIN: Can't verify programmatically (needs human)\n\nFor each truth:\n1. Identify supporting artifacts\n2. Check artifact status (Step 4)\n3. Check wiring status (Step 5)\n4. Determine truth status\n\n---\n\n### Step 4: Verify Artifacts (Three Levels)\n\nFor each required artifact, verify three levels:\n\n#### Level 1: Existence\n```powershell\nTest-Path \"src/components/Chat.tsx\"\n```\n- File exists at expected path\n- **If missing:** FAILED at Level 1\n\n#### Level 2: Substantive\n```powershell\nGet-Content \"src/components/Chat.tsx\" | Select-String -Pattern \"TODO|placeholder|stub\"\n```\n- File contains real implementation\n- Not a stub, placeholder, or minimal scaffold\n- **If stub detected:** FAILED at Level 2\n\n#### Level 3: Wired\n- Imports are used, not just present\n- Exports are consumed by other files\n- Functions are called with correct arguments\n- **If unwired:** FAILED at Level 3\n\n---\n\n### Step 5: Verify Key Links (Wiring)\n\nFor each key link, verify the connection exists:\n\n**Pattern: Component → API**\n```powershell\n# Check Chat.tsx calls /api/chat\nSelect-String -Path \"src/components/Chat.tsx\" -Pattern \"fetch.*api/chat\"\n```\n\n**Pattern: API → Database**\n```powershell\n# Check route calls prisma\nSelect-String -Path \"src/app/api/chat/route.ts\" -Pattern \"prisma\\.\"\n```\n\n**Pattern: Form → Handler**\n```powershell\n# Check onSubmit has implementation\nSelect-String -Path \"src/components/Form.tsx\" -Pattern \"onSubmit\" -Context 0,5\n```\n\n**Pattern: State → Render**\n```powershell\n# Check state is used in JSX\nSelect-String -Path \"src/components/Chat.tsx\" -Pattern \"messages\\.map\"\n```\n\n---\n\n### Step 6: Check Requirements Coverage\n\nIf REQUIREMENTS.md exists:\n\n```powershell\nSelect-String -Path \".gsd/REQUIREMENTS.md\" -Pattern \"Phase {N}\"\n```\n\nFor each requirement:\n1. Identify which truths/artifacts support it\n2. Determine status based on supporting infrastructure\n\n**Requirement status:**\n- ✓ SATISFIED: All supporting truths verified\n- ✗ BLOCKED: Supporting truths failed\n- ? NEEDS HUMAN: Can't verify programmatically\n\n---\n\n### Step 7: Scan for Anti-Patterns\n\nRun anti-pattern detection on modified files:\n\n```powershell\n# TODO/FIXME comments\nSelect-String -Path \"src/**/*.ts\" -Pattern \"TODO|FIXME|XXX|HACK\"\n\n# Placeholder content\nSelect-String -Path \"src/**/*.tsx\" -Pattern \"placeholder|coming soon\" \n\n# Empty implementations\nSelect-String -Path \"src/**/*.ts\" -Pattern \"return null|return \\{\\}|return \\[\\]\"\n\n# Console.log only\nSelect-String -Path \"src/**/*.ts\" -Pattern \"console\\.log\" -Context 2\n```\n\n**Categorize findings:**\n- 🛑 Blocker: Prevents goal achievement\n- ⚠️ Warning: Indicates incomplete work\n- ℹ️ Info: Notable but not problematic\n\n---\n\n### Step 8: Identify Human Verification Needs\n\nSome things can't be verified programmatically:\n\n**Always needs human:**\n- Visual appearance (does it look right?)\n- User flow completion\n- Real-time behavior (WebSocket, SSE)\n- External service integration\n- Performance feel\n- Error message clarity\n\n**Format:**\n```markdown\n### 1. {Test Name}\n**Test:** {What to do}\n**Expected:** {What should happen}\n**Why human:** {Why can't verify programmatically}\n```\n\n---\n\n### Step 9: Determine Overall Status\n\n**Status: passed**\n- All truths VERIFIED\n- All artifacts pass levels 1-3\n- All key links WIRED\n- No blocker anti-patterns\n\n**Status: gaps_found**\n- One or more truths FAILED\n- OR artifacts MISSING/STUB\n- OR key links NOT_WIRED\n- OR blocker anti-patterns found\n\n**Status: human_needed**\n- All automated checks pass\n- BUT items flagged for human verification\n\n**Calculate score:**\n```\nscore = verified_truths / total_truths\n```\n\n---\n\n### Step 10: Structure Gap Output\n\nWhen gaps found, structure for `/plan --gaps`:\n\n```yaml\n---\nphase: {N}\nverified: {timestamp}\nstatus: gaps_found\nscore: {N}/{M} must-haves verified\ngaps:\n - truth: \"User can see existing messages\"\n status: failed\n reason: \"Chat.tsx doesn't fetch from API\"\n artifacts:\n - path: \"src/components/Chat.tsx\"\n issue: \"No useEffect with fetch call\"\n missing:\n - \"API call in useEffect to /api/chat\"\n - \"State for storing fetched messages\"\n - \"Render messages array in JSX\"\n---\n```\n\n---\n\n## Stub Detection Patterns\n\n### Universal Stub Patterns\n```powershell\n# Comment-based stubs\nSelect-String -Pattern \"TODO|FIXME|XXX|HACK|PLACEHOLDER\"\n\n# Placeholder text\nSelect-String -Pattern \"placeholder|lorem ipsum|coming soon\" \n\n# Empty implementations\nSelect-String -Pattern \"return null|return undefined|return \\{\\}|return \\[\\]\"\n```\n\n### React Component Stubs\n```javascript\n// RED FLAGS:\nreturn
Component
\nreturn
Placeholder
\nreturn
{/* TODO */}
\nreturn null\nreturn <>\n\n// Empty handlers:\nonClick={() => {}}\nonChange={() => console.log('clicked')}\nonSubmit={(e) => e.preventDefault()} // Only prevents default\n```\n\n### API Route Stubs\n```typescript\n// RED FLAGS:\nexport async function POST() {\n return Response.json({ message: \"Not implemented\" });\n}\n\nexport async function GET() {\n return Response.json([]); // Empty array, no DB query\n}\n\n// Console log only:\nexport async function POST(req) {\n console.log(await req.json());\n return Response.json({ ok: true });\n}\n```\n\n### Wiring Red Flags\n```typescript\n// Fetch exists but response ignored:\nfetch('/api/messages') // No await, no .then\n\n// Query exists but result not returned:\nawait prisma.message.findMany()\nreturn Response.json({ ok: true }) // Returns static, not query\n\n// Handler only prevents default:\nonSubmit={(e) => e.preventDefault()}\n\n// State exists but not rendered:\nconst [messages, setMessages] = useState([])\nreturn
No messages
// Always shows static\n```\n\n---\n\n## VERIFICATION.md Format\n\n```markdown\n---\nphase: {N}\nverified: {timestamp}\nstatus: {passed | gaps_found | human_needed}\nscore: {N}/{M} must-haves verified\nis_re_verification: {true | false}\ngaps: [...] # If gaps_found\n---\n\n# Phase {N} Verification\n\n## Must-Haves\n\n### Truths\n| Truth | Status | Evidence |\n|-------|--------|----------|\n| {truth 1} | ✓ VERIFIED | {how verified} |\n| {truth 2} | ✗ FAILED | {what's missing} |\n\n### Artifacts\n| Path | Exists | Substantive | Wired |\n|------|--------|-------------|-------|\n| src/components/Chat.tsx | ✓ | ✓ | ✗ |\n\n### Key Links\n| From | To | Via | Status |\n|------|-----|-----|--------|\n| Chat.tsx | api/chat | fetch | ✗ NOT_WIRED |\n\n## Anti-Patterns Found\n- 🛑 {blocker}\n- ⚠️ {warning}\n\n## Human Verification Needed\n### 1. Visual Review\n**Test:** Open http://localhost:3000/chat\n**Expected:** Message list renders with real data\n**Why human:** Visual layout verification\n\n## Gaps (if any)\n{Structured gap analysis for planner}\n\n## Verdict\n{Status explanation}\n```\n\n---\n\n## Success Criteria\n\n- [ ] Previous VERIFICATION.md checked\n- [ ] Must-haves established (from frontmatter or derived)\n- [ ] All truths verified with status and evidence\n- [ ] All artifacts checked at 3 levels (exists, substantive, wired)\n- [ ] All key links verified\n- [ ] Anti-patterns scanned and categorized\n- [ ] Human verification items identified\n- [ ] Overall status determined\n- [ ] Gaps structured in YAML (if gaps_found)\n- [ ] VERIFICATION.md created\n- [ ] Results returned to orchestrator\n" }, { "path": ".gemini/GEMINI.md", "content": "# GSD Methodology — Mission Control Rules\n\n> **Get Shit Done**: A spec-driven, context-engineered development methodology.\n> \n> These rules enforce disciplined, high-quality autonomous development.\n\n---\n\n## Canonical Rules\n\n**All canonical rules are in [PROJECT_RULES.md](../PROJECT_RULES.md).**\n\nThis file provides Gemini-specific integration. For the complete methodology, see PROJECT_RULES.md.\n\n---\n\n## Core Principles\n\n1. **Plan Before You Build** — No code without specification\n2. **State Is Sacred** — Every action updates persistent memory\n3. **Context Is Limited** — Prevent degradation through hygiene\n4. **Verify Empirically** — No \"trust me, it works\"\n\n---\n\n## Quick Reference\n\n```\nBefore coding → Check SPEC.md is FINALIZED\nBefore file read → Search first, then targeted read\nAfter each task → Update STATE.md\nAfter 3 failures → State dump + fresh session\nBefore \"Done\" → Empirical proof captured\n```\n\n---\n\n## Workflow Integration\n\nThese rules integrate with the GSD workflows:\n\n| Workflow | Rules Enforced |\n|----------|----------------|\n| `/map` | Updates ARCHITECTURE.md, STACK.md |\n| `/plan` | Enforces Planning Lock, creates ROADMAP |\n| `/execute` | Enforces State Persistence after each task |\n| `/verify` | Enforces Empirical Validation |\n| `/pause` | Triggers Context Hygiene state dump |\n| `/resume` | Loads state from STATE.md |\n\n---\n\n## Gemini-Specific Tips\n\nFor Gemini-specific enhancements, see [adapters/GEMINI.md](../adapters/GEMINI.md).\n\nKey recommendations:\n- **Flash** for quick iterations and simple edits\n- **Pro** for complex planning and analysis\n- Large context is available but **search-first** still applies\n\n---\n\n*GSD Methodology adapted for Google Antigravity*\n*Canonical rules: [PROJECT_RULES.md](../PROJECT_RULES.md)*\n*Source: https://github.com/glittercowboy/get-shit-done*\n\n" }, { "path": ".gitignore", "content": "# GSD State Files\n.gsd/ARCHITECTURE.md\n.gsd/DECISIONS.md\n.gsd/JOURNAL.md\n.gsd/ROADMAP.md\n.gsd/SPEC.md\n.gsd/STACK.md\n.gsd/STATE.md\n.gsd/TODO.md\n\n# OS generated\nThumbs.db\n.DS_Store\n" }, { "path": ".gsd/examples/cross-platform.md", "content": "# Cross-Platform Commands Reference\n\n> PowerShell ↔ Bash equivalents for GSD workflows\n\n## Common Operations\n\n| Operation | PowerShell | Bash |\n|-----------|------------|------|\n| **Test file exists** | `Test-Path \"file.md\"` | `test -f \"file.md\"` |\n| **Test directory exists** | `Test-Path \"dir\" -PathType Container` | `test -d \"dir\"` |\n| **Create directory** | `New-Item -ItemType Directory -Path \"dir\"` | `mkdir -p \"dir\"` |\n| **List files** | `Get-ChildItem \"*.md\"` | `ls *.md` |\n| **List recursively** | `Get-ChildItem -Recurse` | `find . -type f` |\n| **Read file** | `Get-Content \"file.md\"` | `cat \"file.md\"` |\n| **Search in files** | `Select-String -Path \"**/*\" -Pattern \"TODO\"` | `grep -r \"TODO\" .` |\n| **Count lines** | `(Get-Content file).Count` | `wc -l < file` |\n| **Copy files** | `Copy-Item -Recurse src dest` | `cp -r src dest` |\n| **Delete files** | `Remove-Item -Recurse -Force dir` | `rm -rf dir` |\n\n## Git Operations (Same on Both)\n\n```bash\ngit add -A\ngit commit -m \"message\"\ngit push\ngit status --short\n```\n\n## Workflow-Specific Examples\n\n### /map — Analyze Codebase\n\n**PowerShell:**\n```powershell\nGet-ChildItem -Recurse -Directory | \n Where-Object { $_.Name -notmatch \"node_modules|\\.git\" }\n```\n\n**Bash:**\n```bash\nfind . -type d ! -path \"*/node_modules/*\" ! -path \"*/.git/*\"\n```\n\n---\n\n### /plan — Check SPEC Status\n\n**PowerShell:**\n```powershell\n$spec = Get-Content \".gsd/SPEC.md\" -Raw\nif ($spec -match \"FINALIZED\") { \"Ready\" }\n```\n\n**Bash:**\n```bash\nif grep -q \"FINALIZED\" .gsd/SPEC.md; then echo \"Ready\"; fi\n```\n\n---\n\n### /execute — Discover Plans\n\n**PowerShell:**\n```powershell\nGet-ChildItem \".gsd/phases/1/*-PLAN.md\"\n```\n\n**Bash:**\n```bash\nls .gsd/phases/1/*-PLAN.md 2>/dev/null\n```\n\n---\n\n### /verify — Search TODOs\n\n**PowerShell:**\n```powershell\nSelect-String -Path \"src/**/*\" -Pattern \"TODO|FIXME\"\n```\n\n**Bash:**\n```bash\ngrep -rn \"TODO\\|FIXME\" src/\n```\n\n---\n\n## Environment Detection\n\nAdd this to workflows for cross-platform commands:\n\n```markdown\n**Note:** Commands shown are PowerShell. For Bash equivalents, see `.gsd/examples/cross-platform.md`\n```\n\n---\n\n*Reference for Linux/Mac users*\n" }, { "path": ".gsd/examples/multi-wave-workflow.md", "content": "# Multi-Wave Workflow Example\n\nThis example demonstrates a complete GSD workflow with:\n- Short spec\n- Plan breakdown\n- 2-wave execution\n- Verification with commands\n- State snapshots\n\n---\n\n## Example: Add User Authentication\n\n### 1. SPEC.md (Finalized)\n\n```markdown\n---\nstatus: FINALIZED\nupdated: 2026-02-07\n---\n\n# User Authentication Feature\n\n## Overview\nAdd login/logout functionality with JWT tokens.\n\n## Requirements\n1. POST /api/auth/login endpoint\n2. POST /api/auth/logout endpoint\n3. JWT stored in httpOnly cookie\n4. Protected route middleware\n\n## Success Criteria\n- User can login with email/password\n- Invalid credentials return 401\n- Protected routes require valid JWT\n- Logout clears the cookie\n```\n\n---\n\n### 2. ROADMAP.md (Phase Entry)\n\n```markdown\n## Phase 1: User Authentication\n\n- [ ] Plan 1.1: Auth endpoints (Wave 1)\n- [ ] Plan 1.2: Protected middleware (Wave 2)\n```\n\n---\n\n### 3. PLAN 1.1 (Wave 1)\n\n```xml\n---\nphase: 1\nplan: 1\ntype: implementation\nwave: 1\n---\n\n\nCreate login and logout endpoints with JWT handling.\n\n\n\nFiles to read: src/app/api/ structure, existing auth if any\n\n\n\n\n Create login endpoint\n src/app/api/auth/login/route.ts\n \n Create POST handler accepting {email, password}.\n Query users table, compare password with bcrypt.\n On success: generate JWT, set httpOnly cookie, return 200.\n On failure: return 401 with generic error.\n \n curl -X POST localhost:3000/api/auth/login -d '{\"email\":\"test@example.com\",\"password\":\"test123\"}'\n Valid credentials return 200 + Set-Cookie header\n\n\n\n Create logout endpoint\n src/app/api/auth/logout/route.ts\n \n Create POST handler that clears the auth cookie.\n Return 200 on success.\n \n curl -X POST localhost:3000/api/auth/logout --cookie \"token=...\"\n Cookie is cleared, response is 200\n\n\n```\n\n---\n\n### 4. Wave 1 Execution\n\n**Task 1 Commit:**\n```\ngit commit -m \"feat(phase-1): create login endpoint\"\n```\n\n**Task 2 Commit:**\n```\ngit commit -m \"feat(phase-1): create logout endpoint\"\n```\n\n---\n\n### 5. Wave 1 State Snapshot\n\n```markdown\n---\nwave: 1\nphase: 1\ncreated: 2026-02-07T10:30:00\nstatus: complete\n---\n\n# Wave 1 State Snapshot\n\n## Objective\nCreate authentication endpoints.\n\n## Changes Realized\n- Created login endpoint with JWT generation\n- Created logout endpoint with cookie clearing\n- Added bcrypt password comparison\n\n## Files Touched\n| File | Change Type | Description |\n|------|-------------|-------------|\n| src/app/api/auth/login/route.ts | created | Login handler |\n| src/app/api/auth/logout/route.ts | created | Logout handler |\n\n## Verification Results\n| Check | Command | Result |\n|-------|---------|--------|\n| Login works | `curl -X POST .../login` | ✅ 200 + cookie |\n| Logout works | `curl -X POST .../logout` | ✅ 200 + cleared |\n\n## Commits in This Wave\n| Hash | Message |\n|------|---------|\n| abc123 | feat(phase-1): create login endpoint |\n| def456 | feat(phase-1): create logout endpoint |\n\n## TODO for Next Wave\n1. Create auth middleware\n2. Apply to protected routes\n```\n\n---\n\n### 6. PLAN 1.2 (Wave 2)\n\n```xml\n---\nphase: 1\nplan: 2\ntype: implementation\nwave: 2\ndepends_on: [1]\n---\n\n\nCreate middleware to protect routes requiring authentication.\n\n\n\nWave 1 complete: login/logout endpoints exist.\nJWT is stored in httpOnly cookie named \"token\".\n\n\n\n\n Create auth middleware\n src/middleware/auth.ts\n \n Create middleware that:\n 1. Reads JWT from cookie\n 2. Verifies signature with jose\n 3. Attaches user to request\n 4. Returns 401 if invalid/missing\n \n Import and call middleware with mock request\n Valid JWT passes, invalid/missing returns 401\n\n\n\n Apply middleware to protected route\n src/app/api/user/profile/route.ts\n \n Create example protected route.\n Apply auth middleware.\n Return user data if authenticated.\n \n curl localhost:3000/api/user/profile with and without cookie\n With cookie: 200 + data. Without: 401\n\n\n```\n\n---\n\n### 7. Wave 2 Execution & Snapshot\n\n**Commits:**\n```\ngit commit -m \"feat(phase-1): create auth middleware\"\ngit commit -m \"feat(phase-1): apply middleware to profile route\"\n```\n\n**State Snapshot:** (similar format to Wave 1)\n\n---\n\n### 8. Verification\n\n```bash\n# Full verification sequence\ncurl -X POST localhost:3000/api/auth/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\":\"user@example.com\",\"password\":\"secret\"}' \\\n -c cookies.txt\n\n# Expected: 200 + Set-Cookie: token=...\n\ncurl localhost:3000/api/user/profile -b cookies.txt\n# Expected: 200 + user data\n\ncurl localhost:3000/api/user/profile\n# Expected: 401\n\ncurl -X POST localhost:3000/api/auth/logout -b cookies.txt\n# Expected: 200 + cookie cleared\n```\n\n---\n\n## Key Takeaways\n\n1. **Waves group dependent work** — Wave 2 waited for Wave 1\n2. **State snapshots preserve context** — Each wave ends with documented state\n3. **Atomic commits per task** — Easy to trace and revert\n4. **Verification built into plan** — No \"trust me, it works\"\n5. **Effort hints model selection** — `high` effort = use reasoning model\n\n---\n\n*See PROJECT_RULES.md for wave execution rules.*\n*See templates/state_snapshot.md for snapshot format.*\n" }, { "path": ".gsd/examples/quick-reference.md", "content": "# GSD Quick Reference Card\n\n## Workflow Lifecycle\n\n```\n┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐\n│ /map │ → │ /plan │ → │ /execute │ → │ /verify │\n│ │ │ │ │ │ │ │\n│ Analyze │ │ Create │ │ Run │ │ Check │\n│codebase │ │ phases │ │ tasks │ │ work │\n└─────────┘ └─────────┘ └──────────┘ └─────────┘\n ↑ │\n └──────────────┘\n (if gaps found)\n```\n\n## All Commands\n\n| Command | Args | Purpose |\n|---------|------|---------|\n| `/map` | - | Analyze codebase → ARCHITECTURE.md |\n| `/plan` | `[phase]` | Create PLAN.md files for phase |\n| `/execute` | `phase [--gaps-only]` | Run plans with wave execution |\n| `/verify` | `phase` | Validate with empirical proof |\n| `/debug` | `description` | Systematic debugging |\n| `/progress` | - | Show current position |\n| `/pause` | - | Save state, end session |\n| `/resume` | - | Load state, start session |\n| `/add-todo` | `item [--priority]` | Quick capture |\n| `/check-todos` | `[--all]` | List pending items |\n\n## Core Rules\n\n| Rule | Enforcement |\n|------|-------------|\n| 🔒 Planning Lock | No code until SPEC finalized |\n| 💾 State Persistence | Update STATE.md after tasks |\n| 🧹 Context Hygiene | 3 failures → fresh session |\n| ✅ Empirical Validation | Proof required for \"done\" |\n\n## Key Files\n\n| File | Purpose | Updated By |\n|------|---------|------------|\n| SPEC.md | Vision (finalize first!) | User |\n| ROADMAP.md | Phase definitions | /plan |\n| STATE.md | Session memory | All |\n| ARCHITECTURE.md | System design | /map |\n| TODO.md | Quick capture | /add-todo |\n\n## XML Task Structure\n\n```xml\n\n Clear name\n exact/path.ts\n Specific instructions\n Executable command\n Measurable criteria\n\n```\n\n## Priority Indicators\n\n| Priority | Icon |\n|----------|------|\n| High | 🔴 |\n| Medium | 🟡 |\n| Low | 🟢 |\n\n---\n\n*Print this for quick reference!*\n" }, { "path": ".gsd/examples/workflow-example.md", "content": "# GSD Workflow Example\n\n> A complete walkthrough of using GSD from start to finish.\n\n## Scenario: Building a Simple Todo API\n\n### Step 1: Define the Spec\n\nFirst, fill out `.gsd/SPEC.md`:\n\n```markdown\n# SPEC.md\n\n> **Status**: `FINALIZED`\n\n## Vision\nA simple RESTful API for managing todo items.\n\n## Goals\n1. CRUD operations for todos\n2. Persistence to SQLite\n3. Input validation\n\n## Success Criteria\n- [ ] POST /todos creates a todo\n- [ ] GET /todos returns list\n- [ ] DELETE /todos/:id removes item\n```\n\n---\n\n### Step 2: Map the Codebase (if existing)\n\n```\n/map\n```\n\nThis creates:\n- `.gsd/ARCHITECTURE.md` — Current structure\n- `.gsd/STACK.md` — Technologies in use\n\n---\n\n### Step 3: Plan the Phases\n\n```\n/plan 1\n```\n\nGSD analyzes the SPEC and creates `.gsd/phases/1/` with PLAN.md files:\n\n```markdown\n# Plan 1.1: Database Setup\n\n## Objective\nCreate SQLite database with todos table.\n\n## Tasks\n\n\n Initialize SQLite database\n src/db.ts\n \n Create SQLite connection using better-sqlite3.\n Create todos table with: id, title, completed, created_at.\n \n node -e \"require('./src/db')\" exits without error\n Database file exists, table created\n\n```\n\n---\n\n### Step 4: Execute the Phase\n\n```\n/execute 1\n```\n\nGSD:\n1. Loads Plan 1.1\n2. Executes tasks in order\n3. Runs verify commands\n4. Creates atomic commits\n5. Creates SUMMARY.md\n6. Proceeds to Plan 1.2\n7. Verifies phase goal\n\n---\n\n### Step 5: Verify the Work\n\n```\n/verify 1\n```\n\nGSD:\n1. Extracts must-haves from phase\n2. Runs verification commands\n3. Captures evidence\n4. Creates VERIFICATION.md\n5. Reports pass/fail\n\n---\n\n### Step 6: Continue or Debug\n\n**If verified:**\n```\n/plan 2 → Plan next phase\n/execute 2 → Execute next phase\n```\n\n**If issues found:**\n```\n/execute 1 --gaps-only → Run fix plans\n/debug \"API returns 500\" → Debug the issue\n```\n\n---\n\n## Quick Commands Reference\n\n| Command | When to Use |\n|---------|-------------|\n| `/map` | Analyze existing codebase |\n| `/plan [N]` | Create plans for phase N |\n| `/execute [N]` | Run all plans in phase N |\n| `/verify [N]` | Confirm phase N works |\n| `/debug [issue]` | Fix a problem |\n| `/progress` | See current status |\n| `/pause` | End session, save state |\n| `/resume` | Start new session |\n| `/add-todo` | Capture quick idea |\n| `/check-todos` | See pending items |\n\n---\n\n*This example demonstrates the GSD methodology flow.*\n" }, { "path": ".gsd/templates/DEBUG.md", "content": "# Debug Template\n\nTemplate for `.gsd/debug/[slug].md` — active debug session tracking.\n\n---\n\n## File Template\n\n```markdown\n---\nstatus: gathering | investigating | fixing | verifying | resolved\ntrigger: \"[verbatim user input]\"\ncreated: [ISO timestamp]\nupdated: [ISO timestamp]\n---\n\n## Current Focus\n\n\nhypothesis: [current theory being tested]\ntest: [how testing it]\nexpecting: [what result means if true/false]\nnext_action: [immediate next step]\n\n## Symptoms\n\n\nexpected: [what should happen]\nactual: [what actually happens]\nerrors: [error messages if any]\nreproduction: [how to trigger]\nstarted: [when it broke / always broken]\n\n## Eliminated\n\n\n- hypothesis: [theory that was wrong]\n evidence: [what disproved it]\n timestamp: [when eliminated]\n\n## Evidence\n\n\n- timestamp: [when found]\n checked: [what was examined]\n found: [what was observed]\n implication: [what this means]\n\n## Resolution\n\n\nroot_cause: [empty until found]\nfix: [empty until applied]\nverification: [empty until verified]\nfiles_changed: []\n```\n\n---\n\n## Section Rules\n\n**Frontmatter (status, trigger, timestamps):**\n- `status`: OVERWRITE - reflects current phase\n- `trigger`: IMMUTABLE - verbatim user input, never changes\n- `created`: IMMUTABLE - set once\n- `updated`: OVERWRITE - update on every change\n\n**Current Focus:**\n- OVERWRITE entirely on each update\n- Always reflects what AI is doing RIGHT NOW\n- If AI reads this after session reset, it knows exactly where to resume\n- Fields: hypothesis, test, expecting, next_action\n\n**Symptoms:**\n- Written during initial gathering phase\n- IMMUTABLE after gathering complete\n- Reference point for what we're trying to fix\n\n**Eliminated:**\n- APPEND only - never remove entries\n- Prevents re-investigating dead ends after context reset\n- Critical for efficiency across session boundaries\n\n**Evidence:**\n- APPEND only - never remove entries\n- Facts discovered during investigation\n- Builds the case for root cause\n\n**Resolution:**\n- OVERWRITE as understanding evolves\n- Final state shows confirmed root cause and verified fix\n\n---\n\n## Lifecycle\n\n**Creation:** When /debug is called\n- Create file with trigger from user input\n- Set status to \"gathering\"\n- next_action = \"gather symptoms\"\n\n**During investigation:**\n- OVERWRITE Current Focus with each hypothesis\n- APPEND to Evidence with each finding\n- APPEND to Eliminated when hypothesis disproved\n\n**On resolution:**\n- status → \"resolved\"\n- Move file to .gsd/debug/resolved/\n\n---\n\n## Resume Behavior\n\nWhen AI reads this file after session reset:\n\n1. Parse frontmatter → know status\n2. Read Current Focus → know exactly what was happening\n3. Read Eliminated → know what NOT to retry\n4. Read Evidence → know what's been learned\n5. Continue from next_action\n\nThe file IS the debugging brain.\n" }, { "path": ".gsd/templates/PLAN.md", "content": "# PLAN.md Template\n\n> Copy this template when creating execution plans.\n\n```markdown\n---\nphase: {N}\nplan: {M}\nwave: {W}\ngap_closure: false\n---\n\n# Plan {N}.{M}: {Descriptive Name}\n\n## Objective\n{One paragraph explaining what this plan delivers and why it matters}\n\n## Context\nLoad these files for context:\n- .gsd/SPEC.md\n- .gsd/ARCHITECTURE.md\n- {relevant source files}\n\n## Tasks\n\n\n {Clear, specific task name}\n \n {exact/file/path1.ext}\n {exact/file/path2.ext}\n \n \n {Specific implementation instructions}\n \n Steps:\n 1. {Step 1}\n 2. {Step 2}\n 3. {Step 3}\n \n AVOID: {common mistake} because {reason}\n USE: {preferred approach} because {reason}\n \n \n {Executable command or check}\n Example: npm test -- --testNamePattern=\"auth\"\n Example: curl -X POST localhost:3000/api/login\n \n \n {Measurable acceptance criteria}\n Example: Valid credentials → 200 + Set-Cookie, invalid → 401\n \n\n\n\n {Task 2 name}\n {files}\n {instructions}\n {command}\n {criteria}\n\n\n## Must-Haves\nAfter all tasks complete, verify:\n- [ ] {Must-have 1 — derived from phase goal}\n- [ ] {Must-have 2}\n\n## Success Criteria\n- [ ] All tasks verified passing\n- [ ] Must-haves confirmed\n- [ ] No regressions in tests\n```\n\n## Task Types\n\n| Type | Use For | Behavior |\n|------|---------|----------|\n| `auto` | Everything Claude can do independently | Fully autonomous |\n| `checkpoint:human-verify` | Visual/functional verification | Pauses for user |\n| `checkpoint:decision` | Implementation choices | Pauses for user |\n\n## Wave Assignment\n\n| Wave | Use For |\n|------|---------|\n| 1 | Foundation (types, schemas, utilities) |\n| 2 | Core implementations |\n| 3 | Integration and validation |\n\nPlans in the same wave can run in parallel.\nLater waves depend on earlier waves.\n" }, { "path": ".gsd/templates/RESEARCH.md", "content": "# RESEARCH.md Template\n\n> Copy this template when documenting phase research.\n\n```markdown\n---\nphase: {N}\nresearched_at: {YYYY-MM-DD}\ndiscovery_level: 1 | 2 | 3\n---\n\n# Phase {N} Research\n\n## Objective\n{What question is this research answering?}\n\n## Discovery Level\n**Level {1|2|3}** — {Quick verification | Standard research | Deep dive}\n\n## Key Decisions\n\n### Decision 1: {Topic}\n**Question:** {What needed to be decided?}\n**Options Considered:**\n1. {Option A}: {pros/cons}\n2. {Option B}: {pros/cons}\n3. {Option C}: {pros/cons}\n\n**Decision:** {Which option and why}\n**Confidence:** {High | Medium | Low}\n\n### Decision 2: {Topic}\n...\n\n## Findings\n\n### {Topic 1}\n{What was learned}\n\n**Sources:**\n- {URL or reference}\n- {URL or reference}\n\n### {Topic 2}\n{What was learned}\n\n## Patterns to Follow\n- {Pattern 1}: {How to apply it}\n- {Pattern 2}: {How to apply it}\n\n## Anti-Patterns to Avoid\n- {Anti-pattern 1}: {Why to avoid}\n- {Anti-pattern 2}: {Why to avoid}\n\n## Dependencies Identified\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {pkg} | {ver} | {why needed} |\n\n## Risks\n- **{Risk 1}:** {Impact and mitigation}\n- **{Risk 2}:** {Impact and mitigation}\n\n## Recommendations for Planning\n1. {Recommendation 1}\n2. {Recommendation 2}\n```\n\n## Discovery Levels\n\n| Level | Time | Use When |\n|-------|------|----------|\n| 1 | 2-5 min | Single known library, confirming syntax |\n| 2 | 15-30 min | Choosing between options, new integration |\n| 3 | 1+ hour | Architectural decision, novel problem |\n" }, { "path": ".gsd/templates/SUMMARY.md", "content": "# Summary Template\n\nTemplate for `.gsd/phases/{N}/{plan}-SUMMARY.md` — execution summary after plan completion.\n\n---\n\n## File Template\n\n```markdown\n---\nphase: {N}\nplan: {M}\ncompleted_at: [ISO timestamp]\nduration_minutes: {N}\nstatus: complete | partial | failed\n---\n\n# Summary: {Plan Name}\n\n## Results\n\n- **Tasks:** {N}/{M} completed\n- **Commits:** {N}\n- **Verification:** {passed | failed}\n\n---\n\n## Tasks Completed\n\n| Task | Description | Commit | Status |\n|------|-------------|--------|--------|\n| 1 | {task name} | {hash} | ✅ Complete |\n| 2 | {task name} | {hash} | ✅ Complete |\n| 3 | {task name} | — | ❌ Blocked |\n\n---\n\n## Files Changed\n\n| File | Change Type | Description |\n|------|-------------|-------------|\n| {path} | Created | {what it does} |\n| {path} | Modified | {what changed} |\n| {path} | Deleted | {why removed} |\n\n---\n\n## Deviations Applied\n\n{If none: \"None — executed as planned.\"}\n\n### Rule 1 — Bug Fixes\n- {description of bug fixed}\n\n### Rule 2 — Missing Critical\n- {description of functionality added}\n\n### Rule 3 — Blocking Issues\n- {description of blocker fixed}\n\n---\n\n## Verification\n\n| Check | Status | Evidence |\n|-------|--------|----------|\n| {verification 1} | ✅ Pass | {command/output} |\n| {verification 2} | ✅ Pass | {command/output} |\n\n---\n\n## Notes\n\n{Any observations, concerns, or recommendations for future phases}\n\n---\n\n## Metadata\n\n- **Started:** {timestamp}\n- **Completed:** {timestamp}\n- **Duration:** {N} minutes\n- **Context Usage:** ~{N}%\n```\n\n---\n\n## Guidelines\n\n**Create SUMMARY.md:**\n- After each plan completes\n- Before moving to next plan\n- Even if plan failed (document what happened)\n\n**Include:**\n- All commits with hashes\n- All deviations (never hide these)\n- Verification results with evidence\n\n**Keep it factual:**\n- No opinions\n- Just what happened\n- Evidence over claims\n" }, { "path": ".gsd/templates/UAT.md", "content": "# UAT Template\n\nTemplate for `.gsd/phases/{N}/UAT.md` — User Acceptance Testing checklist.\n\n**Purpose:** Structured manual testing protocol for human verification checkpoints.\n\n---\n\n## File Template\n\n```markdown\n---\nphase: {N}\ntype: uat\ncreated: [ISO timestamp]\nstatus: pending | in_progress | passed | failed\n---\n\n# Phase {N} UAT\n\n## Overview\n\n**Phase:** {name}\n**Goal:** {what this phase delivers}\n**Tester:** User\n**Date:** {date}\n\n---\n\n## Test Environment\n\n**Setup Required:**\n- [ ] Dev server running (`npm run dev`)\n- [ ] Database seeded with test data\n- [ ] Browser dev tools open for error monitoring\n\n**Test Data:**\n- User: test@example.com / password123\n- Other relevant test accounts/data\n\n---\n\n## Test Cases\n\n### TC-01: {Test Case Name}\n\n**Scenario:** {What user is trying to do}\n\n**Steps:**\n1. {Step 1}\n2. {Step 2}\n3. {Step 3}\n\n**Expected Result:**\n- {What should happen}\n\n**Actual Result:**\n- [ ] PASS\n- [ ] FAIL — Issue: ___\n\n---\n\n### TC-02: {Test Case Name}\n\n**Scenario:** {What user is trying to do}\n\n**Steps:**\n1. {Step 1}\n2. {Step 2}\n\n**Expected Result:**\n- {What should happen}\n\n**Actual Result:**\n- [ ] PASS\n- [ ] FAIL — Issue: ___\n\n---\n\n## Edge Cases\n\n### EC-01: {Edge Case Name}\n\n**Test:** {What to try}\n**Expected:** {Graceful handling}\n**Result:** [ ] PASS [ ] FAIL\n\n---\n\n## Error Scenarios\n\n### ERR-01: {Error Scenario}\n\n**Trigger:** {How to cause error}\n**Expected Behavior:** {Error message, recovery}\n**Result:** [ ] PASS [ ] FAIL\n\n---\n\n## Visual Verification\n\n### VIS-01: Layout\n\n- [ ] Responsive on mobile (375px)\n- [ ] Responsive on tablet (768px)\n- [ ] Desktop layout correct (1024px+)\n- [ ] No horizontal scroll\n- [ ] All text readable\n\n### VIS-02: Styling\n\n- [ ] Colors match design system\n- [ ] Fonts correct\n- [ ] Spacing consistent\n- [ ] Icons display correctly\n\n---\n\n## Summary\n\n| Category | Pass | Fail | Total |\n|----------|------|------|-------|\n| Functional | | | |\n| Edge Cases | | | |\n| Errors | | | |\n| Visual | | | |\n\n**Overall Status:** [ ] APPROVED [ ] NEEDS FIXES\n\n**Issues Found:**\n1. {Issue description}\n2. {Issue description}\n\n**Notes:**\n{Any additional observations}\n```\n\n---\n\n## Usage Guidelines\n\n**When to create UAT:**\n- After phase execution complete\n- Before marking phase as verified\n- For any `checkpoint:human-verify` tasks\n\n**Who runs UAT:**\n- User (always)\n- AI cannot verify visual/UX elements\n\n**After UAT:**\n- If PASSED: Phase can be marked complete\n- If FAILED: Create gap closure plans with `/plan-milestone-gaps`\n\n---\n\n## Test Case Guidelines\n\n**Good test cases:**\n- Specific, reproducible steps\n- Clear expected results\n- One scenario per test case\n\n**Categories to cover:**\n1. Happy path (main functionality)\n2. Edge cases (boundary conditions)\n3. Error handling (invalid input, failures)\n4. Visual/UX (layout, responsiveness)\n" }, { "path": ".gsd/templates/VERIFICATION.md", "content": "# VERIFICATION.md Template\n\n> Copy this template when creating phase verification reports.\n\n```markdown\n---\nphase: {N}\nverified_at: {YYYY-MM-DD HH:MM}\nverdict: PASS | FAIL | PARTIAL\npass_count: {X}\ntotal_count: {Y}\n---\n\n# Phase {N} Verification Report\n\n## Summary\n\n**{X}/{Y}** must-haves verified\n**Verdict:** {PASS | FAIL | PARTIAL}\n\n## Must-Haves\n\n### ✅ 1. {Must-have description}\n**Status:** PASS\n**Method:** {How this was verified}\n**Evidence:**\n```\n{Actual command output or screenshot reference}\n```\n\n### ❌ 2. {Must-have description}\n**Status:** FAIL\n**Method:** {How this was verified}\n**Expected:** {What should happen}\n**Actual:** {What actually happened}\n**Evidence:**\n```\n{Actual command output}\n```\n**Gap:** {What needs to be fixed}\n\n### ⏭️ 3. {Must-have description}\n**Status:** SKIPPED\n**Reason:** {Why this couldn't be verified}\n\n## Gap Closure Required\n\n{If verdict is FAIL or PARTIAL, list what needs fixing}\n\n1. **{Gap 1}:** {Description of what's wrong and how to fix}\n2. **{Gap 2}:** {Description}\n\n## Next Steps\n\n{Based on verdict}\n\n- If PASS: Proceed to next phase\n- If FAIL: Run `/execute {N} --gaps-only` after fixing\n- If PARTIAL: Address gaps then re-verify\n```\n\n## Evidence Types\n\n| Verification | Evidence Required |\n|--------------|-------------------|\n| API endpoint | curl command + response |\n| UI behavior | Screenshot |\n| Test suite | Test output |\n| File exists | `ls` or `dir` output |\n| Build passes | Build command output |\n" }, { "path": ".gsd/templates/architecture.md", "content": "# Architecture\n\n> Auto-generated by /map on \n\n## Overview\n\n{Brief description of the system and its purpose.}\n\n```\n┌───────────────────────────────────────────────────────────────┐\n│ USER │\n└────────────────────────┬──────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────┐\n│ COMPONENT A │\n└────────────────────────┬──────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────┐\n│ COMPONENT B │\n└───────────────────────────────────────────────────────────────┘\n```\n\n## Components\n\n### Component A\n- **Purpose:** {What this component does}\n- **Location:** `{path/to/component}`\n- **Files:** {count} files\n- **Pattern:** {architectural pattern used}\n\n| File | Purpose | Priority |\n|------|---------|----------|\n| file1 | {purpose} | {high/medium/low} |\n| file2 | {purpose} | {high/medium/low} |\n\n### Component B\n- **Purpose:** {What this component does}\n- **Location:** `{path/to/component}`\n\n## Data Flow\n\n1. **User initiates action** (e.g., {example})\n2. **Component A processes** {what happens}\n3. **Component B receives** {what happens}\n4. **Result returned** to user\n\n## Technical Debt\n\n- [ ] {Identified debt item 1}\n- [ ] {Identified debt item 2}\n- [ ] {Identified debt item 3}\n\n## Conventions\n\n**Naming:**\n- {Convention 1}\n- {Convention 2}\n\n**Structure:**\n- {Convention 1}\n- {Convention 2}\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/context.md", "content": "# Context Template\n\nTemplate for `.gsd/phases/{N}/CONTEXT.md` — user's vision for a phase.\n\n---\n\n## File Template\n\n```markdown\n---\nphase: {N}\nname: {phase-name}\ncreated: [ISO timestamp]\n---\n\n# Phase {N} Context\n\n## Vision\n\n{How the user imagines this phase working — in their words}\n\n## What's Essential\n\nNon-negotiable aspects:\n\n- {Essential 1}\n- {Essential 2}\n- {Essential 3}\n\n## What's Flexible\n\nOpen to different implementations:\n\n- {Flexible 1}\n- {Flexible 2}\n\n## What's Out of Scope\n\nExplicitly NOT part of this phase:\n\n- {Out of scope 1}\n- {Out of scope 2}\n\n## User Expectations\n\n### Look and Feel\n{How it should appear/behave}\n\n### Performance\n{Speed/responsiveness expectations}\n\n### Integration\n{How it fits with existing work}\n\n## Examples / Inspiration\n\n{Any examples the user referenced}\n\n## Questions Answered\n\nClarifications from /discuss-phase:\n\n| Question | Answer |\n|----------|--------|\n| {question} | {answer} |\n\n## Constraints\n\nTechnical or business constraints:\n\n- {Constraint 1}\n- {Constraint 2}\n```\n\n---\n\n## When to Create\n\nCreated by `/discuss-phase` to capture user's vision before planning.\n\n## How to Use\n\n- Planner reads CONTEXT.md to understand intent\n- Executor honors the vision during implementation\n- Verifier checks against user expectations\n\n## Guidelines\n\n- Capture user's words, not AI interpretation\n- Focus on WHAT, not HOW\n- Keep it short — vision, not specification\n" }, { "path": ".gsd/templates/decisions.md", "content": "# DECISIONS.md — Architecture Decision Records\n\n> **Purpose**: Log significant technical decisions and their rationale.\n\n## Template\n\n```markdown\n## [DECISION-XXX] Title\n\n**Date**: YYYY-MM-DD\n**Status**: Proposed | Accepted | Deprecated | Superseded\n\n### Context\nWhat is the issue we're facing?\n\n### Decision\nWhat have we decided to do?\n\n### Rationale\nWhy did we make this decision?\n\n### Consequences\nWhat are the trade-offs?\n\n### Alternatives Considered\nWhat other options were evaluated?\n```\n\n---\n\n## Decisions\n\n\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/discovery.md", "content": "# Discovery Template\n\nTemplate for `.gsd/phases/{N}/DISCOVERY.md` — shallow research for library/option decisions.\n\n**Purpose:** Answer \"which library/option should we use\" questions during planning.\n\nFor deep ecosystem research, use `/research-phase` which produces RESEARCH.md.\n\n---\n\n## File Template\n\n```markdown\n---\nphase: {N}\ntype: discovery\ntopic: [discovery-topic]\n---\n\n\nDiscover [topic] to inform [phase name] implementation.\n\nPurpose: [What decision/implementation this enables]\nScope: [Boundaries]\nOutput: DISCOVERY.md with recommendation\n\n\n\n\n- [Question to answer]\n- [Area to investigate]\n- [Specific comparison if needed]\n\n\n\n- [Out of scope for this discovery]\n- [Defer to implementation phase]\n\n\n\n\n\n**Source Priority:**\n1. **Official Docs** — Authoritative, current\n2. **Web Search** — For comparisons, trends (verify findings)\n3. **GitHub** — For real usage patterns\n\n**Quality Checklist:**\n- [ ] All claims have authoritative sources\n- [ ] Negative claims verified with official docs\n- [ ] Alternative approaches considered\n- [ ] Recent updates checked for breaking changes\n\n**Confidence Levels:**\n- HIGH: Official docs confirm\n- MEDIUM: Multiple sources confirm\n- LOW: Single source or training knowledge only\n\n\n```\n\n---\n\n## Output Structure\n\nCreate `.gsd/phases/{N}/DISCOVERY.md`:\n\n```markdown\n# [Topic] Discovery\n\n## Summary\n[2-3 paragraph executive summary]\n\n## Primary Recommendation\n[What to do and why — specific and actionable]\n\n## Alternatives Considered\n[What else was evaluated and why not chosen]\n\n## Key Findings\n\n### [Category 1]\n- [Finding with source URL]\n\n### [Category 2]\n- [Finding with relevance]\n\n## Code Examples\n[Relevant patterns if applicable]\n\n## Metadata\n\n\n[Why this confidence level]\n\n\n\n- [Primary sources used]\n\n\n\n[What needs validation during implementation]\n\n```\n\n---\n\n## When to Use\n\n**Use discovery when:**\n- Technology choice unclear (library A vs B)\n- Best practices needed for unfamiliar integration\n- API/library investigation required\n\n**Don't use when:**\n- Established patterns (CRUD, auth with known library)\n- Questions answerable from project context\n\n**Use RESEARCH.md instead when:**\n- Niche/complex domains (3D, games, audio)\n- Need ecosystem knowledge, not just library choice\n- \"How do experts build this\" questions\n" }, { "path": ".gsd/templates/journal.md", "content": "# JOURNAL.md — Session Log\n\n> **Purpose**: Chronicle of work sessions for context continuity.\n\n---\n\n## Sessions\n\n## Session: YYYY-MM-DD HH:MM\n\n### Objective\n{What you set out to accomplish this session.}\n\n### Accomplished\n- ✅ {Task 1 completed}\n- ✅ {Task 2 completed}\n - {Sub-detail if needed}\n- ✅ {Task 3 completed}\n\n### Verification\n- [x] {Verification check 1}\n- [x] {Verification check 2}\n- [ ] {Verification pending}\n\n### Blockers Encountered\n- {Blocker 1 and how it was resolved}\n- {Blocker 2 — still open}\n\n### Handoff Notes\n- {Important context for next session}\n- {Files that need attention}\n- {Decisions that need to be made}\n\n---\n\n## Session: YYYY-MM-DD HH:MM\n\n### Objective\n{Previous session objective.}\n\n### Accomplished\n- ✅ {Completed items}\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/milestone.md", "content": "# Milestone Template\n\nTemplate for `.gsd/milestones/{name}/MILESTONE.md` — milestone definition and tracking.\n\n---\n\n## File Template\n\n```markdown\n---\nname: {milestone-name}\nversion: {semantic version, e.g., v1.0}\nstatus: planning | active | complete | archived\ncreated: [ISO timestamp]\ntarget_date: [optional target]\n---\n\n# Milestone: {name}\n\n## Vision\n\n{What this milestone achieves — one paragraph}\n\n## Must-Haves\n\nNon-negotiable deliverables for this milestone:\n\n- [ ] {Must-have 1}\n- [ ] {Must-have 2}\n- [ ] {Must-have 3}\n\n## Nice-to-Haves\n\nIf time permits:\n\n- [ ] {Nice-to-have 1}\n- [ ] {Nice-to-have 2}\n\n## Phases\n\n| Phase | Name | Status | Objective |\n|-------|------|--------|-----------|\n| 1 | {name} | ⬜ Not Started | {objective} |\n| 2 | {name} | ⬜ Not Started | {objective} |\n| 3 | {name} | ⬜ Not Started | {objective} |\n\n## Success Criteria\n\nHow we know milestone is complete:\n\n- [ ] {Measurable criterion 1}\n- [ ] {Measurable criterion 2}\n\n## Architecture Decisions\n\nKey technical decisions for this milestone:\n\n| Decision | Choice | Rationale |\n|----------|--------|-----------|\n| {decision} | {choice} | {why} |\n\n## Risks\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| {risk} | Low/Med/High | Low/Med/High | {action} |\n\n## Progress Log\n\n| Date | Event | Notes |\n|------|-------|-------|\n| {date} | Milestone started | — |\n```\n\n---\n\n## Lifecycle\n\n1. **Creation:** `/new-milestone` creates this file\n2. **Active:** Updated as phases complete\n3. **Complete:** `/complete-milestone` moves to archive\n4. **Archived:** Read-only reference\n\n---\n\n## Guidelines\n\n- One active milestone at a time\n- 3-5 phases per milestone\n- Must-haves should be testable\n- Success criteria should be measurable\n" }, { "path": ".gsd/templates/phase-summary.md", "content": "# Phase {N} Summary\n\n> **Status**: Complete\n> **Completed**: YYYY-MM-DD\n\n## Objective\n{What this phase set out to accomplish.}\n\n## Deliverables\n\n| Deliverable | Status | Notes |\n|-------------|--------|-------|\n| {Deliverable 1} | ✅ | {Any relevant notes} |\n| {Deliverable 2} | ✅ | {Any relevant notes} |\n| {Deliverable 3} | ✅ | {Any relevant notes} |\n\n## Tasks Completed\n\n### Plan {N}.1: {Plan Name}\n- [x] {Task 1}\n- [x] {Task 2}\n\n### Plan {N}.2: {Plan Name}\n- [x] {Task 1}\n- [x] {Task 2}\n\n## Verification Results\n\n| Check | Result | Evidence |\n|-------|--------|----------|\n| {Verification 1} | ✅ Pass | {Command output / screenshot path} |\n| {Verification 2} | ✅ Pass | {Command output / screenshot path} |\n\n## Commits\n\n| Hash | Message |\n|------|---------|\n| `abc123` | feat(phase-N): {description} |\n| `def456` | feat(phase-N): {description} |\n\n## Lessons Learned\n- {What went well}\n- {What could be improved}\n- {Unexpected discoveries}\n\n## Next Steps\n- {What the next phase should address}\n- {Any deferred items}\n\n---\n\n*Completed: YYYY-MM-DD*\n" }, { "path": ".gsd/templates/project.md", "content": "# Project Template\n\nTemplate for `.gsd/SPEC.md` (or PROJECT.md) — project specification.\n\n---\n\n## File Template\n\n```markdown\n---\nstatus: DRAFT | FINALIZED\ncreated: [ISO timestamp]\nfinalized: [ISO timestamp when status changed]\n---\n\n# SPEC.md — Project Specification\n\n## Vision\n\n{One paragraph describing what this project is and why it matters}\n\n---\n\n## Goals\n\n1. **{Primary Goal}**\n {Brief description}\n\n2. **{Secondary Goal}**\n {Brief description}\n\n3. **{Tertiary Goal}**\n {Brief description}\n\n---\n\n## Non-Goals (Out of Scope)\n\nExplicitly NOT part of this project:\n\n- {Non-goal 1}\n- {Non-goal 2}\n- {Non-goal 3}\n\n---\n\n## Users\n\n**Primary User:** {Who}\n- {How they'll use it}\n- {What they need}\n\n**Secondary User:** {Who} (if applicable)\n- {How they'll use it}\n\n---\n\n## Constraints\n\n### Technical\n- {Technical constraint 1}\n- {Technical constraint 2}\n\n### Timeline\n- {Timeline constraint}\n\n### Other\n- {Budget, resources, etc.}\n\n---\n\n## Success Criteria\n\nHow we know the project is successful:\n\n- [ ] {Measurable outcome 1}\n- [ ] {Measurable outcome 2}\n- [ ] {Measurable outcome 3}\n\n---\n\n## Prior Art\n\nExisting solutions or inspiration:\n\n| Solution | Pros | Cons | Relevance |\n|----------|------|------|-----------|\n| {solution} | {pros} | {cons} | {how it relates} |\n\n---\n\n## Open Questions\n\nQuestions to resolve during planning:\n\n- [ ] {Question 1}\n- [ ] {Question 2}\n\n---\n\n## Decisions\n\nKey decisions made during specification:\n\n| Decision | Choice | Rationale | Date |\n|----------|--------|-----------|------|\n| {decision} | {choice} | {why} | {date} |\n```\n\n---\n\n## Status Flow\n\n1. **DRAFT** — Being written, not ready for planning\n2. **FINALIZED** — Approved, planning can begin\n\n**Planning Lock:** Cannot create plans until status is FINALIZED.\n\n## Guidelines\n\n- Keep vision to one paragraph\n- Goals should be achievable in one milestone\n- Non-goals are as important as goals\n- Success criteria must be measurable\n" }, { "path": ".gsd/templates/requirements.md", "content": "# Requirements Template\n\nTemplate for `.gsd/REQUIREMENTS.md` — formal requirements tracking with traceability.\n\n---\n\n## File Template\n\n```markdown\n---\nmilestone: {name}\nupdated: [ISO timestamp]\n---\n\n# Requirements\n\n## Overview\n\nRequirements derived from SPEC.md for traceability and coverage tracking.\n\n---\n\n## Functional Requirements\n\n| ID | Requirement | Source | Phase | Status |\n|----|-------------|--------|-------|--------|\n| REQ-01 | {requirement description} | SPEC Goal 1 | 1 | Pending |\n| REQ-02 | {requirement description} | SPEC Goal 1 | 1 | Pending |\n| REQ-03 | {requirement description} | SPEC Goal 2 | 2 | Pending |\n| REQ-04 | {requirement description} | SPEC Goal 2 | 2 | Pending |\n| REQ-05 | {requirement description} | SPEC Goal 3 | 3 | Pending |\n\n---\n\n## Non-Functional Requirements\n\n| ID | Requirement | Category | Phase | Status |\n|----|-------------|----------|-------|--------|\n| NFR-01 | Response time < 200ms | Performance | 4 | Pending |\n| NFR-02 | Mobile responsive | UX | All | Pending |\n| NFR-03 | 99% uptime | Reliability | 4 | Pending |\n\n---\n\n## Constraints\n\n| ID | Constraint | Source | Impact |\n|----|------------|--------|--------|\n| CON-01 | {constraint} | SPEC | {affected areas} |\n| CON-02 | {constraint} | Technical | {affected areas} |\n\n---\n\n## Traceability Matrix\n\n| Requirement | Plans | Tests | Status |\n|-------------|-------|-------|--------|\n| REQ-01 | 1.1, 1.2 | TC-01 | — |\n| REQ-02 | 1.2 | TC-02, TC-03 | — |\n| REQ-03 | 2.1 | TC-04 | — |\n\n---\n\n## Status Definitions\n\n| Status | Meaning |\n|--------|---------|\n| Pending | Not yet started |\n| In Progress | Being implemented |\n| Complete | Implemented and verified |\n| Blocked | Cannot proceed |\n| Deferred | Moved to later milestone |\n```\n\n---\n\n## Guidelines\n\n**Requirement IDs:**\n- REQ-XX: Functional requirements\n- NFR-XX: Non-functional requirements\n- CON-XX: Constraints\n\n**Good requirements are:**\n- Testable\n- Specific\n- Traceable to SPEC goals\n\n**Update when:**\n- Phase completes (mark requirements satisfied)\n- Scope changes (add/defer requirements)\n- Verification passes (update status)\n" }, { "path": ".gsd/templates/roadmap.md", "content": "# Roadmap Template\n\nTemplate for `.gsd/ROADMAP.md` — phase structure and progress tracking.\n\n---\n\n## File Template\n\n```markdown\n---\nmilestone: {name}\nversion: {semantic version}\nupdated: [ISO timestamp]\n---\n\n# Roadmap\n\n> **Current Phase:** {N} - {name}\n> **Status:** {planning | executing | verifying}\n\n## Must-Haves (from SPEC)\n\n- [ ] {Must-have 1}\n- [ ] {Must-have 2}\n- [ ] {Must-have 3}\n\n---\n\n## Phases\n\n### Phase 1: {Foundation}\n**Status:** ⬜ Not Started | 🔄 In Progress | ✅ Complete\n**Objective:** {What this phase delivers}\n**Requirements:** REQ-01, REQ-02\n\n**Plans:**\n- [ ] Plan 1.1: {name}\n- [ ] Plan 1.2: {name}\n\n---\n\n### Phase 2: {Core Feature}\n**Status:** ⬜ Not Started\n**Objective:** {What this phase delivers}\n**Depends on:** Phase 1\n\n**Plans:**\n- [ ] Plan 2.1: {name}\n- [ ] Plan 2.2: {name}\n\n---\n\n### Phase 3: {Integration}\n**Status:** ⬜ Not Started\n**Objective:** {What this phase delivers}\n**Depends on:** Phase 2\n\n---\n\n### Phase 4: {Polish/Launch}\n**Status:** ⬜ Not Started\n**Objective:** {Final touches and deployment}\n**Depends on:** Phase 3\n\n---\n\n## Progress Summary\n\n| Phase | Status | Plans | Complete |\n|-------|--------|-------|----------|\n| 1 | ⬜ | 0/2 | — |\n| 2 | ⬜ | 0/2 | — |\n| 3 | ⬜ | 0/1 | — |\n| 4 | ⬜ | 0/1 | — |\n\n---\n\n## Timeline\n\n| Phase | Started | Completed | Duration |\n|-------|---------|-----------|----------|\n| 1 | — | — | — |\n| 2 | — | — | — |\n| 3 | — | — | — |\n| 4 | — | — | — |\n```\n\n---\n\n## Status Icons\n\n- ⬜ Not Started\n- 🔄 In Progress\n- ✅ Complete\n- ⏸️ Paused\n- ❌ Blocked\n\n## Guidelines\n\n- 3-5 phases per milestone\n- Each phase has clear deliverable\n- Dependencies flow forward\n- Update status as work progresses\n" }, { "path": ".gsd/templates/spec.md", "content": "# SPEC.md — Project Specification\n\n> **Status**: `DRAFT` | `FINALIZED`\n>\n> ⚠️ **Planning Lock**: No code may be written until this spec is marked `FINALIZED`.\n\n## Vision\n{One paragraph describing what this project is and why it exists.}\n\n## Goals\n1. **{Goal 1}** — {Brief description}\n2. **{Goal 2}** — {Brief description}\n3. **{Goal 3}** — {Brief description}\n\n## Non-Goals (Out of Scope)\n- {What this project explicitly will NOT do}\n- {Features that are intentionally excluded}\n- {Scope boundaries}\n\n## Constraints\n- {Technical constraint 1}\n- {Business constraint 1}\n- {Timeline constraint 1}\n\n## Success Criteria\n- [ ] {Measurable outcome 1}\n- [ ] {Measurable outcome 2}\n- [ ] {Measurable outcome 3}\n- [ ] {Measurable outcome 4}\n\n## User Stories (Optional)\n\n### As a {user type}\n- I want to {action}\n- So that {benefit}\n\n### As a {user type}\n- I want to {action}\n- So that {benefit}\n\n## Technical Requirements (Optional)\n\n| Requirement | Priority | Notes |\n|-------------|----------|-------|\n| {Requirement 1} | Must-have | {Details} |\n| {Requirement 2} | Should-have | {Details} |\n| {Requirement 3} | Nice-to-have | {Details} |\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/sprint.md", "content": "# Sprint {N} — {Sprint Name}\n\n> **Duration**: YYYY-MM-DD to YYYY-MM-DD\n> **Status**: In Progress | Complete\n\n## Goal\n{One sentence describing what this sprint aims to achieve.}\n\n## Scope\n\n### Included\n- {Feature/task 1}\n- {Feature/task 2}\n- {Feature/task 3}\n\n### Explicitly Excluded\n- {Out of scope item 1}\n- {Out of scope item 2}\n\n## Tasks\n\n| Task | Assignee | Status | Est. Hours |\n|------|----------|--------|------------|\n| {Task 1} | {who} | ⬜ Todo | {hours} |\n| {Task 2} | {who} | 🔄 In Progress | {hours} |\n| {Task 3} | {who} | ✅ Done | {hours} |\n\n## Daily Log\n\n### Day 1 (YYYY-MM-DD)\n- {What was accomplished}\n- {Blockers encountered}\n\n### Day 2 (YYYY-MM-DD)\n- {What was accomplished}\n- {Blockers encountered}\n\n## Risks & Blockers\n\n| Risk | Impact | Mitigation |\n|------|--------|------------|\n| {Risk 1} | {High/Med/Low} | {What can be done} |\n\n## Retrospective (end of sprint)\n\n### What Went Well\n- {Positive outcome 1}\n\n### What Could Improve\n- {Area for improvement 1}\n\n### Action Items\n- [ ] {Action to take in next sprint}\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/stack.md", "content": "# Technology Stack\n\n> Auto-generated by /map on \n\n## Runtime\n\n| Technology | Version | Purpose |\n|------------|---------|---------|\n| {Language} | {version} | {purpose} |\n| {Framework} | {version} | {purpose} |\n| {Database} | {version} | {purpose} |\n\n## Core Technologies\n\n### {Category 1}\n| Feature | System | Purpose |\n|---------|--------|---------|\n| {Feature} | {System/Location} | {Purpose} |\n\n### {Category 2}\n| Directory | Files | Purpose |\n|-----------|-------|---------|\n| `{path}` | {count} | {purpose} |\n\n## Dependencies\n\n### External Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| {package} | {version} | {purpose} |\n\n### Internal Dependencies\n\n| Component | Depends On | Purpose |\n|-----------|------------|---------|\n| {Component A} | {Component B} | {Why dependency exists} |\n\n## Infrastructure\n\n| Service | Provider | Purpose |\n|---------|----------|---------|\n| {Service} | {Provider} | {Purpose} |\n\n**Repository:** {repository URL}\n\n## Configuration\n\n| Variable | Purpose | Location |\n|----------|---------|----------|\n| {VAR_NAME} | {What it controls} | {Where it's set} |\n\n## File Size Inventory\n\n| Category | Count | Total Lines (approx) |\n|----------|-------|---------------------|\n| {Category} | {count} | {lines} |\n| **Total** | **{total}** | **{total_lines}** |\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/state.md", "content": "# State Template\n\nTemplate for `.gsd/STATE.md` — project memory across sessions.\n\n---\n\n## File Template\n\n```markdown\n---\nupdated: [ISO timestamp]\n---\n\n# Project State\n\n## Current Position\n\n**Milestone:** {name}\n**Phase:** {N} - {name}\n**Status:** {planning | executing | verifying | blocked}\n**Plan:** {current plan if executing}\n\n## Last Action\n\n{What was just completed}\n\n## Next Steps\n\n1. {Immediate next action}\n2. {Following action}\n3. {Third action if known}\n\n## Active Decisions\n\nDecisions made that affect current work:\n\n| Decision | Choice | Made | Affects |\n|----------|--------|------|---------|\n| {what} | {choice} | {date} | {phases/plans} |\n\n## Blockers\n\n{None if clear}\n\n- [ ] {Blocker 1}: {resolution approach}\n- [ ] {Blocker 2}: {resolution approach}\n\n## Concerns\n\nThings to watch but not blocking:\n\n- {Concern 1}\n- {Concern 2}\n\n## Session Context\n\n{Any context the next session needs to know}\n```\n\n---\n\n## Update Rules\n\n**Update STATE.md after:**\n- Every completed task\n- Every decision made\n- Any blocker identified\n- Session end/pause\n\n**What to update:**\n- `updated` timestamp\n- Current Position\n- Last Action\n- Next Steps\n\n**Keep it lean:**\n- STATE.md is read frequently\n- Only current context, not history\n- History goes in JOURNAL.md\n\n---\n\n## Resume Protocol\n\nWhen starting a new session:\n\n1. Read STATE.md first\n2. Understand current position\n3. Check blockers/concerns\n4. Continue from Next Steps\n\nThe STATE.md is the \"save game\" for the project.\n" }, { "path": ".gsd/templates/state_snapshot.md", "content": "# State Snapshot Template\n\nTemplate for wave summaries and session state captures.\n\n---\n\n## When to Use\n\nCreate a state snapshot:\n- After completing each wave\n- Before pausing work\n- After 3 debugging failures\n- When switching models mid-session\n- At any significant milestone\n\n---\n\n## Template\n\n```markdown\n---\nwave: {N}\nphase: {phase number}\ncreated: {ISO timestamp}\nstatus: {complete | partial | blocked}\n---\n\n# Wave {N} State Snapshot\n\n## Objective\n\n{What this wave aimed to accomplish — 1-2 sentences}\n\n## Changes Realized\n\n- {Change 1}\n- {Change 2}\n- {Change 3}\n\n## Files Touched\n\n| File | Change Type | Description |\n|------|-------------|-------------|\n| {path/to/file1} | created | {brief description} |\n| {path/to/file2} | modified | {brief description} |\n| {path/to/file3} | deleted | {brief description} |\n\n## Verification Results\n\n| Check | Command | Result |\n|-------|---------|--------|\n| {Test 1} | `{command}` | ✅ Passed |\n| {Test 2} | `{command}` | ✅ Passed |\n| {Test 3} | `{command}` | ❌ Failed: {reason} |\n\n## Commits in This Wave\n\n| Hash | Message |\n|------|---------|\n| {abc123} | {commit message 1} |\n| {def456} | {commit message 2} |\n\n## Risks & Technical Debt\n\n{None if clear}\n\n- ⚠️ {Risk or debt item 1}\n- ⚠️ {Risk or debt item 2}\n\n## TODO for Next Wave\n\n1. {Next task 1}\n2. {Next task 2}\n3. {Next task 3}\n\n## Context for Fresh Session\n\n{Any information the next session needs — decisions made, blockers encountered, hypotheses to test}\n\n## Token Usage (Optional)\n\n| Metric | Value |\n|--------|-------|\n| Files loaded | {count} |\n| Est. tokens | {number} |\n| Budget used | {percentage}% |\n| Compression | {yes/no} |\n\n{Notes on token efficiency for this wave}\n```\n\n---\n\n## Minimal Snapshot (Debug Session)\n\nFor quick state dumps during debugging:\n\n```markdown\n# Debug State Snapshot\n\n**Time:** {timestamp}\n**Problem:** {what you're debugging}\n\n**Tried:**\n1. {approach 1} → {result}\n2. {approach 2} → {result}\n3. {approach 3} → {result}\n\n**Current Hypothesis:** {theory}\n\n**Files Involved:**\n- {file1}\n- {file2}\n\n**Recommended Next:** {suggested approach for fresh session}\n```\n\n---\n\n## Integration with STATE.md\n\nState snapshots are point-in-time captures. After creating a snapshot:\n\n1. Update STATE.md with current position\n2. Reference the snapshot in SESSION Context\n3. Commit both together\n\nSTATE.md is current state; snapshots are historical records.\n\n---\n\n*Part of GSD methodology. See PROJECT_RULES.md for wave execution rules.*\n" }, { "path": ".gsd/templates/todo.md", "content": "# TODO.md — Pending Items\n\n> Quick capture of ideas, tasks, and issues.\n>\n> Use `/add-todo` to add items, `/check-todos` to view.\n\n## Format\n\n```markdown\n- [ ] Description `priority` — YYYY-MM-DD\n- [x] Completed item `priority` — YYYY-MM-DD ✓ YYYY-MM-DD\n```\n\n## Priority Levels\n\n| Level | Use For |\n|-------|---------|\n| `high` 🔴 | Blocking issues, urgent fixes |\n| `medium` 🟡 | Normal priority (default) |\n| `low` 🟢 | Nice-to-have, future ideas |\n\n---\n\n## Items\n\n\n\n- [ ] {Example todo item} `medium` — YYYY-MM-DD\n\n---\n\n*Last updated: *\n" }, { "path": ".gsd/templates/token_report.md", "content": "# Token Report Template\n\nTemplate for documenting token usage per wave or session.\n\n---\n\n## Template\n\n```markdown\n---\nwave: {N}\nphase: {phase number}\ncreated: {ISO timestamp}\n---\n\n# Token Usage Report\n\n## Summary\n\n| Metric | Value |\n|--------|-------|\n| Files loaded | {count} |\n| Estimated tokens | {number} |\n| Budget usage | {percentage}% |\n| Compression applied | {yes/no} |\n\n## Files Loaded\n\n| File | Lines | Est. Tokens | Reason |\n|------|-------|-------------|--------|\n| {path/to/file1} | {N} | {N} | {why loaded} |\n| {path/to/file2} | {N} | {N} | {why loaded} |\n\n## Compression Applied\n\n| File | Before | After | Savings |\n|------|--------|-------|---------|\n| {file} | {N} | summary | {N} tokens |\n\n## Efficiency Analysis\n\n### What Worked Well\n- {Strategy that saved tokens}\n\n### Could Improve\n- {Opportunity for optimization}\n\n### Recommendations\n- {Suggestion for next wave}\n```\n\n---\n\n## When to Create\n\nCreate a token report:\n- After completing a wave with high token usage\n- When budget exceeds 50%\n- For debugging session performance\n- During milestone retrospectives\n\n---\n\n## Quick Report (Minimal)\n\nFor simple tracking:\n\n```markdown\n## Token Report: Wave {N}\n\n- Files: {count}\n- Tokens: ~{number}\n- Budget: {X}%\n- Status: [OK|WARNING|CRITICAL]\n```\n\n---\n\n*Part of GSD v1.6 Token Optimization.*\n" }, { "path": ".gsd/templates/user-setup.md", "content": "# User Setup Template\n\nTemplate for user setup instructions when external services are needed.\n\n---\n\n## File Template\n\n```markdown\n---\nphase: {N}\nplan: {M}\ntype: user-setup\n---\n\n# User Setup Required\n\n## Overview\n\nThis plan requires manual setup that the AI cannot perform.\n\n**Time estimate:** {X minutes}\n**Blocking:** Plan cannot proceed until complete\n\n---\n\n## Setup Steps\n\n### 1. {Service Name}\n\n**Why needed:** {Purpose in the project}\n\n**Create account:**\n- Go to: {URL}\n- Sign up with: {recommendations}\n\n**Get credentials:**\n1. Navigate to: {dashboard location}\n2. Find: {API keys section}\n3. Create: {what to create}\n\n**Add to project:**\n```powershell\n# Add to .env.local\n{ENV_VAR}=your_key_here\n```\n\n**Verify:**\n```powershell\n# Test the connection\n{verification command}\n```\n\n---\n\n### 2. {Another Service}\n\n**Why needed:** {Purpose}\n\n**Steps:**\n1. {Step 1}\n2. {Step 2}\n3. {Step 3}\n\n**Environment variables:**\n```\n{VAR_1}=value\n{VAR_2}=value\n```\n\n---\n\n## Dashboard Configuration\n\nSome things require manual dashboard setup:\n\n| Service | Task | Location | Notes |\n|---------|------|----------|-------|\n| {service} | {task} | {where} | {notes} |\n\n---\n\n## Verification Checklist\n\nBefore continuing, verify:\n\n- [ ] All environment variables set\n- [ ] All accounts created\n- [ ] All dashboard configurations complete\n- [ ] Verification commands pass\n\n---\n\n## When Complete\n\nType \"done\" or \"setup complete\" to continue with execution.\n```\n\n---\n\n## Guidelines\n\n**Include only what AI cannot do:**\n- Account creation (requires human identity)\n- Secret retrieval (protected behind login)\n- Dashboard configuration (no API available)\n- Payment method setup\n- 2FA enrollment\n\n**Do NOT include:**\n- npm install (AI can do)\n- File creation (AI can do)\n- Configuration file edits (AI can do)\n- API calls (AI can do)\n\n**Keep minimal** — every manual step slows down execution.\n" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\nAll notable changes to GSD for Antigravity.\n\n## [1.5.0] - 2026-04-01\n\n### Breaking Changes\n- **Skills moved from `.agent/skills/` to `.agents/skills/`** — aligns with the [Agent Skills open standard](https://agentskills.io/specification), the universal cross-agent discovery path used by Gemini CLI, Claude Code, Cursor, VS Code Copilot, and other compatible agents\n- **SKILL.md `name` fields updated** — all 11 skills now use lowercase-hyphenated names matching their folder names per spec (e.g., `GSD Executor` → `executor`)\n\n### Added\n- `/sprint` workflow — time-boxed sprints (new/status/close) for quick focused work outside the milestone cycle\n- **Test Quality Rules** in `/plan` — prevents agents from gaming test suites with mock-everything, tautological assertions, or always-pass tests\n- **Discovery template reference** (Level 1.5) in `/plan` — bridges the gap between quick verification and full research\n- **Journal/decisions archival** in `/complete-milestone` — archives DECISIONS.md and JOURNAL.md into milestone folder, resets for next milestone\n- **Architecture auto-refresh** in `/complete-milestone` — refreshes ARCHITECTURE.md and STACK.md after milestone completion\n- **Requirements tracking** — `/plan` loads REQUIREMENTS.md, `/execute` updates requirement status, `/complete-milestone` archives and marks requirements\n- **Session file reset** in `/new-milestone` — resets DECISIONS.md and JOURNAL.md if they've grown beyond a header\n- SVG banner in README\n\n### Changed\n- README updated with `/sprint` commands section, new file structure, command count (29 total)\n- All references across docs, scripts, and workflows updated for `.agents/skills/` path\n- `validate-skills.ps1/.sh` updated to scan `.agents/skills/`\n- `install.md` and `update.md` workflows handle both `.agent/` (workflows) and `.agents/` (skills)\n\n### Fixed\n- Skills not appearing in Antigravity after updates (closes #10)\n\n---\n\n## [1.4.0] - 2026-01-17\n\n### Added\n- **Template Parity** — 8 new templates (22 total)\n - `architecture.md`, `decisions.md`, `journal.md`, `stack.md`\n - `phase-summary.md`, `sprint.md`, `todo.md`, `spec.md`\n- `validate-templates.ps1/.sh` — template validation scripts\n- `validate-all` now includes template validation\n\n---\n\n## [1.3.0] - 2026-01-17\n\n### Added\n- **Validation Scripts** — expanded testing infrastructure\n - `validate-skills.ps1/.sh` — verify skill directory structure\n - `validate-all.ps1/.sh` — master script runs all validators\n- **VERSION file** — single source of truth for version\n- `/help` now displays current version\n\n### Changed\n- README.md updated with Testing section\n\n---\n\n## [1.2.0] - 2026-01-17\n\n### Added\n- **Cross-Platform Support** — All 16 workflow files now have Bash equivalents\n- `/web-search` — Search the web for technical research\n\n### Changed\n- README.md updated with dual-syntax Getting Started (PowerShell + Bash)\n- README.md added Cross-Platform Support section\n- Git commands in workflows use `bash` syntax (cross-platform)\n\n---\n\n## [1.1.0] - 2026-01-17\n\n### Added\n- **Template Parity** — 14 templates aligned with original repository\n - `DEBUG.md`, `UAT.md`, `discovery.md`, `requirements.md`, etc.\n- **Examples** — `.gsd/examples/` directory\n - `workflow-example.md` — Full workflow walkthrough\n - `quick-reference.md` — Command cheat sheet\n - `cross-platform.md` — Platform-specific guidance\n- `/add-todo` — Quick capture workflow\n- `/check-todos` — List pending items workflow\n- `/whats-new` — Show recent changes\n\n### Changed\n- Workflows now have \"Related\" sections for discoverability\n- Cross-linked workflows and skills\n\n---\n\n## [1.0.0] - 2026-01-17\n\n### Added\n\n**Core Workflows (21)**\n- `/map` — Analyze codebase, generate ARCHITECTURE.md\n- `/plan` — Create PLAN.md with XML task structure\n- `/execute` — Wave-based execution with atomic commits\n- `/verify` — Must-haves validation with empirical proof\n- `/debug` — Systematic debugging with 3-strike rule\n- `/new-project` — Deep questioning initialization (10 phases)\n- `/new-milestone` — Create milestone with phases\n- `/complete-milestone` — Archive and tag milestone\n- `/audit-milestone` — Quality review\n- `/add-phase` — Add phase to roadmap\n- `/insert-phase` — Insert with renumbering\n- `/remove-phase` — Remove with safety checks\n- `/discuss-phase` — Clarify scope before planning\n- `/research-phase` — Technical deep dive\n- `/list-phase-assumptions` — Surface assumptions\n- `/plan-milestone-gaps` — Gap closure plans\n- `/progress` — Show current position\n- `/pause` — State preservation\n- `/resume` — Context restoration\n- `/add-todo` — Quick capture\n- `/check-todos` — List todos\n- `/help` — Command reference\n\n**Skills (8)**\n- `planner` — Task anatomy, goal-backward methodology\n- `executor` — Atomic commits, Need-to-Know context\n- `verifier` — Must-haves extraction, evidence requirements\n- `debugger` — 3-strike rule, systematic diagnosis\n- `codebase-mapper` — Structure analysis, debt discovery\n- `plan-checker` — Plan validation before execution\n- `context-health-monitor` — Prevents context rot\n- `empirical-validation` — Requires proof for changes\n\n**Documentation**\n- README.md with full methodology explanation\n- GSD-STYLE.md comprehensive style guide\n- Templates: PLAN.md, VERIFICATION.md, RESEARCH.md, SUMMARY.md\n- Examples: workflow-example.md, quick-reference.md, cross-platform.md\n\n**Rules**\n- GEMINI.md with 4 core rules enforcement\n- Planning Lock, State Persistence, Context Hygiene, Empirical Validation\n\n### Attribution\nAdapted from [glittercowboy/get-shit-done](https://github.com/glittercowboy/get-shit-done) for Google Antigravity.\n" }, { "path": "GSD-STYLE.md", "content": "# GSD-STYLE.md\n\n> **Comprehensive reference.** Core rules auto-load from `.gemini/GEMINI.md`. This document provides deep explanations and examples for when you need the full picture.\n\nThis document explains how GSD is written so future AI instances can contribute consistently.\n\n## Core Philosophy\n\nGSD is a **meta-prompting system** where every file is both implementation and specification. Files teach the AI how to build software systematically. The system optimizes for:\n\n- **Solo developer + AI workflow** (no enterprise patterns)\n- **Context engineering** (manage the context window deliberately)\n- **Plans as prompts** (PLAN.md files are executable, not documents to transform)\n\n---\n\n## File Structure Conventions\n\n### Workflows (`.agent/workflows/*.md`)\n\nSlash commands the user invokes. Each workflow:\n- Has YAML frontmatter with `description`\n- Contains XML-structured process blocks\n- Ends with \"Next Steps\" routing\n\n### Skills (`.agents/skills/*/SKILL.md`)\n\nSpecialized agent behaviors. Each skill:\n- Has YAML frontmatter with `name` and `description`\n- Contains detailed methodology\n- Is referenced by parent workflows\n\n### Templates (`.gsd/templates/*.md`)\n\nReusable document structures. Copy, don't reference.\n\n### References (`.gsd/examples/*.md`)\n\nRead-only documentation and examples.\n\n---\n\n## XML Tag Conventions\n\n### Semantic Containers Only\n\nUse XML tags for semantic meaning, not formatting:\n\n```markdown\n\nYou are a GSD executor...\n\n\n\nExecute all plans in a phase...\n\n\n\n## 1. First Step\n...\n\n```\n\n### Task Structure\n\n```xml\n\n Clear descriptive name\n exact/path/to/file.ts\n \n Specific implementation instructions.\n AVOID: common mistake (reason)\n USE: preferred approach (reason)\n \n executable command that proves completion\n measurable acceptance criteria\n\n```\n\n### Effort Attribute (Optional)\n\nThe `effort` attribute hints at task complexity for model selection:\n\n| Value | Use Case | Model Hint |\n|-------|----------|------------|\n| `low` | Simple edits, formatting | Fast models |\n| `medium` | Standard implementation (default) | Standard models |\n| `high` | Complex logic, refactoring | Reasoning models |\n| `max` | Architecture, security-critical | Deep reasoning |\n\n**Default:** `medium` if omitted. No workflow should fail if this attribute is absent.\n\nSee [docs/model-selection-playbook.md](docs/model-selection-playbook.md) for model selection guidance.\n\n\n### Checkpoint Structure\n\n```xml\n\n Verify UI renders correctly\n User reviews the rendered component\n User confirms visual correctness\n\n```\n\n---\n\n## Language & Tone\n\n### Imperative Voice\n- ✅ \"Create the file\"\n- ❌ \"You should create the file\"\n- ❌ \"We will create the file\"\n\n### No Filler\n- ✅ \"Run `npm test`\"\n- ❌ \"Now let's go ahead and run `npm test`\"\n\n### No Sycophancy\n- ✅ \"Phase complete.\"\n- ❌ \"Great job! Phase complete!\"\n\n### Brevity with Substance\nEvery sentence should convey information. Remove words that don't add meaning.\n\n---\n\n## Context Engineering\n\n### Size Constraints\n\n| Context Usage | Quality |\n|---------------|---------|\n| 0-30% | PEAK — Thorough, comprehensive |\n| 30-50% | GOOD — Confident, solid work |\n| 50-70% | DEGRADING — Efficiency mode begins |\n| 70%+ | POOR — Rushed, minimal |\n\n**Rule:** Plans should complete within ~50% context.\n\n### Fresh Context Pattern\n\nWhen spawning subprocesses (plans, tasks), they get:\n- The specific plan being executed\n- Minimal necessary context from parent files\n- NO accumulated orchestrator state\n\n### State Preservation\n\nSTATE.md exists because context windows are temporary.\nEverything important goes in STATE.md so the next session can continue.\n\n---\n\n## Anti-Patterns to Avoid\n\n### Enterprise Patterns (Banned)\n\n❌ Stakeholder communication\n❌ Team coordination\n❌ Sprint ceremonies\n❌ Multiple approval levels\n❌ Separate environments requiring explicit promotion\n\n### Temporal Language (Banned in Implementation Docs)\n\n❌ \"First, we'll...\"\n❌ \"Next, we should...\"\n❌ \"Finally, we'll...\"\n\n### Generic XML (Banned)\n\n```xml\n\n
\n Authentication\n ...\n
\n\n\n\n Create login endpoint\n ...\n\n```\n\n### Vague Tasks (Banned)\n\n```xml\n\nImplement authentication\n\n\n\n Create POST /api/auth/login endpoint.\n Accept {email, password} JSON body.\n Query User by email, compare with bcrypt.\n Return JWT in httpOnly cookie on success.\n Return 401 on failure.\n\n```\n\n---\n\n## Commit Conventions\n\n### Format\n```\ntype(scope): description\n```\n\n### Types\n| Type | Use For |\n|------|---------|\n| `feat` | New feature |\n| `fix` | Bug fix |\n| `docs` | Documentation |\n| `refactor` | Code restructure |\n| `test` | Add tests |\n| `chore` | Maintenance |\n\n### Rules\n- One task = one commit\n- Scope is phase number for phase work\n- No commit before verification passes\n\n---\n\n## UX Patterns\n\n### Banners\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n GSD ► STATUS MESSAGE\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n### \"Next Up\" Format\n\n```\n───────────────────────────────────────────────────────\n\n▶ NEXT\n\n/command — description\n\n───────────────────────────────────────────────────────\n```\n\n### Decision Gates\n\nWhen user input needed:\n```\n⚠️ DECISION REQUIRED\n\nOption A: {description}\nOption B: {description}\n\nWhich do you prefer?\n```\n\n---\n\n## Summary: Core Meta-Patterns\n\n1. **Plans are prompts** — PLAN.md is read and executed directly\n2. **Fresh context for execution** — Each plan runs in clean context\n3. **STATE.md is memory** — Everything important persists there\n4. **Verify before done** — No \"trust me, it works\"\n5. **Aggressive atomicity** — Small tasks, atomic commits\n6. **No enterprise theater** — Solo dev + AI workflow only\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2026 toonight\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "PROJECT_RULES.md", "content": "# PROJECT_RULES.md — GSD Canonical Rules\n\n> **Single Source of Truth** for the Get Shit Done methodology.\n> \n> Model-agnostic. All adapters and extensions reference this file.\n\n---\n\n## Core Protocol\n\n**SPEC → PLAN → EXECUTE → VERIFY → COMMIT**\n\n1. **SPEC**: Define requirements in `.gsd/SPEC.md` until status is `FINALIZED`\n2. **PLAN**: Decompose into phases in `.gsd/ROADMAP.md`, then detailed plans\n3. **EXECUTE**: Implement with atomic commits per task\n4. **VERIFY**: Prove completion with empirical evidence\n5. **COMMIT**: One task = one commit, message format: `type(scope): description`\n\n**Planning Lock**: No implementation code until SPEC.md contains \"Status: FINALIZED\".\n\n---\n\n## Proof Requirements\n\nEvery change requires verification evidence:\n\n| Change Type | Required Proof |\n|-------------|----------------|\n| API endpoint | curl/HTTP response |\n| UI change | Screenshot |\n| Build/compile | Command output |\n| Test | Test runner output |\n| Config | Verification command |\n\n**Never accept**: \"It looks correct\", \"This should work\", \"I've done similar before\".\n\n**Always require**: Captured output, screenshot, or test result.\n\n---\n\n## Search-First Discipline\n\n**Before reading any file completely:**\n\n1. **Search first** — Use grep, ripgrep, or IDE search to find relevant snippets\n2. **Evaluate snippets** — Determine if full file read is justified\n3. **Targeted reads** — Only read specific line ranges when needed\n\n**Benefits:**\n- Reduces context pollution\n- Faster understanding of large codebases\n- Prevents reading irrelevant code\n\n**Anti-pattern**: Reading entire files \"to understand the context\" without searching first.\n\n---\n\n## Wave Execution\n\nPlans are grouped into **waves** based on dependencies:\n\n| Wave | Characteristic | Execution |\n|------|----------------|-----------|\n| 1 | Foundation tasks, no dependencies | Run in parallel |\n| 2 | Depends on Wave 1 | Wait for Wave 1, then parallel |\n| 3 | Depends on Wave 2 | Wait for Wave 2, then parallel |\n\n**Wave Completion Protocol:**\n1. All tasks in wave verified\n2. State snapshot created\n3. Commit all wave work\n4. Update STATE.md with position\n\n---\n\n## State Snapshots\n\nAt the end of each wave or significant work block, create a state snapshot:\n\n```markdown\n## Wave N Summary\n\n**Objective:** {what this wave aimed to accomplish}\n\n**Changes:**\n- {change 1}\n- {change 2}\n\n**Files Touched:**\n- {file1}\n- {file2}\n\n**Verification:**\n- {command}: {result}\n\n**Risks/Debt:**\n- {any concerns}\n\n**Next Wave TODO:**\n- {item 1}\n- {item 2}\n```\n\n---\n\n## Model Independence\n\n**Absolute Rule**: No rule, workflow, or skill may require a specific model provider.\n\n**Allowed:**\n- Optional adapters with provider-specific enhancements\n- Capability-based recommendations (e.g., \"use a reasoning model for planning\")\n- Examples mentioning specific models as illustrations\n\n**Forbidden:**\n- Hard dependencies on provider features\n- Breaking behavior when a specific model is unavailable\n- Duplicating canonical rules in adapters\n\n**Adapter Pattern:**\n```\nadapters/\n├── CLAUDE.md # Optional Claude enhancements\n├── GEMINI.md # Optional Gemini enhancements\n└── GPT_OSS.md # Optional GPT/OSS enhancements\n```\n\nEach adapter must begin with:\n> \"Everything in this file is optional. For canonical rules, see PROJECT_RULES.md.\"\n\n---\n\n## Commit Conventions\n\n**Format:**\n```\ntype(scope): description\n```\n\n**Types:**\n| Type | Usage |\n|------|-------|\n| `feat` | New feature |\n| `fix` | Bug fix |\n| `docs` | Documentation only |\n| `refactor` | Code restructure (no behavior change) |\n| `test` | Adding/updating tests |\n| `chore` | Maintenance, dependencies |\n\n**Rules:**\n- One task = one commit\n- Verify before commit\n- Scope = phase number for phase work (e.g., `feat(phase-1): ...`)\n\n---\n\n## Repository Structure\n\n```\nPROJECT_RULES.md # ← This file (canonical rules)\nGSD-STYLE.md # Style and conventions\n\n.agent/\n└── workflows/ # Slash commands (/plan, /execute, etc.)\n\n.agents/\n└── skills/ # Agent specializations (Agent Skills standard)\n\n.gemini/ # Gemini-specific configuration\n.gsd/ # Project state and artifacts\n├── SPEC.md # Requirements (must be FINALIZED)\n├── ROADMAP.md # Phases and progress\n├── STATE.md # Session memory\n├── templates/ # Document templates\n└── examples/ # Usage examples\n\nadapters/ # Optional model-specific enhancements\ndocs/ # Operational documentation\nscripts/ # Utility scripts\n```\n\n---\n\n## Context Management\n\n**Context Quality Thresholds:**\n\n| Usage | Quality |\n|-------|---------|\n| 0-30% | **PEAK** — Comprehensive, thorough work |\n| 30-50% | **GOOD** — Solid, confident output |\n| 50-70% | **DEGRADING** — Efficiency mode |\n| 70%+ | **POOR** — Rushed, incomplete |\n\n**Context Hygiene Rules:**\n- Keep plans under 50% context usage\n- Fresh context for each plan execution\n- After 3 debugging failures → state dump → fresh session\n- STATE.md = memory across sessions\n\n---\n\n## Token Efficiency Rules\n\n**Goal:** Minimize token consumption while maintaining output quality.\n\n### Loading Rules\n\n| Action | Rule |\n|--------|------|\n| Before reading file | Search first (grep, ripgrep) |\n| File >200 lines | Use outline, not full file |\n| File already understood | Reference summary, don't reload |\n| >5 files needed | Stop, reconsider approach |\n\n### Budget Thresholds\n\n| Usage | Action Required |\n|-------|-----------------|\n| 0-50% | Proceed normally |\n| 50-70% | Switch to outline mode, compress context |\n| 70%+ | State dump required, recommend fresh session |\n\n### Compression Protocol\n\nAfter understanding a file:\n1. Create summary in STATE.md or task notes\n2. Reference summary instead of re-reading\n3. Only reload specific sections if needed\n\n### Per-Wave Efficiency\n\n- Start each wave with minimal context\n- Load files just-in-time (when task requires)\n- Compress/summarize before moving to next wave\n- Document token usage in state snapshots (optional)\n\n**Anti-patterns:**\n- Loading files \"just in case\"\n- Re-reading files already understood\n- Full file reads when snippets suffice\n- Ignoring budget warnings\n\n---\n\n## Quick Reference\n\n```\nBefore coding → SPEC.md must be FINALIZED\nBefore file read → Search first, then targeted read\nAfter each task → Commit + update STATE.md\nAfter each wave → State snapshot\nAfter 3 failures → State dump + fresh session\nBefore \"Done\" → Empirical proof captured\n```\n\n---\n\n*GSD Methodology — Model-Agnostic Edition*\n*Reference implementation for multi-LLM environments*\n" }, { "path": "README.md", "content": "
\n\n\n \"Get\n\n\n
\n\n[![Version](https://img.shields.io/badge/version-1.5.0-00C853?style=flat-square)](CHANGELOG.md)\n[![License](https://img.shields.io/badge/license-MIT-2196F3?style=flat-square)](LICENSE)\n[![Based on GSD](https://img.shields.io/badge/based%20on-GSD-7B2D8E?style=flat-square)](https://github.com/glittercowboy/get-shit-done)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20Mac-FF6D00?style=flat-square)](#-cross-platform-support)\n[![Model Agnostic](https://img.shields.io/badge/models-any%20LLM-E91E63?style=flat-square)](#-multi-model-support)\n\n
\n\n**Stop vibecoding. Start shipping.**\n\n*Describe your idea → GSD extracts everything the AI needs → Watch it build correctly.*\n\n
\n\n[Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Commands](#-commands-29-total) · [Documentation](#-documentation)\n\n
\n\n---\n\n## 🧠 The Problem\n\n> Vibecoding has a bad reputation — and it deserves it.\n\nYou describe what you want, AI generates code, and you get **inconsistent garbage** that falls apart at scale.\n\nGSD fixes that. It's the **context engineering layer** that makes AI coding reliable.\n\n\n\n\n\n\n
\n\n### ❌ Without GSD\n```\n\"Add a feature\"\n → Inconsistent code\n → Bugs everywhere\n → Debug loop\n → Frustration\n```\n\n\n\n### ✅ With GSD\n```\n\"Add a feature\"\n → SPEC\n → Plan\n → Atomic execution\n → Verification\n → ✅ Done\n```\n\n
\n\n> **No enterprise roleplay.** No sprint ceremonies, story points, stakeholder syncs, or Jira workflows.\n> Just an incredibly effective system for building cool stuff consistently.\n\n---\n\n## 👤 Who This Is For\n\n| | |\n|---|---|\n| 🧑‍💻 **Solo developers** | Using AI coding assistants and need consistency |\n| 👥 **Small teams** | Who want structure without enterprise overhead |\n| 😤 **Anyone** | Tired of AI generating inconsistent garbage |\n\n---\n\n## ⚡ Getting Started\n\n
\n🪟 PowerShell (Windows)\n\n```powershell\n# Open your project\ncd your-project\n\n# Clone the GSD template\ngit clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-template\n\n# Copy to your project\nCopy-Item -Recurse gsd-template\\.agent .\\\nCopy-Item -Recurse gsd-template\\.agents .\\\nCopy-Item -Recurse gsd-template\\.gemini .\\\nCopy-Item -Recurse gsd-template\\.gsd .\\\nCopy-Item -Recurse gsd-template\\adapters .\\\nCopy-Item -Recurse gsd-template\\docs .\\\nCopy-Item -Recurse gsd-template\\scripts .\\\nCopy-Item -Force gsd-template\\PROJECT_RULES.md .\\\nCopy-Item -Force gsd-template\\GSD-STYLE.md .\\\nCopy-Item -Force gsd-template\\model_capabilities.yaml .\\\n\n# Clean up\nRemove-Item -Recurse -Force gsd-template\n```\n\n
\n\n
\n🐧 Bash (Linux / Mac)\n\n```bash\n# Open your project\ncd your-project\n\n# Clone the GSD template\ngit clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-template\n\n# Copy to your project\ncp -r gsd-template/.agent ./\ncp -r gsd-template/.agents ./\ncp -r gsd-template/.gemini ./\ncp -r gsd-template/.gsd ./\ncp -r gsd-template/adapters ./\ncp -r gsd-template/docs ./\ncp -r gsd-template/scripts ./\ncp gsd-template/PROJECT_RULES.md ./\ncp gsd-template/GSD-STYLE.md ./\ncp gsd-template/model_capabilities.yaml ./\n\n# Clean up\nrm -rf gsd-template\n```\n\n
\n\nThen run `/new-project` and follow the prompts.\n\n> [!TIP]\n> You can also use `/install` from a clean project to automate the installation above.\n\n---\n\n## 🔄 How It Works\n\n```mermaid\ngraph LR\n A[\"🆕 /new-project\"] --> B[\"📋 SPEC.md\"]\n B --> C[\"💬 /discuss-phase\"]\n C --> D[\"📐 /plan\"]\n D --> E[\"⚙️ /execute\"]\n E --> F[\"✅ /verify\"]\n F --> G{\"More\\nphases?\"}\n G -- Yes --> C\n G -- No --> H[\"🏁 /complete-milestone\"]\n\n style A fill:#7B2D8E,color:#fff,stroke:none\n style B fill:#00C853,color:#fff,stroke:none\n style C fill:#2196F3,color:#fff,stroke:none\n style D fill:#FF6D00,color:#fff,stroke:none\n style E fill:#E91E63,color:#fff,stroke:none\n style F fill:#00C853,color:#fff,stroke:none\n style G fill:#FFC107,color:#000,stroke:none\n style H fill:#7B2D8E,color:#fff,stroke:none\n```\n\n| Step | Command | Output |\n|:----:|---------|--------|\n| **1** | `/new-project` | Deep questioning → `SPEC.md` (finalized) |\n| **2** | `/discuss-phase N` | Clarify scope → `DECISIONS.md` |\n| **3** | `/plan N` | Technical discovery → `PLAN.md` with XML tasks |\n| **4** | `/execute N` | Wave-based execution → Atomic commits |\n| **5** | `/verify N` | Must-haves check → Evidence captured |\n| **6** | Repeat | Next phase or `/complete-milestone` |\n\n---\n\n## 🧩 Why It Works\n\n### 📦 Context Engineering\n\nThe AI is incredibly powerful **if** you give it the context it needs. Most people don't. GSD handles it for you:\n\n| File | Role | Icon |\n|------|------|:----:|\n| `SPEC.md` | Project vision, always loaded | 🎯 |\n| `ARCHITECTURE.md` | System understanding | 🏗️ |\n| `ROADMAP.md` | Where you're going, what's done | 🗺️ |\n| `STATE.md` | Decisions, blockers, memory across sessions | 💾 |\n| `PLAN.md` | Atomic tasks with XML structure | 📐 |\n| `SUMMARY.md` | What happened, what changed | 📝 |\n\n> Size limits based on where AI quality degrades. Stay under, get consistent excellence.\n\n### 🏷️ XML Prompt Formatting\n\nEvery plan is structured XML optimized for AI execution:\n\n```xml\n\n Create login endpoint\n src/app/api/auth/login/route.ts\n \n Use jose for JWT (not jsonwebtoken - CommonJS issues).\n Validate credentials against users table.\n Return httpOnly cookie on success.\n \n curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie\n Valid credentials return cookie, invalid return 401\n\n```\n\nPrecise instructions. No guessing. Verification built in.\n\n### 🌊 Wave-Based Execution\n\nPlans are grouped into waves based on dependencies:\n\n```mermaid\ngraph TD\n subgraph W1[\"🌊 Wave 1 — Foundation\"]\n T1[\"Task A\"] & T2[\"Task B\"] & T3[\"Task C\"]\n end\n subgraph W2[\"🌊 Wave 2 — Integration\"]\n T4[\"Task D\"] & T5[\"Task E\"]\n end\n subgraph W3[\"🌊 Wave 3 — Polish\"]\n T6[\"Task F\"]\n end\n\n W1 --> W2 --> W3\n\n style W1 fill:#E3F2FD,stroke:#2196F3,color:#000\n style W2 fill:#FFF3E0,stroke:#FF6D00,color:#000\n style W3 fill:#F3E5F5,stroke:#7B2D8E,color:#000\n style T1 fill:#2196F3,color:#fff,stroke:none\n style T2 fill:#2196F3,color:#fff,stroke:none\n style T3 fill:#2196F3,color:#fff,stroke:none\n style T4 fill:#FF6D00,color:#fff,stroke:none\n style T5 fill:#FF6D00,color:#fff,stroke:none\n style T6 fill:#7B2D8E,color:#fff,stroke:none\n```\n\nEach executor gets **fresh context**. Your main session stays fast.\n\n### 🔗 Atomic Git Commits\n\nEach task gets its own commit immediately after completion:\n\n```\nabc123f feat(phase-1): create login endpoint\ndef456g feat(phase-1): add password validation\nhij789k feat(phase-1): implement JWT cookie handling\n```\n\n> **Why?** Git bisect finds exact failing task · Each task independently revertable · Clear history for AI in future sessions\n\n### 🔬 Empirical Verification\n\nNo \"trust me, it works.\" Every verification produces evidence:\n\n| Change Type | Evidence Required |\n|:---:|:---:|\n| 🌐 API endpoint | `curl` output |\n| 🖥️ UI change | Screenshot |\n| 🏗️ Build | Command output |\n| 🧪 Tests | Test results |\n\n---\n\n## 🎮 Commands (29 Total)\n\n> [!NOTE]\n> Slash commands are typed directly as chat messages (e.g. send `/plan 1`). They are **not** IDE autocomplete features — if your editor shows \"nothing found\" when pressing `/`, that's normal. Just type the full command and send it.\n\n### 🔵 Core Workflow\n\n| Command | Purpose |\n|---------|---------|\n| `/map` | 🏗️ Analyze codebase → `ARCHITECTURE.md` |\n| `/plan [N]` | 📐 Create `PLAN.md` for phase N |\n| `/execute [N]` | ⚙️ Wave-based execution with atomic commits |\n| `/verify [N]` | ✅ Must-haves validation with proof |\n| `/debug [desc]` | 🐛 Systematic debugging (3-strike rule) |\n\n### 🟢 Project Setup\n\n| Command | Purpose |\n|---------|---------|\n| `/install` | 📦 Install GSD from GitHub |\n| `/new-project` | 🆕 Deep questioning → `SPEC.md` |\n| `/new-milestone` | 🏁 Create milestone with phases |\n| `/complete-milestone` | 🎉 Archive completed milestone |\n| `/audit-milestone` | 🔍 Review milestone quality |\n\n### 🟠 Phase Management\n\n| Command | Purpose |\n|---------|---------|\n| `/add-phase` | ➕ Add phase to end of roadmap |\n| `/insert-phase` | 📌 Insert phase (renumbers) |\n| `/remove-phase` | ➖ Remove phase (safety checks) |\n| `/discuss-phase` | 💬 Clarify scope before planning |\n| `/research-phase` | 🔬 Deep technical research |\n| `/list-phase-assumptions` | 📋 Surface planning assumptions |\n| `/plan-milestone-gaps` | 🔧 Create gap closure plans |\n\n### 🟡 Sprint\n\n| Command | Purpose |\n|---------|---------|\n| `/sprint new` | ⚡ Create a time-boxed sprint for quick focused work |\n| `/sprint status` | 📊 Show sprint progress |\n| `/sprint close` | ✅ Close sprint with retrospective |\n\n### 🟣 Navigation & State\n\n| Command | Purpose |\n|---------|---------|\n| `/progress` | 📊 Show current position |\n| `/pause` | ⏸️ Save state for session handoff |\n| `/resume` | ▶️ Restore from last session |\n| `/add-todo` | 📝 Quick capture idea |\n| `/check-todos` | 📋 List pending items |\n\n### 🔴 Utilities\n\n| Command | Purpose |\n|---------|---------|\n| `/help` | ❓ Show all available commands |\n| `/web-search` | 🌐 Search the web for decisions |\n| `/whats-new` | 📢 Show recent GSD changes |\n| `/update` | ⬆️ Update GSD to latest version |\n\n---\n\n## 💡 Typical Session\n\n```bash\n/resume # ← Load context from last session\n/progress # ← See where you left off\n/discuss-phase 2 # ← Clarify requirements (optional)\n/plan 2 # ← Plan next phase\n/execute 2 # ← Implement with atomic commits\n/verify 2 # ← Prove it works (screenshots, tests)\n/pause # ← Save state for later\n```\n\n> [!IMPORTANT]\n> GSD forces **planning before coding**. The AI can't write code until `SPEC.md` says `FINALIZED`. This prevents building the wrong thing.\n\n---\n\n## 🔒 Core Rules\n\n| | Rule | Why It Matters |\n|:---:|------|----------------|\n| 🔒 | **Planning Lock** | No code until `SPEC.md` is `FINALIZED` — prevents building wrong thing |\n| 💾 | **State Persistence** | Update `STATE.md` after every task — memory across sessions |\n| 🧹 | **Context Hygiene** | 3 failures → state dump → fresh session — prevents circular debugging |\n| ✅ | **Empirical Validation** | Proof required — no \"it should work\" |\n\n---\n\n## 🌍 Cross-Platform Support\n\nAll workflow files include **dual syntax** — both PowerShell and Bash commands.\n\n| Platform | Instructions |\n|:--------:|:------------:|\n| 🪟 **Windows** | Use PowerShell blocks |\n| 🐧 **Linux / Mac** | Use Bash blocks (may require `jq`) |\n\n> Git commands (`git add`, `git commit`, `git tag`) are cross-platform and work identically everywhere.\n\n---\n\n## 🤖 Multi-Model Support\n\nGSD is **model-agnostic** — use any LLM that works in your environment.\n\n### Canonical Rules\n\nAll rules live in [PROJECT_RULES.md](PROJECT_RULES.md) — the single source of truth.\n\n### Optional Adapters\n\nModel-specific enhancements *(optional, never required)*:\n\n```\nadapters/\n├── CLAUDE.md # Extended thinking, effort levels\n├── GEMINI.md # Flash vs Pro selection\n└── GPT_OSS.md # Function calling, context handling\n```\n\n### Model Selection by Phase\n\n| Phase | Recommended | Why |\n|:-----:|:-----------:|-----|\n| 📋 Planning | Reasoning models | Complex decisions |\n| ⚙️ Implementation | Fast models | Iteration speed |\n| 🐛 Debugging | Reasoning models | Hypothesis testing |\n| 🔍 Review | Long-context models | Full diff analysis |\n\n> See [model-selection-playbook.md](docs/model-selection-playbook.md) for detailed guidance.\n\n---\n\n## 🔍 Search-First Mode\n\n> **Principle:** Search before reading files completely.\n\n### Why?\n\n- 🎯 Reduces context pollution\n- ⚡ Faster codebase understanding\n- 🚫 Prevents reading irrelevant code\n\n
\nSetup (Optional)\n\n**PowerShell:**\n```powershell\n.\\scripts\\setup_search.ps1 # Checks for ripgrep/fd\n.\\scripts\\search_repo.ps1 \"pattern\" # Search wrapper\n```\n\n**Bash:**\n```bash\n./scripts/setup_search.sh # Checks for ripgrep/fd\n./scripts/search_repo.sh \"pattern\" # Search wrapper\n```\n\n> **No installation required** — falls back to built-in tools (`Select-String` / `grep`).\n\n
\n\n### Workflow\n\n1. **Define question** — What are you looking for?\n2. **Search first** — `.\\scripts\\search_repo.ps1 \"keyword\"`\n3. **Evaluate results** — Which files matter?\n4. **Targeted read** — Only read relevant sections\n\n---\n\n## 💰 Token Optimization\n\n> **Principle:** Minimize token consumption while maintaining quality.\n\n### Skills Available\n\n| Skill | Purpose |\n|-------|---------|\n| 📊 `token-budget` | Track and manage token usage |\n| 🗜️ `context-compressor` | Compress context for efficiency |\n| 🔍 `context-fetch` | Search-first loading |\n| 🩺 `context-health-monitor` | Detect quality degradation |\n\n### Budget Thresholds\n\n| Usage | Status | Action |\n|:-----:|:------:|--------|\n| 0–50% | 🟢 OK | Proceed normally |\n| 50–70% | 🟡 Warning | Compress, use outlines |\n| 70%+ | 🔴 Critical | State dump required |\n\n> See [token-optimization-guide.md](docs/token-optimization-guide.md) for complete strategies.\n\n---\n\n## 📁 File Structure\n\n```\n📄 PROJECT_RULES.md # ← Canonical rules (model-agnostic)\n📄 GSD-STYLE.md # Complete style guide\n\n📂 .agent/\n└── 📂 workflows/ # 27 slash commands\n\n📂 .agents/\n└── 📂 skills/ # 11 agent specializations (Agent Skills standard)\n\n📂 .gemini/\n└── 📄 GEMINI.md # Gemini integration\n\n📂 .gsd/\n├── 📄 SPEC.md # ← START HERE (finalize first)\n├── 📄 ROADMAP.md # Phases and progress\n├── 📄 STATE.md # Session memory\n├── 📄 ARCHITECTURE.md # System design (/map output)\n├── 📄 STACK.md # Tech inventory\n├── 📄 DECISIONS.md # Architecture Decision Records\n├── 📄 JOURNAL.md # Session log\n├── 📄 TODO.md # Quick capture\n├── 📂 templates/ # Document templates\n└── 📂 examples/ # Usage walkthroughs\n\n📂 adapters/ # Optional model-specific enhancements\n├── 📄 CLAUDE.md\n├── 📄 GEMINI.md\n└── 📄 GPT_OSS.md\n\n📂 docs/ # Operational documentation\n├── 📄 model-selection-playbook.md\n└── 📄 runbook.md\n\n📂 scripts/ # Utility scripts\n├── 📄 validate-*.ps1/.sh # Structure validators\n├── 📄 setup_search.ps1/.sh # Search tool setup\n└── 📄 search_repo.ps1/.sh # Search wrapper\n\n📄 model_capabilities.yaml # Optional capability registry\n```\n\n---\n\n## 🧪 Testing\n\nRun validation scripts to verify GSD structure:\n\n
\n🪟 PowerShell\n\n```powershell\n.\\scripts\\validate-all.ps1 # Run all validators\n.\\scripts\\validate-workflows.ps1 # Workflows only\n.\\scripts\\validate-skills.ps1 # Skills only\n```\n\n
\n\n
\n🐧 Bash\n\n```bash\n./scripts/validate-all.sh # Run all validators\n./scripts/validate-workflows.sh # Workflows only\n./scripts/validate-skills.sh # Skills only\n```\n\n
\n\n---\n\n## 📚 Documentation\n\n| Resource | Description |\n|----------|-------------|\n| [PROJECT_RULES.md](PROJECT_RULES.md) | Canonical model-agnostic rules |\n| [GSD-STYLE.md](GSD-STYLE.md) | Complete style and conventions guide |\n| [Model Selection Playbook](docs/model-selection-playbook.md) | Model selection guidance |\n| [Runbook](docs/runbook.md) | Operational procedures |\n| [Token Optimization Guide](docs/token-optimization-guide.md) | Token efficiency strategies |\n| [Examples](.gsd/examples/) | Usage walkthroughs and quick reference |\n| [Templates](.gsd/templates/) | Document templates for plans, verification |\n\n---\n\n## 🧠 Philosophy\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
🎯Plan before building — SPEC.md matters more than you think
🧹Fresh context > polluted context — State dumps prevent hallucinations
🔬Proof over trust — Screenshots and command outputs, not \"looks right\"
⚛️Aggressive atomicity — 2–3 tasks per plan, atomic commits
🔍Search before reading — Don't load files blindly
💰Token-efficient — Every token counts
🤖Model-agnostic — Works with any capable LLM
🚫No enterprise theater — Solo dev + AI workflow only
\n\n---\n\n
\n\nAdapted from glittercowboy/get-shit-done for Google Antigravity\n\n
\n\n[![GitHub](https://img.shields.io/badge/GitHub-toonight-181717?style=flat-square&logo=github)](https://github.com/toonight/get-shit-done-for-antigravity)\n\n
" }, { "path": "VERSION", "content": "1.5.0\n" }, { "path": "adapters/CLAUDE.md", "content": "# Claude Adapter\n\n> **Everything in this file is optional.**\n> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md).\n\nThis adapter provides optional enhancements for Claude models in Antigravity.\n\n---\n\n## Extended Thinking Mode\n\nWhen available, activate extended thinking for:\n\n| Task Type | Recommended |\n|-----------|-------------|\n| Architecture planning | ✅ High effort |\n| Complex debugging | ✅ High effort |\n| Security analysis | ✅ High effort |\n| Simple edits | ❌ Not needed |\n| Quick iterations | ❌ Overhead too high |\n\n### Effort Levels\n\nIf the model supports effort/budget levels:\n\n| Level | Use Case |\n|-------|----------|\n| `low` | Simple edits, formatting, comments |\n| `medium` | Standard implementation (default) |\n| `high` | Complex logic, refactoring, debugging |\n| `max` | Architecture, security, critical decisions |\n\n**Default:** `medium` if not specified.\n\n---\n\n## Artifacts Mode\n\nWhen artifacts are supported:\n\n- Use for code generation that needs preview\n- Use for documentation with formatting\n- Avoid for small inline edits\n\n---\n\n## Context Optimization\n\nClaude-specific context tips:\n\n1. **System prompt loading**: Core rules in system prompt, task details in user message\n2. **XML structure**: Claude parses XML well — use task XML format from GSD-STYLE.md\n3. **Conversation history**: Minimal history preferred; use STATE.md for continuity\n\n---\n\n## File Conventions\n\nNot required, but if organizing Claude-specific files:\n\n```\n.claude/\n├── CLAUDE.md # This adapter (if using)\n└── settings.json # IDE-specific settings\n```\n\n---\n\n## Anti-Patterns\n\n❌ **Using max effort for everything** — Slow and expensive\n❌ **Skipping verification** — Thinking mode doesn't guarantee correctness\n❌ **Depending on artifacts** — Not all Claude interfaces support them\n\n---\n\n*See PROJECT_RULES.md for canonical requirements.*\n" }, { "path": "adapters/GEMINI.md", "content": "# Gemini Adapter\n\n> **Everything in this file is optional.**\n> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md).\n\nThis adapter provides optional enhancements for Gemini models in Antigravity.\n\n---\n\n## Model Selection\n\n### Flash vs Pro\n\n| Model Type | Best For |\n|------------|----------|\n| **Flash** | Quick iterations, simple edits, high-volume tasks |\n| **Pro** | Complex planning, large refactors, deep analysis |\n\n**Default recommendation:** Start with Pro for planning, switch to Flash for implementation.\n\n---\n\n## Context Window Optimization\n\nGemini models often have large context windows. Optimize usage:\n\n1. **Load full files strategically** — Large context allows it, but still prefer search-first\n2. **Batch related files** — Group related code in single context load\n3. **Clear separation** — Use XML tags to separate file contents\n\n### Context Loading Pattern\n\n```xml\n\n{file contents}\n\n\n\n{file contents}\n\n\n\n{your task here}\n\n```\n\n---\n\n## Grounding\n\nWhen available, use grounding for:\n\n- Checking latest documentation\n- Verifying API behaviors\n- Validating external service states\n\n**Not for:** Code implementation (use codebase content).\n\n---\n\n## Code Execution\n\nIf code execution sandbox is available:\n\n- Use for verification commands\n- Use for testing snippets\n- Document outputs in SUMMARY.md\n\n---\n\n## Integration with .gemini/\n\nThe `.gemini/GEMINI.md` file can reference this adapter:\n\n```markdown\n# In .gemini/GEMINI.md\n\nFor canonical rules, see PROJECT_RULES.md.\nFor Gemini-specific tips, see adapters/GEMINI.md.\n```\n\n---\n\n## Anti-Patterns\n\n❌ **Loading entire codebase** — Even with large context, quality degrades\n❌ **Ignoring context thresholds** — 50% is still the quality boundary\n❌ **Skipping STATE.md** — Context window size doesn't replace persistent state\n\n---\n\n*See PROJECT_RULES.md for canonical requirements.*\n" }, { "path": "adapters/GPT_OSS.md", "content": "# GPT & Open Source Models Adapter\n\n> **Everything in this file is optional.**\n> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md).\n\nThis adapter provides guidance for GPT models and open-source alternatives.\n\n---\n\n## GPT Models\n\n### Model Selection\n\n| Model | Best For |\n|-------|----------|\n| **GPT-4o** | Balanced speed and quality, multimodal |\n| **GPT-4 Turbo** | Complex reasoning, large context |\n| **GPT-3.5** | Fast iterations, simple tasks |\n\n---\n\n### Function Calling\n\nWhen function calling is available:\n\n```json\n{\n \"name\": \"run_verification\",\n \"description\": \"Execute a verification command\",\n \"parameters\": {\n \"command\": \"npm test\",\n \"expected\": \"All tests pass\"\n }\n}\n```\n\n**Use for:**\n- Verification commands\n- File operations\n- External service checks\n\n---\n\n### Context Optimization\n\nGPT models may have smaller context than some alternatives:\n\n1. **Be selective** — Only load necessary files\n2. **Use search-first** — Critical for context efficiency\n3. **Summarize large files** — Extract relevant sections only\n\n---\n\n## Open Source Models\n\n### General Guidance\n\nOpen source models vary widely. General tips:\n\n| Consideration | Guidance |\n|---------------|----------|\n| **Context length** | Verify model's limit; adjust file loading |\n| **Instruction following** | Use explicit, structured prompts |\n| **Code quality** | May need more verification steps |\n| **Speed** | Varies by hardware; plan accordingly |\n\n---\n\n### Local Deployment\n\nFor locally-running models:\n\n1. **Resource planning** — Ensure adequate GPU/RAM\n2. **Latency expectations** — Adjust iteration speed assumptions\n3. **Fallback strategy** — Document when to switch to cloud models\n\n---\n\n### Recommended Patterns\n\n**Structured prompts work better:**\n\n```markdown\n## Task\n{clear task description}\n\n## Context\n{relevant code snippets}\n\n## Expected Output\n{what you need back}\n\n## Constraints\n{any limitations or requirements}\n```\n\n---\n\n## Shorter Context Strategies\n\nWhen working with limited context:\n\n1. **Aggressive search-first** — Never load full files blindly\n2. **Incremental loading** — Add context as needed, not upfront\n3. **State snapshots more frequently** — Prevent context overflow\n4. **Split large tasks** — Smaller plans, more waves\n\n---\n\n## Anti-Patterns\n\n❌ **Assuming GPT-4 context** — Verify actual model limits\n❌ **Complex nested prompts** — Keep structure flat and clear\n❌ **Ignoring model limits** — Quality crashes hard past context limit\n\n---\n\n## Model-Specific Files\n\nNot required, but if organizing:\n\n```\n.openai/ # For OpenAI API configuration\n.ollama/ # For Ollama local models\n.llm/ # Generic local LLM config\n```\n\n---\n\n*See PROJECT_RULES.md for canonical requirements.*\n" }, { "path": "docs/model-selection-playbook.md", "content": "# Model Selection Playbook\n\n> Guidance for choosing models by phase and task type.\n> \n> **No model is required.** These are recommendations, not requirements.\n\n---\n\n## Selection by Phase\n\n### Planning & Architecture\n\n**Recommended capabilities:**\n- Extended reasoning / thinking mode\n- Large context window (analyze multiple files)\n- Strong at structured output (specs, plans)\n\n**Why:** Planning requires understanding full system context and making architectural decisions.\n\n**Examples:** Models with \"thinking\" or \"reasoning\" modes, larger context variants.\n\n---\n\n### Code Implementation\n\n**Recommended capabilities:**\n- Fast iteration speed\n- Good at code completion\n- Tool/function calling (for verification commands)\n\n**Why:** Implementation involves many small changes with frequent verification cycles.\n\n**Examples:** Speed-tier models, code-specialized variants.\n\n---\n\n### Refactoring\n\n**Recommended capabilities:**\n- Large context window (see before/after)\n- Pattern recognition\n- Consistent style application\n\n**Why:** Refactoring requires maintaining consistency across large code changes.\n\n**Examples:** Standard or long-context variants.\n\n---\n\n### Debugging\n\n**Recommended capabilities:**\n- Extended reasoning (hypothesis generation)\n- Good at reading stack traces\n- Context for error patterns\n\n**Why:** Debugging requires hypothesis testing and pattern matching.\n\n**Examples:** Reasoning-focused models.\n\n---\n\n### Code Review\n\n**Recommended capabilities:**\n- Large context (review full PR diff)\n- Security pattern knowledge\n- Style consistency checking\n\n**Why:** Review requires seeing both code and context together.\n\n**Examples:** Long-context variants.\n\n---\n\n## Capability Tiers\n\n| Tier | Characteristics | Best For |\n|------|-----------------|----------|\n| **Fast** | Quick responses, lower cost | Implementation, iteration |\n| **Standard** | Balanced speed/quality | Most tasks |\n| **Reasoning** | Extended thinking, slower | Planning, debugging, architecture |\n| **Long-context** | >100k tokens | Review, refactoring |\n\n---\n\n## Anti-Patterns\n\n❌ **Using reasoning models for simple edits** — Overkill, slow, expensive\n\n❌ **Using fast models for architecture** — Insufficient depth for complex decisions\n\n❌ **Ignoring context limits** — Leads to quality degradation\n\n❌ **Forcing a specific model** — Breaks model-agnosticism\n\n---\n\n## Model Switching Mid-Session\n\n**When to switch:**\n- Context is getting polluted (approaching 50%)\n- Task type changes significantly (planning → implementation)\n- Current model struggling with task type\n\n**How to switch:**\n1. Create state snapshot\n2. Update STATE.md with current position\n3. Start fresh session with appropriate model\n4. Load STATE.md to resume\n\n---\n\n## GSD Model-Agnostic Principle\n\nGSD works with any capable LLM. The methodology compensates for model differences through:\n\n1. **Structured plans** — Reduce ambiguity\n2. **Explicit verification** — Catch errors regardless of model\n3. **State persistence** — Enable model switching\n4. **Fresh context** — Prevent accumulation issues\n\nChoose models based on task needs, not methodology requirements.\n\n---\n\n*See PROJECT_RULES.md for canonical rules.*\n*See docs/runbook.md for operational procedures.*\n" }, { "path": "docs/runbook.md", "content": "# GSD Runbook\n\n> Operational procedures for debugging, validation, and recovery.\n\n---\n\n## Quick Commands\n\n### Status Check\n\n**PowerShell:**\n```powershell\n# Current git status\ngit status\n\n# Recent commits\ngit log --oneline -10\n\n# Current branch\ngit branch --show-current\n```\n\n**Bash:**\n```bash\n# Current git status\ngit status\n\n# Recent commits\ngit log --oneline -10\n\n# Current branch\ngit branch --show-current\n```\n\n---\n\n## Wave Validation\n\n### Verify Wave Completion\n\n**Before marking a wave complete:**\n\n1. All tasks have commits:\n ```powershell\n git log --oneline -N # N = number of tasks in wave\n ```\n\n2. All verifications passed (documented in SUMMARY.md)\n\n3. STATE.md updated with current position\n\n4. State snapshot created\n\n### Wave Rollback\n\n**If a wave needs to be reverted:**\n\n```powershell\n# Find commit before wave started\ngit log --oneline -20\n\n# Reset to that commit (keeps changes staged)\ngit reset --soft \n\n# Or hard reset (discards changes)\ngit reset --hard \n```\n\n---\n\n## Debugging Procedures\n\n### 3-Strike Rule\n\nAfter 3 consecutive failed debug attempts:\n\n1. **Stop** — Don't try a 4th approach in same session\n\n2. **Document** in STATE.md:\n ```markdown\n ## Debug Session\n \n **Problem:** {description}\n \n **Attempts:**\n 1. {approach 1} → {result}\n 2. {approach 2} → {result}\n 3. {approach 3} → {result}\n \n **Hypothesis:** {current theory}\n \n **Recommended next:** {suggested approach}\n ```\n\n3. **Fresh session** — Start new conversation with documented context\n\n### Log Inspection\n\n**Find relevant logs:**\n\n```powershell\n# Search for error patterns\nSelect-String -Path \"*.log\" -Pattern \"error|exception|failed\" -CaseSensitive:$false\n```\n\n```bash\n# Search for error patterns\ngrep -ri \"error\\|exception\\|failed\" *.log\n```\n\n---\n\n## Verification Commands\n\n### Build Verification\n\n```powershell\n# Node.js\nnpm run build\nif ($LASTEXITCODE -eq 0) { Write-Host \"✅ Build passed\" }\n\n# Python\npython -m py_compile src/**/*.py\n```\n\n### Test Verification\n\n```powershell\n# Node.js\nnpm test\n\n# Python\npytest -v\n\n# Go\ngo test ./...\n```\n\n### Lint Verification\n\n```powershell\n# Node.js\nnpm run lint\n\n# Python\nruff check .\n\n# Go\ngolangci-lint run\n```\n\n---\n\n## State Recovery\n\n### From STATE.md\n\nWhen resuming work:\n\n1. Read STATE.md for current position\n2. Check \"Last Action\" for context\n3. Follow \"Next Steps\" to continue\n4. Verify recent commits match documented progress\n\n### From Git History\n\nIf STATE.md is outdated:\n\n```powershell\n# See recent work\ngit log --oneline -20\n\n# Check specific commit details\ngit show --stat\n\n# View file at specific commit\ngit show :path/to/file\n```\n\n### Context Pollution Recovery\n\nIf quality is degrading mid-session:\n\n1. Create state snapshot immediately\n2. Update STATE.md with full context\n3. Commit any pending work\n4. Start fresh session\n5. Run `/resume` to reload context\n\n---\n\n## Search Commands\n\n### Find in Codebase\n\n**PowerShell:**\n```powershell\n# Find pattern in files\nSelect-String -Path \"src/**/*.ts\" -Pattern \"TODO\" -Recurse\n\n# Find files by name\nGet-ChildItem -Recurse -Filter \"*.config.*\"\n```\n\n**Bash:**\n```bash\n# Find pattern in files (with ripgrep)\nrg \"TODO\" --type ts\n\n# Find pattern in files (with grep)\ngrep -r \"TODO\" src/\n\n# Find files by name\nfind . -name \"*.config.*\"\n```\n\n### Search-First Workflow\n\nBefore reading any file:\n\n1. Search for relevant terms:\n ```powershell\n Select-String -Path \"**/*.md\" -Pattern \"architecture\" -Recurse\n ```\n\n2. Identify candidate files from results\n\n3. Read only relevant sections:\n ```powershell\n Get-Content file.md | Select-Object -Skip 49 -First 20 # Lines 50-70\n ```\n\n---\n\n## Common Issues\n\n### \"SPEC.md not FINALIZED\"\n\n**Cause:** Planning lock prevents implementation\n\n**Fix:**\n1. Open `.gsd/SPEC.md`\n2. Complete all required sections\n3. Change status to `Status: FINALIZED`\n4. Retry command\n\n### \"Context degrading\"\n\n**Symptoms:** Shorter responses, skipped steps, inconsistency\n\n**Fix:**\n1. Create state snapshot\n2. Commit current work\n3. Start fresh session\n4. Run `/resume`\n\n### \"Commit failed\"\n\n**Causes:** Staged conflicts, hook failures\n\n**Debug:**\n```powershell\ngit status\ngit diff --staged\n```\n\n---\n\n## Checklist Templates\n\n### Pre-Execution Checklist\n\n- [ ] SPEC.md is FINALIZED\n- [ ] ROADMAP.md has current phase\n- [ ] STATE.md loaded and understood\n- [ ] Previous wave verified complete\n\n### Post-Wave Checklist\n\n- [ ] All tasks committed\n- [ ] Verifications documented\n- [ ] STATE.md updated\n- [ ] State snapshot created\n- [ ] No uncommitted changes\n\n### Session End Checklist\n\n- [ ] Current work committed\n- [ ] STATE.md has \"Next Steps\"\n- [ ] JOURNAL.md updated (if milestone)\n- [ ] No loose ends\n\n---\n\n*See PROJECT_RULES.md for canonical rules.*\n*See docs/model-selection-playbook.md for model guidance.*\n" }, { "path": "docs/token-optimization-guide.md", "content": "# Token Optimization Guide\n\n> Practical strategies for reducing token consumption while maintaining quality.\n\n---\n\n## Why Token Optimization Matters\n\n| Issue | Impact |\n|-------|--------|\n| Excessive file loading | Higher costs, slower responses |\n| Context accumulation | Quality degradation after 50% |\n| Re-reading files | Wasted tokens on understood content |\n| Full files when snippets suffice | 10x token usage |\n\n**Goal:** Maximize output quality per token spent.\n\n---\n\n## The Token Efficiency Stack\n\n```\n┌─────────────────────────────────────┐\n│ 1. Search-First (context-fetch) │ ← Find before loading\n├─────────────────────────────────────┤\n│ 2. Budget Tracking (token-budget) │ ← Know your limits\n├─────────────────────────────────────┤\n│ 3. Compression (context-compressor)│ ← Minimize footprint\n├─────────────────────────────────────┤\n│ 4. Health Monitoring │ ← Prevent degradation\n└─────────────────────────────────────┘\n```\n\n---\n\n## Quick Reference: Token Costs\n\n### By Content Type\n\n| Type | Tokens/Line | 100 Lines = |\n|------|-------------|-------------|\n| Dense code | 6 | ~600 tokens |\n| Standard code | 4 | ~400 tokens |\n| Markdown | 3 | ~300 tokens |\n| Sparse YAML | 2 | ~200 tokens |\n\n### By File Size\n\n| File Lines | Strategy |\n|------------|----------|\n| <50 | Load freely |\n| 50-200 | Outline first |\n| 200-500 | Search + snippets |\n| 500+ | Never load fully |\n\n---\n\n## Optimization Patterns\n\n### Pattern 1: Search → Outline → Target\n\n```\nStep 1: Search for \"handlePayment\"\n → Found in: payment.ts:45, checkout.ts:120\n\nStep 2: Get outline of payment.ts\n → L45-80: handlePayment function\n\nStep 3: Load only L45-80\n → 35 lines (~140 tokens) vs 400 lines (~1600 tokens)\n → Saved: ~90%\n```\n\n### Pattern 2: Summarize After Understanding\n\n```\nAfter reading auth.ts:\n\n## Summary: auth.ts\n- Exports: login, logout, validateToken\n- Pattern: Express middleware\n- DB: queries users table\n- JWT: uses jose library\n\nNext time: Reference summary, don't reload\n```\n\n### Pattern 3: Progressive Disclosure\n\n```\nNeed: Understand login flow\n\nLevel 1: Outline\n → \"login at L45, uses validateCredentials at L67\"\n → Often sufficient\n\nLevel 2: Key function\n → Load L45-65 only\n → Understand core logic\n\nLevel 3: Dependencies\n → Load validateCredentials (L67-85)\n → Only if L2 insufficient\n\nLevel 4: Full file\n → Last resort, re-compress after\n```\n\n---\n\n## Anti-Patterns to Avoid\n\n### ❌ The \"Context Dump\"\n\n```\nBAD:\n\"Let me read all the files in src/ to understand the project\"\n→ 50 files × 200 lines × 4 tokens = 40,000 tokens\n\nGOOD:\n\"Let me search for 'main entry' and 'router'\"\n→ 2 targeted searches, ~500 tokens\n```\n\n### ❌ The \"Just In Case\" Load\n\n```\nBAD:\n\"Loading utils.ts in case I need it later\"\n→ Probably won't need it, wasted tokens\n\nGOOD:\n\"Noting utils.ts exists, will load if needed\"\n→ Zero tokens until actually needed\n```\n\n### ❌ The Re-Read\n\n```\nBAD:\n\"Reading config.ts again to check the port\"\n→ Already read it twice = 1200 tokens\n\nGOOD:\n\"From my earlier analysis, port is on L15\"\n→ Zero additional tokens\n```\n\n---\n\n## Budget Checkpoints\n\n### Before Starting Work\n\n```markdown\n□ Do I know my current budget usage?\n□ Have I tried searching before loading?\n□ Am I loading files I've already understood?\n```\n\n### During Execution\n\n```markdown\n□ Am I at >50%? Time to compress.\n□ Am I re-reading files? Use summaries.\n□ Can I use outline instead of full file?\n```\n\n### After Each Wave\n\n```markdown\n□ Have I compressed context for next wave?\n□ Are summaries documented in STATE.md?\n□ Would a fresh session be more efficient?\n```\n\n---\n\n## Integration with GSD\n\n| GSD Workflow | Token Optimization |\n|--------------|-------------------|\n| `/map` | Generate outline, not full read |\n| `/plan` | Budget estimate per task |\n| `/execute` | Load minimal per task |\n| `/verify` | Targeted evidence only |\n| `/pause` | Compress and dump state |\n\n---\n\n## Metrics\n\nTrack these for improvement:\n\n| Metric | Good | Poor |\n|--------|------|------|\n| Files fully loaded | <3 per wave | 10+ |\n| Search:Load ratio | 3:1 | 1:3 |\n| Re-reads | 0 | 3+ |\n| Budget at wave end | <50% | >70% |\n\n---\n\n*See also:*\n- *[.agents/skills/token-budget/SKILL.md](.agents/skills/token-budget/SKILL.md)*\n- *[.agents/skills/context-compressor/SKILL.md](.agents/skills/context-compressor/SKILL.md)*\n- *[PROJECT_RULES.md](PROJECT_RULES.md) — Token Efficiency Rules*\n" }, { "path": "model_capabilities.yaml", "content": "# Model Capabilities Registry\n#\n# This file is OPTIONAL. GSD works without it.\n# If present, it provides guidance for model selection.\n#\n# Usage: Reference this file when choosing models by capability.\n# Do NOT make any workflow depend on this file existing.\n\n# Capability definitions\ncapabilities:\n thinking_mode:\n description: \"Extended reasoning with internal monologue\"\n benefits:\n - Better for complex planning\n - Improved debugging hypotheses\n - More thorough architecture analysis\n \n long_context:\n description: \"Context window > 100k tokens\"\n benefits:\n - Can analyze multiple files at once\n - Better for large refactors\n - Full codebase reviews\n \n tools:\n description: \"Function/tool calling support\"\n benefits:\n - Execute verification commands\n - Interact with external systems\n - Structured outputs\n \n speed_tier:\n description: \"Response latency tier\"\n values:\n - fast: \"< 2s average, good for iteration\"\n - standard: \"2-5s average, balanced\"\n - reasoning: \"> 5s average, deep analysis\"\n\n# Example model profiles (illustrative, not exhaustive)\n# These show how to categorize models by capability type.\n\nprofiles:\n # Fast iteration models\n fast_coder:\n speed_tier: fast\n thinking_mode: false\n long_context: false\n tools: true\n best_for:\n - Quick edits\n - Simple implementations\n - Frequent iteration cycles\n examples:\n - \"Flash/Turbo variants\"\n - \"Smaller parameter models\"\n \n # Standard balanced models\n standard:\n speed_tier: standard\n thinking_mode: false\n long_context: true\n tools: true\n best_for:\n - Most development tasks\n - Moderate refactoring\n - General coding\n examples:\n - \"Pro/Standard variants\"\n - \"Mid-tier models\"\n \n # Deep reasoning models\n reasoning:\n speed_tier: reasoning\n thinking_mode: true\n long_context: true\n tools: true\n best_for:\n - Architecture planning\n - Complex debugging\n - Security analysis\n examples:\n - \"Thinking/Reasoning variants\"\n - \"Advanced reasoning models\"\n\n# Phase recommendations (suggestions, not requirements)\nphase_recommendations:\n planning:\n preferred_profile: reasoning\n reason: \"Complex decisions benefit from extended thinking\"\n \n implementation:\n preferred_profile: fast_coder\n reason: \"Frequent iteration needs speed\"\n \n refactoring:\n preferred_profile: standard\n reason: \"Balance of context and speed\"\n \n debugging:\n preferred_profile: reasoning\n reason: \"Hypothesis generation needs depth\"\n \n review:\n preferred_profile: standard\n reason: \"Large context for full diffs\"\n\n# IMPORTANT: This file is for guidance only.\n# Never fail a workflow because a specific model capability is missing.\n" }, { "path": "scripts/search_repo.ps1", "content": "# search_repo.ps1 - Search codebase with best available tool\n#\n# Usage: .\\scripts\\search_repo.ps1 [path] [options]\n#\n# Examples:\n# .\\scripts\\search_repo.ps1 \"TODO\"\n# .\\scripts\\search_repo.ps1 \"function.*login\" -Path \"src/\"\n# .\\scripts\\search_repo.ps1 \"error\" -FileType \"ts\"\n\nparam(\n [Parameter(Mandatory = $true, Position = 0)]\n [string]$Pattern,\n \n [Parameter(Position = 1)]\n [string]$Path = \".\",\n \n [Parameter()]\n [string]$FileType,\n \n [Parameter()]\n [switch]$CaseSensitive\n)\n\n# Try ripgrep first (fastest)\n$rgAvailable = Get-Command rg -ErrorAction SilentlyContinue\n\nif ($rgAvailable) {\n Write-Host \"# Using ripgrep\" -ForegroundColor Gray\n \n $rgArgs = @($Pattern, $Path, \"--color=always\")\n \n if ($FileType) {\n $rgArgs += \"--type\"\n $rgArgs += $FileType\n }\n \n if ($CaseSensitive) {\n $rgArgs += \"--case-sensitive\"\n }\n \n & rg @rgArgs\n exit $LASTEXITCODE\n}\n\n# Fall back to Select-String\nWrite-Host \"# Using Select-String (install ripgrep for better performance)\" -ForegroundColor Gray\n\n$searchParams = @{\n Pattern = $Pattern\n Path = $Path\n}\n\n# Build file filter\nif ($FileType) {\n $searchParams.Include = \"*.$FileType\"\n}\n\nif (-not $CaseSensitive) {\n $searchParams.CaseSensitive = $false\n}\n\n# Handle directory vs file\nif (Test-Path $Path -PathType Container) {\n $searchParams.Path = Join-Path $Path \"*\"\n $searchParams.Recurse = $true\n}\n\ntry {\n $results = Get-ChildItem -Path $Path -Recurse -File -ErrorAction SilentlyContinue |\n Where-Object { \n if ($FileType) { \n $_.Extension -eq \".$FileType\" \n }\n else { \n $true \n } \n } |\n Select-String -Pattern $Pattern -CaseSensitive:$CaseSensitive\n \n if ($results) {\n $results | ForEach-Object {\n $relativePath = $_.Path\n $lineNum = $_.LineNumber\n $line = $_.Line\n Write-Host \"${relativePath}:${lineNum}:${line}\"\n }\n }\n else {\n Write-Host \"No matches found for: $Pattern\"\n }\n}\ncatch {\n Write-Host \"Search error: $_\" -ForegroundColor Red\n exit 1\n}\n" }, { "path": "scripts/search_repo.sh", "content": "#!/bin/bash\n# search_repo.sh - Search codebase with best available tool\n#\n# Usage: ./scripts/search_repo.sh [path] [options]\n#\n# Examples:\n# ./scripts/search_repo.sh \"TODO\"\n# ./scripts/search_repo.sh \"function.*login\" src/\n# ./scripts/search_repo.sh \"error\" --type ts\n\nset -e\n\nPATTERN=\"${1:-}\"\nSEARCH_PATH=\"${2:-.}\"\nshift 2 2>/dev/null || true\nEXTRA_ARGS=\"$@\"\n\nif [[ -z \"$PATTERN\" ]]; then\n echo \"Usage: search_repo.sh [path] [options]\"\n echo \"\"\n echo \"Examples:\"\n echo \" ./scripts/search_repo.sh 'TODO'\"\n echo \" ./scripts/search_repo.sh 'login' src/\"\n echo \" ./scripts/search_repo.sh 'error' . --type ts\"\n exit 1\nfi\n\n# Try ripgrep first (fastest)\nif command -v rg &> /dev/null; then\n echo \"# Using ripgrep\" >&2\n rg \"$PATTERN\" \"$SEARCH_PATH\" $EXTRA_ARGS --color=always\n exit $?\nfi\n\n# Fall back to grep\necho \"# Using grep (install ripgrep for better performance)\" >&2\n\n# Convert common rg options to grep options\nGREP_ARGS=\"\"\nfor arg in $EXTRA_ARGS; do\n case \"$arg\" in\n --type)\n # Next argument is the type, skip both\n ;;\n ts|js|py|go|rs|md)\n GREP_ARGS=\"$GREP_ARGS --include=*.$arg\"\n ;;\n *)\n # Pass through other arguments\n GREP_ARGS=\"$GREP_ARGS $arg\"\n ;;\n esac\ndone\n\ngrep -rn \"$PATTERN\" \"$SEARCH_PATH\" $GREP_ARGS --color=always 2>/dev/null || {\n echo \"No matches found for: $PATTERN\"\n exit 0\n}\n" }, { "path": "scripts/setup_search.ps1", "content": "# setup_search.ps1 - Optional search tool setup for GSD\n#\n# This script checks for and provides guidance on installing search tools.\n# GSD works without these tools (falls back to Select-String), but they improve performance.\n\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \" GSD ► Search Tools Setup\" -ForegroundColor Cyan\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \"\"\n\n$rgInstalled = $false\n$fdInstalled = $false\n\n# Check for ripgrep\nWrite-Host \"Checking search tools...\" -ForegroundColor White\nWrite-Host \"\"\n\ntry {\n $rgVersion = & rg --version 2>$null\n if ($rgVersion) {\n Write-Host \"✅ ripgrep (rg) is installed: $($rgVersion[0])\" -ForegroundColor Green\n $rgInstalled = $true\n }\n}\ncatch {\n Write-Host \"❌ ripgrep (rg) is not installed\" -ForegroundColor Yellow\n}\n\n# Check for fd\ntry {\n $fdVersion = & fd --version 2>$null\n if ($fdVersion) {\n Write-Host \"✅ fd is installed: $fdVersion\" -ForegroundColor Green\n $fdInstalled = $true\n }\n}\ncatch {\n Write-Host \"❌ fd is not installed\" -ForegroundColor Yellow\n}\n\nWrite-Host \"\"\n\nif ($rgInstalled -and $fdInstalled) {\n Write-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Green\n Write-Host \" ✅ All search tools are ready!\" -ForegroundColor Green\n Write-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Green\n Write-Host \"\"\n Write-Host \"You can use .\\scripts\\search_repo.ps1 for optimized searching.\"\n}\nelse {\n Write-Host \"⚠️ Some tools are missing (optional)\" -ForegroundColor Yellow\n Write-Host \"\"\n Write-Host \"GSD will work fine with built-in Select-String, but ripgrep and fd\"\n Write-Host \"provide faster searching in large codebases.\"\n Write-Host \"\"\n Write-Host \"───────────────────────────────────────────────────────\" -ForegroundColor Gray\n Write-Host \"📦 Installation Options\" -ForegroundColor White\n Write-Host \"───────────────────────────────────────────────────────\" -ForegroundColor Gray\n Write-Host \"\"\n \n # Check for package managers\n $hasWinget = Get-Command winget -ErrorAction SilentlyContinue\n $hasChoco = Get-Command choco -ErrorAction SilentlyContinue\n $hasScoop = Get-Command scoop -ErrorAction SilentlyContinue\n \n if ($hasWinget) {\n Write-Host \"Using winget:\" -ForegroundColor Cyan\n Write-Host \" winget install BurntSushi.ripgrep.MSVC\"\n Write-Host \" winget install sharkdp.fd\"\n Write-Host \"\"\n }\n \n if ($hasChoco) {\n Write-Host \"Using Chocolatey:\" -ForegroundColor Cyan\n Write-Host \" choco install ripgrep fd\"\n Write-Host \"\"\n }\n \n if ($hasScoop) {\n Write-Host \"Using Scoop:\" -ForegroundColor Cyan\n Write-Host \" scoop install ripgrep fd\"\n Write-Host \"\"\n }\n \n if (-not ($hasWinget -or $hasChoco -or $hasScoop)) {\n Write-Host \"Download binaries from:\" -ForegroundColor Cyan\n Write-Host \" ripgrep: https://github.com/BurntSushi/ripgrep/releases\"\n Write-Host \" fd: https://github.com/sharkdp/fd/releases\"\n Write-Host \"\"\n }\n \n Write-Host \"───────────────────────────────────────────────────────\" -ForegroundColor Gray\n Write-Host \"\"\n Write-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\n Write-Host \" GSD ► Using Select-String as fallback (works fine!)\" -ForegroundColor Cyan\n Write-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\n}\n" }, { "path": "scripts/setup_search.sh", "content": "#!/bin/bash\n# setup_search.sh - Optional search tool setup for GSD\n#\n# This script checks for and optionally installs search tools.\n# GSD works without these tools (falls back to grep), but they improve performance.\n\nset -e\n\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \" GSD ► Search Tools Setup\"\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \"\"\n\n# Check for ripgrep\ncheck_ripgrep() {\n if command -v rg &> /dev/null; then\n echo \"✅ ripgrep (rg) is installed: $(rg --version | head -n1)\"\n return 0\n else\n echo \"❌ ripgrep (rg) is not installed\"\n return 1\n fi\n}\n\n# Check for fd\ncheck_fd() {\n if command -v fd &> /dev/null; then\n echo \"✅ fd is installed: $(fd --version)\"\n return 0\n elif command -v fdfind &> /dev/null; then\n echo \"✅ fd is installed (as fdfind): $(fdfind --version)\"\n return 0\n else\n echo \"❌ fd is not installed\"\n return 1\n fi\n}\n\n# Installation suggestions\nsuggest_install() {\n echo \"\"\n echo \"───────────────────────────────────────────────────────\"\n echo \"📦 Installation Options\"\n echo \"───────────────────────────────────────────────────────\"\n echo \"\"\n \n # Detect OS\n if [[ \"$OSTYPE\" == \"darwin\"* ]]; then\n echo \"macOS detected. Install with Homebrew:\"\n echo \" brew install ripgrep fd\"\n elif [[ -f /etc/debian_version ]]; then\n echo \"Debian/Ubuntu detected. Install with apt:\"\n echo \" sudo apt install ripgrep fd-find\"\n echo \" # Note: fd is installed as 'fdfind' on Debian\"\n elif [[ -f /etc/fedora-release ]]; then\n echo \"Fedora detected. Install with dnf:\"\n echo \" sudo dnf install ripgrep fd-find\"\n elif [[ -f /etc/arch-release ]]; then\n echo \"Arch Linux detected. Install with pacman:\"\n echo \" sudo pacman -S ripgrep fd\"\n else\n echo \"Install from source or package manager:\"\n echo \" ripgrep: https://github.com/BurntSushi/ripgrep\"\n echo \" fd: https://github.com/sharkdp/fd\"\n fi\n \n echo \"\"\n echo \"───────────────────────────────────────────────────────\"\n}\n\n# Main\necho \"Checking search tools...\"\necho \"\"\n\nRG_OK=0\nFD_OK=0\n\ncheck_ripgrep && RG_OK=1\ncheck_fd && FD_OK=1\n\necho \"\"\n\nif [[ $RG_OK -eq 1 && $FD_OK -eq 1 ]]; then\n echo \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\n echo \" ✅ All search tools are ready!\"\n echo \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\n echo \"\"\n echo \"You can use ./scripts/search_repo.sh for optimized searching.\"\n exit 0\nelse\n echo \"⚠️ Some tools are missing (optional)\"\n echo \"\"\n echo \"GSD will work fine with built-in grep, but ripgrep and fd\"\n echo \"provide faster searching in large codebases.\"\n \n suggest_install\n \n echo \"\"\n echo \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\n echo \" GSD ► Using grep as fallback (works fine!)\"\n echo \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\n exit 0\nfi\n" }, { "path": "scripts/validate-all.ps1", "content": "# GSD Master Validation Script\n# Runs all validators and reports overall status\n\n$TotalErrors = 0\n\nWrite-Host \"\"\nWrite-Host \"╔═══════════════════════════════════════════════════════╗\" -ForegroundColor Magenta\nWrite-Host \"║ GSD ► RUNNING ALL VALIDATORS ║\" -ForegroundColor Magenta\nWrite-Host \"╚═══════════════════════════════════════════════════════╝\" -ForegroundColor Magenta\nWrite-Host \"\"\n\n# Run workflow validator\nWrite-Host \"▶ Running workflow validation...\" -ForegroundColor Cyan\n& \"$PSScriptRoot\\validate-workflows.ps1\"\nif ($LASTEXITCODE -ne 0) { $TotalErrors++ }\nWrite-Host \"\"\n\n# Run skill validator\nWrite-Host \"▶ Running skill validation...\" -ForegroundColor Cyan\n& \"$PSScriptRoot\\validate-skills.ps1\"\nif ($LASTEXITCODE -ne 0) { $TotalErrors++ }\nWrite-Host \"\"\n\n# Run template validator\nWrite-Host \"▶ Running template validation...\" -ForegroundColor Cyan\n& \"$PSScriptRoot\\validate-templates.ps1\"\nif ($LASTEXITCODE -ne 0) { $TotalErrors++ }\nWrite-Host \"\"\n\n# Summary\nWrite-Host \"╔═══════════════════════════════════════════════════════╗\" -ForegroundColor Magenta\nWrite-Host \"║ SUMMARY ║\" -ForegroundColor Magenta\nWrite-Host \"╚═══════════════════════════════════════════════════════╝\" -ForegroundColor Magenta\nWrite-Host \"\"\n\nif ($TotalErrors -eq 0) {\n Write-Host \"✅ All validators passed!\" -ForegroundColor Green\n exit 0\n} else {\n Write-Host \"❌ $TotalErrors validator(s) failed\" -ForegroundColor Red\n exit 1\n}\n" }, { "path": "scripts/validate-all.sh", "content": "#!/bin/bash\n# GSD Master Validation Script\n# Runs all validators and reports overall status\n\ntotal_errors=0\nscript_dir=\"$(dirname \"$0\")\"\n\necho \"\"\necho \"╔═══════════════════════════════════════════════════════╗\"\necho \"║ GSD ► RUNNING ALL VALIDATORS ║\"\necho \"╚═══════════════════════════════════════════════════════╝\"\necho \"\"\n\n# Run workflow validator\necho \"▶ Running workflow validation...\"\n\"$script_dir/validate-workflows.sh\"\nif [ $? -ne 0 ]; then ((total_errors++)); fi\necho \"\"\n\n# Run skill validator\necho \"▶ Running skill validation...\"\n\"$script_dir/validate-skills.sh\"\nif [ $? -ne 0 ]; then ((total_errors++)); fi\necho \"\"\n\n# Run template validator\necho \"▶ Running template validation...\"\n\"$script_dir/validate-templates.sh\"\nif [ $? -ne 0 ]; then ((total_errors++)); fi\necho \"\"\n\n# Summary\necho \"╔═══════════════════════════════════════════════════════╗\"\necho \"║ SUMMARY ║\"\necho \"╚═══════════════════════════════════════════════════════╝\"\necho \"\"\n\nif [ $total_errors -eq 0 ]; then\n echo \"✅ All validators passed!\"\n exit 0\nelse\n echo \"❌ $total_errors validator(s) failed\"\n exit 1\nfi\n" }, { "path": "scripts/validate-skills.ps1", "content": "# GSD Skill Validation Script\n# Validates all skill directories for required structure\n\n$ErrorCount = 0\n$WarningCount = 0\n$SkillsChecked = 0\n\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \" GSD ► VALIDATING SKILLS\" -ForegroundColor Cyan\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \"\"\n\n$skills = Get-ChildItem \".agents/skills\" -Directory\n\nforeach ($skill in $skills) {\n $SkillsChecked++\n $skillFile = Join-Path $skill.FullName \"SKILL.md\"\n $hasErrors = $false\n \n # Check SKILL.md exists\n if (-not (Test-Path $skillFile)) {\n Write-Host \"❌ $($skill.Name): Missing SKILL.md\" -ForegroundColor Red\n $ErrorCount++\n continue\n }\n \n $content = Get-Content $skillFile -Raw\n \n # Check for frontmatter\n if ($content -notmatch \"^---\") {\n Write-Host \"❌ $($skill.Name): Missing frontmatter\" -ForegroundColor Red\n $ErrorCount++\n $hasErrors = $true\n }\n \n # Check for name field\n if ($content -notmatch \"name:\") {\n Write-Host \"❌ $($skill.Name): Missing name in frontmatter\" -ForegroundColor Red\n $ErrorCount++\n $hasErrors = $true\n }\n \n # Check for description field\n if ($content -notmatch \"description:\") {\n Write-Host \"❌ $($skill.Name): Missing description in frontmatter\" -ForegroundColor Red\n $ErrorCount++\n $hasErrors = $true\n }\n \n if (-not $hasErrors) {\n Write-Host \"✅ $($skill.Name)\" -ForegroundColor Green\n }\n}\n\nWrite-Host \"\"\nWrite-Host \"───────────────────────────────────────────────────────\" -ForegroundColor Gray\nWrite-Host \"\"\nWrite-Host \"Skills checked: $SkillsChecked\"\nWrite-Host \"Errors: $ErrorCount\" -ForegroundColor $(if ($ErrorCount -gt 0) { \"Red\" } else { \"Green\" })\nWrite-Host \"\"\n\nif ($ErrorCount -eq 0) {\n Write-Host \"✅ All skills valid!\" -ForegroundColor Green\n exit 0\n} else {\n Write-Host \"❌ Validation failed\" -ForegroundColor Red\n exit 1\n}\n" }, { "path": "scripts/validate-skills.sh", "content": "#!/bin/bash\n# GSD Skill Validation Script\n# Validates all skill directories for required structure\n\nerror_count=0\nskills_checked=0\n\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \" GSD ► VALIDATING SKILLS\"\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \"\"\n\nfor skill_dir in .agents/skills/*/; do\n ((skills_checked++))\n skill_name=$(basename \"$skill_dir\")\n skill_file=\"$skill_dir/SKILL.md\"\n has_errors=false\n \n # Check SKILL.md exists\n if [ ! -f \"$skill_file\" ]; then\n echo \"❌ $skill_name: Missing SKILL.md\"\n ((error_count++))\n continue\n fi\n \n # Check for frontmatter\n if ! head -1 \"$skill_file\" | grep -q \"^---\"; then\n echo \"❌ $skill_name: Missing frontmatter\"\n ((error_count++))\n has_errors=true\n fi\n \n # Check for name field\n if ! grep -q \"name:\" \"$skill_file\"; then\n echo \"❌ $skill_name: Missing name in frontmatter\"\n ((error_count++))\n has_errors=true\n fi\n \n # Check for description field\n if ! grep -q \"description:\" \"$skill_file\"; then\n echo \"❌ $skill_name: Missing description in frontmatter\"\n ((error_count++))\n has_errors=true\n fi\n \n if [ \"$has_errors\" = false ]; then\n echo \"✅ $skill_name\"\n fi\ndone\n\necho \"\"\necho \"───────────────────────────────────────────────────────\"\necho \"\"\necho \"Skills checked: $skills_checked\"\necho \"Errors: $error_count\"\necho \"\"\n\nif [ $error_count -eq 0 ]; then\n echo \"✅ All skills valid!\"\n exit 0\nelse\n echo \"❌ Validation failed\"\n exit 1\nfi\n" }, { "path": "scripts/validate-templates.ps1", "content": "# GSD Template Validation Script\n# Validates all template files in .gsd/templates/\n\n$ErrorCount = 0\n$WarningCount = 0\n$TemplatesChecked = 0\n\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \" GSD ► VALIDATING TEMPLATES\" -ForegroundColor Cyan\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \"\"\n\n$templates = Get-ChildItem \".gsd/templates/*.md\"\n\nforeach ($file in $templates) {\n $TemplatesChecked++\n $content = Get-Content $file.FullName -Raw\n $hasErrors = $false\n \n # Check for title (# heading)\n if ($content -notmatch \"^# \") {\n Write-Host \"❌ $($file.Name): Missing title (# heading)\" -ForegroundColor Red\n $ErrorCount++\n $hasErrors = $true\n }\n \n # Check for Last updated marker\n if ($content -notmatch \"Last updated\") {\n Write-Host \"⚠️ $($file.Name): Missing 'Last updated' marker\" -ForegroundColor Yellow\n $WarningCount++\n }\n \n # Check minimum length (templates should have substance)\n if ($content.Length -lt 200) {\n Write-Host \"⚠️ $($file.Name): Very short template (<200 chars)\" -ForegroundColor Yellow\n $WarningCount++\n }\n \n if (-not $hasErrors) {\n Write-Host \"✅ $($file.Name)\" -ForegroundColor Green\n }\n}\n\nWrite-Host \"\"\nWrite-Host \"───────────────────────────────────────────────────────\" -ForegroundColor Gray\nWrite-Host \"\"\nWrite-Host \"Templates checked: $TemplatesChecked\"\nWrite-Host \"Errors: $ErrorCount\" -ForegroundColor $(if ($ErrorCount -gt 0) { \"Red\" } else { \"Green\" })\nWrite-Host \"Warnings: $WarningCount\" -ForegroundColor $(if ($WarningCount -gt 0) { \"Yellow\" } else { \"Green\" })\nWrite-Host \"\"\n\nif ($ErrorCount -eq 0) {\n Write-Host \"✅ All templates valid!\" -ForegroundColor Green\n exit 0\n} else {\n Write-Host \"❌ Validation failed\" -ForegroundColor Red\n exit 1\n}\n" }, { "path": "scripts/validate-templates.sh", "content": "#!/bin/bash\n# GSD Template Validation Script\n# Validates all template files in .gsd/templates/\n\nerror_count=0\nwarning_count=0\ntemplates_checked=0\n\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \" GSD ► VALIDATING TEMPLATES\"\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \"\"\n\nfor file in .gsd/templates/*.md; do\n ((templates_checked++))\n filename=$(basename \"$file\")\n has_errors=false\n \n # Check for title (# heading)\n if ! head -1 \"$file\" | grep -q \"^# \"; then\n echo \"❌ $filename: Missing title (# heading)\"\n ((error_count++))\n has_errors=true\n fi\n \n # Check for Last updated marker\n if ! grep -q \"Last updated\" \"$file\"; then\n echo \"⚠️ $filename: Missing 'Last updated' marker\"\n ((warning_count++))\n fi\n \n # Check minimum length\n file_size=$(wc -c < \"$file\")\n if [ \"$file_size\" -lt 200 ]; then\n echo \"⚠️ $filename: Very short template (<200 chars)\"\n ((warning_count++))\n fi\n \n if [ \"$has_errors\" = false ]; then\n echo \"✅ $filename\"\n fi\ndone\n\necho \"\"\necho \"───────────────────────────────────────────────────────\"\necho \"\"\necho \"Templates checked: $templates_checked\"\necho \"Errors: $error_count\"\necho \"Warnings: $warning_count\"\necho \"\"\n\nif [ $error_count -eq 0 ]; then\n echo \"✅ All templates valid!\"\n exit 0\nelse\n echo \"❌ Validation failed\"\n exit 1\nfi\n" }, { "path": "scripts/validate-workflows.ps1", "content": "# GSD Workflow Validation Script\n# Validates all workflow files for required structure\n\n$ErrorCount = 0\n$WarningCount = 0\n$WorkflowsChecked = 0\n\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \" GSD ► VALIDATING WORKFLOWS\" -ForegroundColor Cyan\nWrite-Host \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\" -ForegroundColor Cyan\nWrite-Host \"\"\n\n$workflows = Get-ChildItem \".agent/workflows/*.md\"\n\nforeach ($file in $workflows) {\n $WorkflowsChecked++\n $content = Get-Content $file.FullName -Raw\n $hasErrors = $false\n \n # Check for frontmatter\n if ($content -notmatch \"^---\") {\n Write-Host \"❌ $($file.Name): Missing frontmatter\" -ForegroundColor Red\n $ErrorCount++\n $hasErrors = $true\n }\n \n # Check for description\n if ($content -notmatch \"description:\") {\n Write-Host \"❌ $($file.Name): Missing description in frontmatter\" -ForegroundColor Red\n $ErrorCount++\n $hasErrors = $true\n }\n \n # Check for process tags (optional but recommended)\n if ($content -notmatch \"\") {\n Write-Host \"⚠️ $($file.Name): Missing tag\" -ForegroundColor Yellow\n $WarningCount++\n }\n \n if (-not $hasErrors) {\n Write-Host \"✅ $($file.Name)\" -ForegroundColor Green\n }\n}\n\nWrite-Host \"\"\nWrite-Host \"───────────────────────────────────────────────────────\" -ForegroundColor Gray\nWrite-Host \"\"\nWrite-Host \"Workflows checked: $WorkflowsChecked\"\nWrite-Host \"Errors: $ErrorCount\" -ForegroundColor $(if ($ErrorCount -gt 0) { \"Red\" } else { \"Green\" })\nWrite-Host \"Warnings: $WarningCount\" -ForegroundColor $(if ($WarningCount -gt 0) { \"Yellow\" } else { \"Green\" })\nWrite-Host \"\"\n\nif ($ErrorCount -eq 0) {\n Write-Host \"✅ All workflows valid!\" -ForegroundColor Green\n exit 0\n} else {\n Write-Host \"❌ Validation failed\" -ForegroundColor Red\n exit 1\n}\n" }, { "path": "scripts/validate-workflows.sh", "content": "#!/bin/bash\n# GSD Workflow Validation Script\n# Validates all workflow files for required structure\n\nerror_count=0\nwarning_count=0\nworkflows_checked=0\n\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \" GSD ► VALIDATING WORKFLOWS\"\necho \"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\"\necho \"\"\n\nfor file in .agent/workflows/*.md; do\n ((workflows_checked++))\n filename=$(basename \"$file\")\n has_errors=false\n \n # Check for frontmatter\n if ! head -1 \"$file\" | grep -q \"^---\"; then\n echo \"❌ $filename: Missing frontmatter\"\n ((error_count++))\n has_errors=true\n fi\n \n # Check for description\n if ! grep -q \"description:\" \"$file\"; then\n echo \"❌ $filename: Missing description in frontmatter\"\n ((error_count++))\n has_errors=true\n fi\n \n # Check for process tags (optional but recommended)\n if ! grep -q \"\" \"$file\"; then\n echo \"⚠️ $filename: Missing tag\"\n ((warning_count++))\n fi\n \n if [ \"$has_errors\" = false ]; then\n echo \"✅ $filename\"\n fi\ndone\n\necho \"\"\necho \"───────────────────────────────────────────────────────\"\necho \"\"\necho \"Workflows checked: $workflows_checked\"\necho \"Errors: $error_count\"\necho \"Warnings: $warning_count\"\necho \"\"\n\nif [ $error_count -eq 0 ]; then\n echo \"✅ All workflows valid!\"\n exit 0\nelse\n echo \"❌ Validation failed\"\n exit 1\nfi\n" } ]