Repository: toonight/get-shit-done-for-antigravity Branch: main Commit: 3cb5243bc595 Files: 93 Total size: 292.8 KB Directory structure: gitextract_zvdi0jnd/ ├── .agent/ │ └── workflows/ │ ├── add-phase.md │ ├── add-todo.md │ ├── audit-milestone.md │ ├── check-todos.md │ ├── complete-milestone.md │ ├── debug.md │ ├── discuss-phase.md │ ├── execute.md │ ├── help.md │ ├── insert-phase.md │ ├── install.md │ ├── list-phase-assumptions.md │ ├── map.md │ ├── new-milestone.md │ ├── new-project.md │ ├── pause.md │ ├── plan-milestone-gaps.md │ ├── plan.md │ ├── progress.md │ ├── remove-phase.md │ ├── research-phase.md │ ├── resume.md │ ├── sprint.md │ ├── update.md │ ├── verify.md │ ├── web-search.md │ └── whats-new.md ├── .agents/ │ └── skills/ │ ├── codebase-mapper/ │ │ └── SKILL.md │ ├── context-compressor/ │ │ └── SKILL.md │ ├── context-fetch/ │ │ └── SKILL.md │ ├── context-health-monitor/ │ │ └── SKILL.md │ ├── debugger/ │ │ └── SKILL.md │ ├── empirical-validation/ │ │ └── SKILL.md │ ├── executor/ │ │ └── SKILL.md │ ├── plan-checker/ │ │ └── SKILL.md │ ├── planner/ │ │ └── SKILL.md │ ├── token-budget/ │ │ └── SKILL.md │ └── verifier/ │ └── SKILL.md ├── .gemini/ │ └── GEMINI.md ├── .gitignore ├── .gsd/ │ ├── examples/ │ │ ├── cross-platform.md │ │ ├── multi-wave-workflow.md │ │ ├── quick-reference.md │ │ └── workflow-example.md │ └── templates/ │ ├── DEBUG.md │ ├── PLAN.md │ ├── RESEARCH.md │ ├── SUMMARY.md │ ├── UAT.md │ ├── VERIFICATION.md │ ├── architecture.md │ ├── context.md │ ├── decisions.md │ ├── discovery.md │ ├── journal.md │ ├── milestone.md │ ├── phase-summary.md │ ├── project.md │ ├── requirements.md │ ├── roadmap.md │ ├── spec.md │ ├── sprint.md │ ├── stack.md │ ├── state.md │ ├── state_snapshot.md │ ├── todo.md │ ├── token_report.md │ └── user-setup.md ├── CHANGELOG.md ├── GSD-STYLE.md ├── LICENSE ├── PROJECT_RULES.md ├── README.md ├── VERSION ├── adapters/ │ ├── CLAUDE.md │ ├── GEMINI.md │ └── GPT_OSS.md ├── docs/ │ ├── model-selection-playbook.md │ ├── runbook.md │ └── token-optimization-guide.md ├── model_capabilities.yaml └── scripts/ ├── search_repo.ps1 ├── search_repo.sh ├── setup_search.ps1 ├── setup_search.sh ├── validate-all.ps1 ├── validate-all.sh ├── validate-skills.ps1 ├── validate-skills.sh ├── validate-templates.ps1 ├── validate-templates.sh ├── validate-workflows.ps1 └── validate-workflows.sh ================================================ FILE CONTENTS ================================================ ================================================ FILE: .agent/workflows/add-phase.md ================================================ --- description: Add a new phase to the end of the roadmap argument-hint: "" --- # /add-phase Workflow Add a new phase to the end of the current roadmap. ## 1. Validate Roadmap Exists ```powershell if (-not (Test-Path ".gsd/ROADMAP.md")) { Write-Error "ROADMAP.md required. Run /new-milestone first." } ``` --- ## 2. Determine Next Phase Number ```powershell # Count existing phases $phases = Select-String -Path ".gsd/ROADMAP.md" -Pattern "### Phase \d+" $nextPhase = $phases.Count + 1 ``` --- ## 3. Gather Phase Information Ask for: - **Name** — Phase title - **Objective** — What this phase achieves - **Depends on** — Previous phases (usually N-1) --- ## 4. Add to ROADMAP.md Append: ```markdown --- ### Phase {N}: {name} **Status**: ⬜ Not Started **Objective**: {objective} **Depends on**: Phase {N-1} **Tasks**: - [ ] TBD (run /plan {N} to create) **Verification**: - TBD ``` --- ## 5. Update STATE.md Note phase added. --- ## 6. Commit ```powershell git add .gsd/ROADMAP.md .gsd/STATE.md git commit -m "docs: add phase {N} - {name}" ``` --- ## 7. Offer Next Steps ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE ADDED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Phase {N}: {name} ─────────────────────────────────────────────────────── ▶ NEXT /plan {N} — Create execution plans for this phase ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/add-todo.md ================================================ --- description: Capture a todo item for later argument-hint: " [--priority high|medium|low]" --- # /add-todo Workflow Quickly capture an idea, task, or issue without interrupting current work flow. **Item:** $ARGUMENTS (the todo description) **Flags:** - `--priority high|medium|low` — Set priority (default: medium) **Output:** - `.gsd/TODO.md` — Accumulated todo items ## 1. Parse Arguments Extract: - Todo description - Priority (default: medium) --- ## 2. Ensure TODO.md Exists ```powershell if (-not (Test-Path ".gsd/TODO.md")) { # Create with header } ``` --- ## 3. Add Todo Item Append to `.gsd/TODO.md`: ```markdown - [ ] {description} `{priority}` — {date} ``` --- ## 4. Confirm ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► TODO ADDED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {description} Priority: {priority} ─────────────────────────────────────────────────────── /check-todos — see all pending items ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/audit-milestone.md ================================================ --- description: Audit a milestone for quality and completeness argument-hint: "[milestone-name]" --- # /audit-milestone Workflow Review a completed (or in-progress) milestone for quality, completeness, and lessons learned. ## 1. Load Milestone Context If milestone name provided, load from archive: ```powershell Get-Content ".gsd/milestones/{name}-SUMMARY.md" ``` If no name, audit current milestone from ROADMAP.md. --- ## 2. Check Must-Haves Verification For each must-have in the milestone: - Was it verified with empirical evidence? - Is the evidence still valid? - Any regressions since completion? --- ## 3. Review Technical Debt Check TODO.md and DECISIONS.md for: - Deferred items during this milestone - Technical debt acknowledged - Items that should be addressed --- ## 4. Analyze Phase Quality For each phase: - Review VERIFICATION.md - Check for gap closures (were there many?) - Note recurring issues --- ## 5. Generate Audit Report ```markdown # Milestone Audit: {name} **Audited:** {date} ## Summary | Metric | Value | |--------|-------| | Phases | {N} | | Gap closures | {M} | | Technical debt items | {K} | ## Must-Haves Status | Requirement | Verified | Evidence | |-------------|----------|----------| | {req 1} | ✅ | {link} | | {req 2} | ✅ | {link} | ## Concerns - {concern 1} - {concern 2} ## Recommendations 1. {recommendation 1} 2. {recommendation 2} ## Technical Debt to Address - [ ] {item 1} - [ ] {item 2} ``` --- ## 6. Offer Actions ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► AUDIT COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Milestone: {name} Health: {GOOD | CONCERNS | NEEDS ATTENTION} ─────────────────────────────────────────────────────── ▶ ACTIONS /plan-milestone-gaps — Create plans to address gaps /add-todo — Capture debt items for later ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/check-todos.md ================================================ --- description: List all pending todo items argument-hint: "[--all] [--priority high|medium|low]" --- # /check-todos Workflow Display pending todo items, optionally filtered by priority or status. **Flags:** - `--all` — Show completed items too - `--priority high|medium|low` — Filter by priority **Input:** - `.gsd/TODO.md` — Todo items ## 1. Load TODO.md ```powershell if (-not (Test-Path ".gsd/TODO.md")) { Write-Output "No todos found. Use /add-todo to create one." exit } Get-Content ".gsd/TODO.md" ``` --- ## 2. Parse and Filter Count items by status: - `- [ ]` = pending - `- [x]` = complete Filter by priority if flag provided. --- ## 3. Display ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► TODOS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PENDING ({N} items) ─────────────────── 🔴 {high priority item} 🟡 {medium priority item} 🟢 {low priority item} {If --all flag:} COMPLETED ({M} items) ───────────────────── ✅ {completed item} ─────────────────────────────────────────────────────── /add-todo — add new item ─────────────────────────────────────────────────────── ``` | Priority | Indicator | |----------|-----------| | high | 🔴 | | medium | 🟡 | | low | 🟢 | | done | ✅ | ================================================ FILE: .agent/workflows/complete-milestone.md ================================================ --- description: Mark current milestone as complete and archive --- # /complete-milestone Workflow Finalize the current milestone, archive documentation, and prepare for next milestone. ## 1. Verify All Phases Complete **PowerShell:** ```powershell # Check ROADMAP.md for incomplete phases Select-String -Path ".gsd/ROADMAP.md" -Pattern "Status.*Not Started|Status.*In Progress" ``` **Bash:** ```bash # Check ROADMAP.md for incomplete phases grep -E "Status.*Not Started|Status.*In Progress" ".gsd/ROADMAP.md" ``` **If incomplete phases found:** ``` ⚠️ Cannot complete milestone — {N} phases incomplete Run /progress to see status. ``` --- ## 2. Run Final Verification Verify all must-haves from ROADMAP.md: - Run verification commands - Capture evidence - Create VERIFICATION.md if not exists --- ## 3. Generate Milestone Summary Create `.gsd/milestones/{name}-SUMMARY.md`: ```markdown # Milestone: {name} ## Completed: {date} ## Deliverables - ✅ {must-have 1} - ✅ {must-have 2} ## Phases Completed 1. Phase 1: {name} — {date} 2. Phase 2: {name} — {date} ... ## Metrics - Total commits: {N} - Files changed: {M} - Duration: {days} ## Lessons Learned {Auto-extract from DECISIONS.md and JOURNAL.md} ``` --- ## 4. Archive Current State **PowerShell:** ```powershell # Create milestone archive New-Item -ItemType Directory -Force ".gsd/milestones/{name}" # Move phase-specific files Move-Item ".gsd/phases/*" ".gsd/milestones/{name}/" # Archive decisions and journal (prevent monolithic growth across milestones) if (Test-Path ".gsd/DECISIONS.md") { Copy-Item ".gsd/DECISIONS.md" ".gsd/milestones/{name}/DECISIONS.md" } if (Test-Path ".gsd/JOURNAL.md") { Copy-Item ".gsd/JOURNAL.md" ".gsd/milestones/{name}/JOURNAL.md" } ``` **Bash:** ```bash # Create milestone archive mkdir -p ".gsd/milestones/{name}" # Move phase-specific files mv .gsd/phases/* ".gsd/milestones/{name}/" # Archive decisions and journal (prevent monolithic growth across milestones) [ -f ".gsd/DECISIONS.md" ] && cp ".gsd/DECISIONS.md" ".gsd/milestones/{name}/DECISIONS.md" [ -f ".gsd/JOURNAL.md" ] && cp ".gsd/JOURNAL.md" ".gsd/milestones/{name}/JOURNAL.md" ``` --- ## 5. Reset for Next Milestone Clear ROADMAP.md phases section (keep header). Update STATE.md to show milestone complete. **Reset DECISIONS.md** — replace contents with a fresh header referencing the archive: ```markdown # Decisions > Previous milestone decisions archived in `.gsd/milestones/{name}/DECISIONS.md` --- ``` **Reset JOURNAL.md** — replace contents with a fresh header: ```markdown # Journal > Previous milestone journal archived in `.gsd/milestones/{name}/JOURNAL.md` --- ``` --- ## 5c. Refresh Architecture Update `.gsd/ARCHITECTURE.md` to reflect the current state of the codebase after the milestone: 1. **Scan the project** — identify new components, removed modules, changed dependencies 2. **Update the architecture diagram** — reflect structural changes from this milestone 3. **Update STACK.md** — refresh technology and dependency information 4. **Keep it lean** — remove details about components that no longer exist; summarize, don't accumulate > This prevents ARCHITECTURE.md from becoming stale or bloated across milestones (addresses the issue where architecture only updates via `/map`). --- ## 5d. Update Requirements If `.gsd/REQUIREMENTS.md` exists, mark completed requirements: 1. Read each requirement's status 2. Cross-reference with milestone deliverables and verification results 3. Mark satisfied requirements as `Complete` 4. Mark deferred items as `Deferred` with reason 5. Archive the requirements snapshot into `.gsd/milestones/{name}/REQUIREMENTS.md` --- ## 6. Commit and Tag ```bash git add -A git commit -m "docs: complete milestone {name}" git tag -a "{name}" -m "Milestone {name} complete" ``` --- ## 7. Celebrate ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► MILESTONE COMPLETE 🎉 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {name} Phases: {N} completed Tag: {name} ─────────────────────────────────────────────────────── ▶ NEXT /new-milestone — Start next milestone /audit-milestone {name} — Review this milestone ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/debug.md ================================================ --- description: Systematic debugging with persistent state argument-hint: "[description of issue]" --- # /debug Workflow You are a GSD debugger orchestrator. You diagnose and fix issues systematically, leveraging fresh context to see what polluted contexts miss. Systematically diagnose an issue using hypothesis-driven debugging, with persistent state to prevent circular attempts. **Issue:** $ARGUMENTS (description of the problem to debug) **Skill reference:** `.agents/skills/debugger/SKILL.md` ## 1. Initialize Debug Session Check for existing debug state: **PowerShell:** ```powershell Test-Path ".gsd/DEBUG.md" ``` **Bash:** ```bash test -f ".gsd/DEBUG.md" ``` If exists, load previous attempts. If not, create new session. Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DEBUG SESSION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Issue: {description} ``` --- ## 2. Document Symptom Create/update `.gsd/DEBUG.md`: ```markdown # Debug Session: {Issue ID} ## Symptom {Exact description of the problem} **When:** {When does it occur?} **Expected:** {What should happen?} **Actual:** {What actually happens?} ``` --- ## 3. Gather Evidence Collect data BEFORE forming hypotheses: **PowerShell:** ```powershell # Get error details {relevant commands to capture error info} # Check logs Get-Content logs/error.log -Tail 50 # Check environment {relevant environment checks} ``` **Bash:** ```bash # Get error details {relevant commands to capture error info} # Check logs tail -50 logs/error.log # Check environment {relevant environment checks} ``` Document evidence in DEBUG.md. --- ## 4. Form Hypotheses Based on evidence, list possible causes: ```markdown ## Hypotheses | # | Hypothesis | Likelihood | Status | |---|------------|------------|--------| | 1 | {cause 1} | 80% | UNTESTED | | 2 | {cause 2} | 15% | UNTESTED | | 3 | {cause 3} | 5% | UNTESTED | ``` --- ## 5. Test Hypotheses Test highest likelihood first: ```markdown ## Attempts ### Attempt 1 **Testing:** H1 — {hypothesis} **Action:** {what you did to test} **Result:** {outcome} **Conclusion:** {CONFIRMED | ELIMINATED | INCONCLUSIVE} ``` --- ## 6. Apply Fix (If Root Cause Found) When root cause confirmed: 1. Implement fix 2. Run original failing scenario 3. Verify PASSES 4. Check for regressions Update DEBUG.md: ```markdown ## Resolution **Root Cause:** {what was actually wrong} **Fix:** {what was changed} **Verified:** {how fix was verified} **Regression Check:** {what else was tested} ``` --- ## 7. Handle 3-Strike Rule If 3 attempts fail on SAME approach: ``` ⚠️ 3 FAILURES ON SAME APPROACH Action: STOP and reassess Options: 1. Try fundamentally DIFFERENT approach 2. /pause for fresh session context 3. Ask user for additional information ``` Update DEBUG.md and recommend next steps. --- ## 8. Commit Resolution If fixed: ```bash git add -A git commit -m "fix: {brief description of fix}" ``` Update STATE.md with resolution. **If Resolved:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► BUG FIXED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Root cause: {what was wrong} Fix: {what was done} Committed: {hash} ─────────────────────────────────────────────────────── ``` **If Stuck After 3 Attempts:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DEBUG PAUSED ⏸ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3 attempts exhausted on current approach. State saved to .gsd/DEBUG.md ─────────────────────────────────────────────────────── Options: • /debug {issue} — try different approach • /pause — save state for fresh session • Provide more context about the issue ─────────────────────────────────────────────────────── ``` ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/pause` | Use after 3 failed attempts | | `/resume` | Start fresh with documented state | | `/verify` | Re-verify after fixing issues | ### Skills | Skill | Purpose | |-------|---------| | `debugger` | Detailed debugging methodology | | `context-health-monitor` | 3-strike rule | ================================================ FILE: .agent/workflows/discuss-phase.md ================================================ --- description: Discuss a phase before planning (clarify scope and approach) argument-hint: "" --- # /discuss-phase Workflow Interactive discussion about a phase to clarify scope, approach, and concerns before creating plans. Run BEFORE `/plan` when: - Phase scope is unclear - Multiple implementation approaches exist - Trade-offs need user input - Dependencies are complex ## 1. Load Phase Context Read from ROADMAP.md: - Phase objective - Dependencies - Current status --- ## 2. Analyze Requirements From phase objective, extract: - What needs to be built - What constraints exist - What decisions need to be made --- ## 3. Present Discussion Points ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► DISCUSS PHASE {N} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Phase: {name} Objective: {objective} ─────────────────────────────────────────────────────── TOPICS TO DISCUSS 1. SCOPE CLARIFICATION - {question about scope} - {question about boundaries} 2. IMPLEMENTATION APPROACH Option A: {approach} Option B: {approach} Which do you prefer and why? 3. DEPENDENCIES - Requires: {what from previous phases} - Missing: {any gaps in earlier work} 4. CONCERNS - {potential issue} - {risk to flag} ─────────────────────────────────────────────────────── ``` --- ## 4. Gather User Input Listen for: - Scope decisions - Approach preferences - Constraints not in spec - Priority clarifications --- ## 5. Document Decisions Update `.gsd/DECISIONS.md`: ```markdown ## Phase {N} Decisions **Date:** {date} ### Scope - {decision about scope} ### Approach - Chose: {approach} - Reason: {rationale} ### Constraints - {constraint identified} ``` --- ## 6. Offer Next Steps ``` ─────────────────────────────────────────────────────── ✓ Discussion documented in DECISIONS.md ▶ NEXT /plan {N} — Create execution plans with this context /research-phase {N} — Deep dive on technical options ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/execute.md ================================================ --- description: The Engineer — Execute a specific phase with focused context argument-hint: " [--gaps-only]" --- # /execute Workflow You are a GSD executor orchestrator. You manage wave-based parallel execution of phase plans. **Core responsibilities:** - Validate phase exists and has plans - Discover and group plans by execution wave - Spawn focused execution for each plan - Verify phase goal after all plans complete - Update roadmap and state on completion Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean: discover plans, analyze dependencies, group into waves, execute sequentially within waves, verify against phase goal. **Context budget:** ~15% orchestrator, fresh context per plan execution. **Phase:** $ARGUMENTS (required - phase number to execute) **Flags:** - `--gaps-only` — Execute only gap closure plans (created by `/verify` when issues found) **Required files:** - `.gsd/ROADMAP.md` — Phase definitions - `.gsd/STATE.md` — Current position - `.gsd/phases/{phase}/` — Phase directory with PLAN.md files ## 1. Validate Environment **PowerShell:** ```powershell Test-Path ".gsd/ROADMAP.md" Test-Path ".gsd/STATE.md" ``` **Bash:** ```bash test -f ".gsd/ROADMAP.md" test -f ".gsd/STATE.md" ``` **If not found:** Error — user should run `/plan` first. --- ## 2. Validate Phase Exists **PowerShell:** ```powershell # Check phase exists in roadmap Select-String -Path ".gsd/ROADMAP.md" -Pattern "Phase $PHASE:" ``` **Bash:** ```bash # Check phase exists in roadmap grep "Phase $PHASE:" ".gsd/ROADMAP.md" ``` **If not found:** Error with available phases from ROADMAP.md. --- ## 3. Ensure Phase Directory Exists **PowerShell:** ```powershell $PHASE_DIR = ".gsd/phases/$PHASE" if (-not (Test-Path $PHASE_DIR)) { New-Item -ItemType Directory -Path $PHASE_DIR } ``` **Bash:** ```bash PHASE_DIR=".gsd/phases/$PHASE" mkdir -p "$PHASE_DIR" ``` --- ## 4. Discover Plans **PowerShell:** ```powershell Get-ChildItem "$PHASE_DIR/*-PLAN.md" ``` **Bash:** ```bash ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null ``` **Check for existing summaries** (completed plans): **PowerShell:** ```powershell Get-ChildItem "$PHASE_DIR/*-SUMMARY.md" ``` **Bash:** ```bash ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null ``` **Build list of incomplete plans** (PLAN without matching SUMMARY). **If `--gaps-only`:** Filter to only plans with `gap_closure: true` in frontmatter. **If no incomplete plans found:** Phase already complete, skip to step 8. --- ## 5. Group Plans by Wave Read `wave` field from each plan's frontmatter: ```yaml --- phase: 1 plan: 2 wave: 1 --- ``` **Group plans by wave number.** Lower waves execute first. Display wave structure: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► EXECUTING PHASE {N} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Wave 1: {plan-1}, {plan-2} Wave 2: {plan-3} {X} plans across {Y} waves ``` --- ## 6. Execute Waves For each wave in order: ### 6a. Execute Plans in Wave For each plan in the current wave: 1. **Load plan context** — Read only the PLAN.md file 2. **Execute tasks** — Follow `` blocks in order 3. **Verify each task** — Run `` commands 4. **Commit per task:** ```bash git add -A git commit -m "feat(phase-{N}): {task-name}" ``` 5. **Create SUMMARY.md** — Document what was done ### 6b. Verify Wave Complete Check all plans in wave have SUMMARY.md files. ### 6c. Proceed to Next Wave Only after current wave fully completes. --- ## 7. Verify Phase Goal After all waves complete: 1. **Read phase goal** from ROADMAP.md 2. **Check must-haves** against actual codebase (not SUMMARY claims) 3. **Run verification commands** specified in phase **Create VERIFICATION.md:** ```markdown ## Phase {N} Verification ### Must-Haves - [x] Must-have 1 — VERIFIED (evidence: ...) - [ ] Must-have 2 — FAILED (reason: ...) ### Verdict: PASS / FAIL ``` **Route by verdict:** - `PASS` → Continue to step 8 - `FAIL` → Create gap closure plans, offer `/execute {N} --gaps-only` --- ## 8. Update Roadmap and State **Update ROADMAP.md:** ```markdown ### Phase {N}: {Name} **Status**: ✅ Complete ``` **Update STATE.md:** ```markdown ## Current Position - **Phase**: {N} (completed) - **Task**: All tasks complete - **Status**: Verified ## Last Session Summary Phase {N} executed successfully. {X} plans, {Y} tasks completed. ## Next Steps 1. Proceed to Phase {N+1} ``` **Update REQUIREMENTS.md** (if exists): - Cross-reference completed tasks with requirement IDs - Mark requirements satisfied by this phase as `In Progress` or `Complete` - Update the traceability matrix with plan references --- ## 9. Commit Phase Completion ```bash git add .gsd/ROADMAP.md .gsd/STATE.md .gsd/REQUIREMENTS.md git commit -m "docs(phase-{N}): complete {phase-name}" ``` --- ## 10. Offer Next Steps Output based on status: **Route A: Phase complete, more phases remain** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {N} COMPLETE ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {X} plans executed Goal verified ✓ ─────────────────────────────────────────────────────── ▶ Next Up Phase {N+1}: {Name} /plan {N+1} — create execution plans /execute {N+1} — execute directly (if plans exist) ─────────────────────────────────────────────────────── ``` **Route B: All phases complete** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► MILESTONE COMPLETE 🎉 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ All phases completed and verified. ─────────────────────────────────────────────────────── ``` **Route C: Gaps found** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {N} GAPS FOUND ⚠ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {X}/{Y} must-haves verified Gap closure plans created. /execute {N} --gaps-only — execute fix plans ─────────────────────────────────────────────────────── ``` **After 3 failed debugging attempts:** 1. Stop current approach 2. Document to `.gsd/STATE.md` what was tried 3. Recommend `/pause` for fresh session ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/plan` | Creates PLAN.md files that /execute runs | | `/verify` | Validates work after /execute completes | | `/debug` | Use when tasks fail verification | | `/pause` | Use after 3 debugging failures | ### Skills | Skill | Purpose | |-------|---------| | `executor` | Detailed execution protocol | | `context-health-monitor` | 3-strike rule enforcement | | `empirical-validation` | Verification requirements | ================================================ FILE: .agent/workflows/help.md ================================================ --- description: Show all available GSD commands --- # /help Workflow Display all available GSD commands with descriptions and usage hints. **First, read and display the version:** **PowerShell:** ```powershell $version = Get-Content "VERSION" -ErrorAction SilentlyContinue if (-not $version) { $version = "unknown" } ``` **Bash:** ```bash version=$(cat VERSION 2>/dev/null || echo "unknown") ``` **Then display help with version in header:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► HELP (v{version}) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CORE WORKFLOW ───────────── /map Analyze codebase → ARCHITECTURE.md /plan [N] Create PLAN.md files for phase N /execute [N] Wave-based execution with atomic commits /verify [N] Must-haves validation with proof /debug [desc] Systematic debugging (3-strike rule) PROJECT SETUP ───────────── /new-project Deep questioning → SPEC.md /new-milestone Create milestone with phases /complete-milestone Archive completed milestone /audit-milestone Review milestone quality PHASE MANAGEMENT ──────────────── /add-phase Add phase to end of roadmap /insert-phase Insert phase (renumbers subsequent) /remove-phase Remove phase (with safety checks) /discuss-phase Clarify scope before planning /research-phase Deep technical research /list-phase-assumptions Surface planning assumptions /plan-milestone-gaps Create gap closure plans NAVIGATION & STATE ────────────────── /progress Show current position in roadmap /pause Save state for session handoff /resume Restore from last session /add-todo Quick capture idea /check-todos List pending items UTILITIES ───────── /help Show this help ─────────────────────────────────────────────────────── QUICK START ─────────── 1. /new-project → Initialize with deep questioning 2. /plan 1 → Create Phase 1 plans 3. /execute 1 → Implement Phase 1 4. /verify 1 → Confirm it works 5. Repeat ─────────────────────────────────────────────────────── CORE RULES ────────── 🔒 Planning Lock No code until SPEC.md is FINALIZED 💾 State Persistence Update STATE.md after every task 🧹 Context Hygiene 3 failures → state dump → fresh session ✅ Empirical Valid. Proof required, no "it should work" ─────────────────────────────────────────────────────── 📚 Docs: GSD-STYLE.md, .gsd/examples/ ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/insert-phase.md ================================================ --- description: Insert a phase between existing phases (renumbers subsequent) argument-hint: " " --- # /insert-phase Workflow Insert a new phase at a specific position, renumbering all subsequent phases. ## 1. Parse Arguments Extract: - **Position** — Where to insert (e.g., 2 inserts before current Phase 2) - **Name** — Phase title --- ## 2. Validate Position **PowerShell:** ```powershell $totalPhases = (Select-String -Path ".gsd/ROADMAP.md" -Pattern "### Phase \d+").Count if ($position -lt 1 -or $position -gt $totalPhases + 1) { Write-Error "Invalid position. Valid: 1-$($totalPhases + 1)" } ``` **Bash:** ```bash total_phases=$(grep -c "### Phase [0-9]" ".gsd/ROADMAP.md") if [ "$position" -lt 1 ] || [ "$position" -gt $((total_phases + 1)) ]; then echo "Error: Invalid position. Valid: 1-$((total_phases + 1))" >&2 fi ``` --- ## 3. Gather Phase Information Ask for: - **Objective** — What this phase achieves - **Dependencies** — What it needs from earlier phases --- ## 4. Renumber Existing Phases For phases >= position, increment phase number by 1. **Also update:** - Phase directory names (`.gsd/phases/{N}/`) - References in PLAN.md files - Dependencies in ROADMAP.md --- ## 5. Insert New Phase Add at position with correct numbering. --- ## 6. Update STATE.md If currently in a phase >= position, update position reference. --- ## 7. Commit ```bash git add -A git commit -m "docs: insert phase {N} - {name} (renumbered {M} phases)" ``` --- ## 8. Display Result ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE INSERTED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Inserted: Phase {N}: {name} Renumbered: Phases {N+1} through {M} ─────────────────────────────────────────────────────── ▶ NEXT /plan {N} — Create plans for new phase /progress — See updated roadmap ─────────────────────────────────────────────────────── ``` Phase insertion can be disruptive. Consider: - In-progress phases may have commits referencing old numbers - Existing plans reference phase numbers - Use sparingly and early in milestone lifecycle ================================================ FILE: .agent/workflows/install.md ================================================ --- description: Install GSD into the current project from GitHub --- # /install Workflow Install GSD for Antigravity into the current project from GitHub. ## 1. Check for Existing Installation Look for GSD marker directories: **PowerShell:** ```powershell $alreadyInstalled = (Test-Path ".agents") -or (Test-Path ".agent") -or (Test-Path ".gsd") if ($alreadyInstalled) { Write-Output "GSD files detected in this project." } ``` **Bash:** ```bash if [ -d ".agents" ] || [ -d ".agent" ] || [ -d ".gsd" ]; then echo "GSD files detected in this project." fi ``` **If already installed:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► ALREADY INSTALLED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD files already exist in this project. ─────────────────────────────────────────────────────── A) Reinstall — Overwrite with latest version B) Cancel — Keep current installation If you want to update instead: /update ─────────────────────────────────────────────────────── ``` If user chooses Cancel, exit. If user chooses Reinstall, continue to Step 2. --- ## 2. Clone from GitHub ```bash git clone --depth 1 https://github.com/toonight/get-shit-done-for-antigravity.git .gsd-install-temp ``` --- ## 3. Copy Files **PowerShell:** ```powershell # Core directories Copy-Item -Recurse ".gsd-install-temp\.agent" ".\" Copy-Item -Recurse ".gsd-install-temp\.agents" ".\" Copy-Item -Recurse ".gsd-install-temp\.gemini" ".\" Copy-Item -Recurse ".gsd-install-temp\.gsd" ".\" Copy-Item -Recurse ".gsd-install-temp\adapters" ".\" Copy-Item -Recurse ".gsd-install-temp\docs" ".\" Copy-Item -Recurse ".gsd-install-temp\scripts" ".\" # Root files Copy-Item -Force ".gsd-install-temp\PROJECT_RULES.md" ".\" Copy-Item -Force ".gsd-install-temp\GSD-STYLE.md" ".\" Copy-Item -Force ".gsd-install-temp\model_capabilities.yaml" ".\" ``` **Bash:** ```bash # Core directories cp -r .gsd-install-temp/.agent ./ cp -r .gsd-install-temp/.agents ./ cp -r .gsd-install-temp/.gemini ./ cp -r .gsd-install-temp/.gsd ./ cp -r .gsd-install-temp/adapters ./ cp -r .gsd-install-temp/docs ./ cp -r .gsd-install-temp/scripts ./ # Root files cp .gsd-install-temp/PROJECT_RULES.md ./ cp .gsd-install-temp/GSD-STYLE.md ./ cp .gsd-install-temp/model_capabilities.yaml ./ ``` --- ## 4. Cleanup **PowerShell:** ```powershell Remove-Item -Recurse -Force ".gsd-install-temp" ``` **Bash:** ```bash rm -rf .gsd-install-temp ``` --- ## 5. Add to .gitignore (Optional) Check if `.gsd/STATE.md` and other session files should be gitignored: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► ADD TO .gitignore? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Recommended .gitignore additions for session-specific files: .gsd/STATE.md .gsd/JOURNAL.md .gsd/TODO.md ─────────────────────────────────────────────────────── A) Yes — Add recommended entries B) No — Skip ─────────────────────────────────────────────────────── ``` --- ## 6. Confirm Installation ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► INSTALLED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD for Antigravity has been installed. Files installed: • .agent/ (workflows) • .agents/ (skills — Agent Skills standard) • .gemini/ (Gemini integration) • .gsd/ (project state templates) • adapters/ (model-specific enhancements) • docs/ (operational documentation) • scripts/ (utility scripts) • PROJECT_RULES.md • GSD-STYLE.md • model_capabilities.yaml ─────────────────────────────────────────────────────── Next step: /new-project — Initialize your project with GSD ─────────────────────────────────────────────────────── ``` - This workflow is designed to work from a clean project (no prior GSD installation) - It copies ALL necessary files, unlike manual installation which may miss some - For updates to an existing installation, use /update instead - The /new-project command should be run after installation to set up SPEC.md ================================================ FILE: .agent/workflows/list-phase-assumptions.md ================================================ --- description: List assumptions made during phase planning argument-hint: "" --- # /list-phase-assumptions Workflow Surface and document assumptions made during phase planning that should be validated. ## 1. Load Phase Plans ```powershell Get-ChildItem ".gsd/phases/{N}/*-PLAN.md" ``` --- ## 2. Extract Assumptions Scan plans for: - Technology choices without justification - Implied dependencies - Expected behaviors not verified - Time estimates - Scope boundaries --- ## 3. Categorize Assumptions | Category | Risk Level | |----------|------------| | Technical | API exists, library works, syntax correct | | Integration | Services compatible, auth works | | Scope | Feature boundaries, what's excluded | | Performance | Will handle load, fast enough | | Timeline | Estimates accurate | --- ## 4. Display Assumptions ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {N} ASSUMPTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TECHNICAL 🟡 {assumption 1} — Validate before execution 🟢 {assumption 2} — Low risk INTEGRATION 🔴 {assumption 3} — High risk, verify first SCOPE 🟡 {assumption 4} — Confirm with user ─────────────────────────────────────────────────────── ▶ ACTIONS • Validate high-risk assumptions before /execute • Add verified assumptions to RESEARCH.md • Flag for user review if scope-related ─────────────────────────────────────────────────────── ``` --- ## 5. Offer Validation Ask if user wants to: - Validate specific assumptions now - Add to TODO.md for later - Accept and proceed ================================================ FILE: .agent/workflows/map.md ================================================ --- description: The Architect — Analyze codebase and update ARCHITECTURE.md and STACK.md --- # /map Workflow You are a GSD codebase mapper. You analyze existing codebases to understand structure, patterns, and technical debt. **Core responsibilities:** - Scan project structure and identify components - Analyze dependencies and versions - Map data flow and integration points - Identify technical debt and patterns - Document findings for planning context Analyze the existing codebase and produce documentation that enables informed planning. This workflow should be run BEFORE `/plan` on brownfield projects to give the planner full context. **No arguments required.** Operates on current project directory. **Outputs:** - `.gsd/ARCHITECTURE.md` — System design documentation - `.gsd/STACK.md` — Technology inventory ## 1. Validate Project Check this is a valid project: **PowerShell:** ```powershell # Look for common project indicators $indicators = @( "package.json", "requirements.txt", "Cargo.toml", "go.mod", "pom.xml", "*.csproj", "Gemfile" ) ``` **Bash:** ```bash # Look for common project indicators indicators=("package.json" "requirements.txt" "Cargo.toml" "go.mod" "pom.xml" "*.csproj" "Gemfile") ``` Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► MAPPING CODEBASE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ## 2. Analyze Project Structure ### 2a. Directory Analysis **PowerShell:** ```powershell Get-ChildItem -Recurse -Directory | Where-Object { $_.Name -notmatch "node_modules|\.git|__pycache__|dist|build" } ``` **Bash:** ```bash find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' \ -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' ``` Identify: - Source directories (`src/`, `lib/`, `app/`) - Test directories (`tests/`, `__tests__/`, `spec/`) - Configuration locations - Asset directories ### 2b. Entry Points Find main files: **PowerShell:** ```powershell # Example for Node.js Get-Content "package.json" | ConvertFrom-Json | Select-Object -ExpandProperty main ``` **Bash:** ```bash # Example for Node.js (requires jq) cat package.json | jq -r '.main' ``` ### 2c. Component Detection Scan for common patterns: - React components (`*.tsx`, `*.jsx`) - API routes (`routes/`, `api/`) - Database models (`models/`, `entities/`) - Services (`services/`, `lib/`) - Utilities (`utils/`, `helpers/`) --- ## 3. Analyze Dependencies ### 3a. Production Dependencies **PowerShell:** ```powershell # Node.js example Get-Content "package.json" | ConvertFrom-Json | Select-Object -ExpandProperty dependencies ``` **Bash:** ```bash # Node.js example (requires jq) cat package.json | jq '.dependencies' ``` For each dependency, note: - Name and version - Purpose (infer from name/usage) - Is it actively used? ### 3b. Development Dependencies Same for devDependencies, noting: - Build tools - Test frameworks - Linters/formatters ### 3c. Outdated Packages ```bash npm outdated # or pip list --outdated ``` --- ## 4. Map Data Flow ### 4a. External Integrations Search for: **PowerShell:** ```powershell # API calls Select-String -Path "src/**/*" -Pattern "fetch\(|axios\.|http\." # Database connections Select-String -Path "**/*" -Pattern "DATABASE_URL|mongodb|postgres|mysql" # Third-party services Select-String -Path "**/*" -Pattern "stripe|sendgrid|twilio|aws-sdk" ``` **Bash:** ```bash # API calls grep -rE 'fetch\(|axios\.|http\.' src/ # Database connections grep -rE 'DATABASE_URL|mongodb|postgres|mysql' . # Third-party services grep -rE 'stripe|sendgrid|twilio|aws-sdk' . ``` ### 4b. Internal Flow Trace how data moves: - Entry point → Business logic → Data layer → Output - Identify shared state (context, stores, singletons) --- ## 5. Identify Technical Debt ### 5a. Code Smells Search for indicators: **PowerShell:** ```powershell # TODOs and FIXMEs Select-String -Path "src/**/*" -Pattern "TODO|FIXME|HACK|XXX" # Deprecated markers Select-String -Path "**/*" -Pattern "@deprecated|DEPRECATED" ``` **Bash:** ```bash # TODOs and FIXMEs grep -rE 'TODO|FIXME|HACK|XXX' src/ # Deprecated markers grep -rE '@deprecated|DEPRECATED' . ``` ### 5b. Pattern Inconsistencies Note where patterns differ: - Naming conventions - File organization - Error handling approaches ### 5c. Missing Elements Identify gaps: - No tests for critical paths - Missing error boundaries - No input validation - No logging/monitoring --- ## 6. Write ARCHITECTURE.md ```markdown # Architecture > Auto-generated by /map on {date} ## Overview {High-level description of what this system does} ``` ┌─────────────────────────────────────────┐ │ [Entry Point] │ ├─────────────────────────────────────────┤ │ [Business Logic Layer] │ ├─────────────────────────────────────────┤ │ [Data Layer] │ └─────────────────────────────────────────┘ ``` ## Components ### {Component 1} - **Purpose:** {what it does} - **Location:** `{path}` - **Dependencies:** {what it imports} ### {Component 2} ... ## Data Flow 1. {Step 1} 2. {Step 2} 3. {Step 3} ## Integration Points | Service | Type | Purpose | |---------|------|---------| | {name} | API | {purpose} | ## Technical Debt - [ ] {Debt item 1} - [ ] {Debt item 2} ## Conventions **Naming:** {patterns observed} **Structure:** {organization patterns} **Testing:** {test patterns} ``` --- ## 7. Write STACK.md ```markdown # Technology Stack > Auto-generated by /map on {date} ## Runtime | Technology | Version | Purpose | |------------|---------|---------| | {runtime} | {version} | Core runtime | ## Dependencies ### Production | Package | Version | Purpose | |---------|---------|---------| | {pkg} | {ver} | {purpose} | ### Development | Package | Version | Purpose | |---------|---------|---------| | {pkg} | {ver} | {purpose} | ## Infrastructure | Service | Provider | Purpose | |---------|----------|---------| | {service} | {provider} | {purpose} | ## Configuration | Variable | Purpose | Location | |----------|---------|----------| | {var} | {purpose} | {file} | ## Outdated Packages | Package | Current | Latest | Risk | |---------|---------|--------|------| | {pkg} | {cur} | {new} | {risk} | ``` --- ## 8. Update State Update `.gsd/STATE.md`: ```markdown ## Last Session Summary Codebase mapping complete. - {N} components identified - {M} dependencies analyzed - {K} technical debt items found ``` --- ## 9. Commit Documentation ```bash git add .gsd/ARCHITECTURE.md .gsd/STACK.md .gsd/STATE.md git commit -m "docs: map existing codebase" ``` --- ## 10. Offer Next Steps ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► CODEBASE MAPPED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Components: {N} Dependencies: {M} production, {K} dev Technical debt: {J} items ─────────────────────────────────────────────────────── ▶ Next Up /plan — create execution plans with full context Files updated: • .gsd/ARCHITECTURE.md • .gsd/STACK.md ─────────────────────────────────────────────────────── ``` ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/plan` | Use ARCHITECTURE.md from /map for planning context | ### Skills | Skill | Purpose | |-------|---------| | `codebase-mapper` | Detailed mapping methodology | ================================================ FILE: .agent/workflows/new-milestone.md ================================================ --- description: Create a new milestone with phases argument-hint: "" --- # /new-milestone Workflow Define a new milestone with goal, phases, and success criteria. ## 1. Validate SPEC Exists **PowerShell:** ```powershell if (-not (Test-Path ".gsd/SPEC.md")) { Write-Error "SPEC.md required. Run /new-project first." } ``` **Bash:** ```bash if [ ! -f ".gsd/SPEC.md" ]; then echo "Error: SPEC.md required. Run /new-project first." >&2 fi ``` --- ## 2. Gather Milestone Information Ask for: - **Name** — Milestone identifier (e.g., "v1.0", "MVP", "Beta") - **Goal** — What does this milestone achieve? - **Must-haves** — Non-negotiable deliverables - **Nice-to-haves** — Optional if time permits --- ## 3. Generate Phase Breakdown Based on goal and must-haves, suggest phases: ```markdown ## Suggested Phases Phase 1: {Foundation/Setup} Phase 2: {Core Feature A} Phase 3: {Core Feature B} Phase 4: {Integration/Polish} Phase 5: {Verification/Launch} ``` Ask user to confirm or modify. --- ## 4. Update ROADMAP.md ```markdown # ROADMAP.md > **Current Milestone**: {name} > **Goal**: {goal} ## Must-Haves - [ ] {must-have 1} - [ ] {must-have 2} ## Phases ### Phase 1: {name} **Status**: ⬜ Not Started **Objective**: {description} ### Phase 2: {name} **Status**: ⬜ Not Started **Objective**: {description} ... ``` --- ## 5. Update STATE.md ```markdown ## Current Position - **Milestone**: {name} - **Phase**: Not started - **Status**: Milestone planned ``` --- ## 5b. Reset Session Files (if starting fresh) If DECISIONS.md or JOURNAL.md contain entries from a previous milestone, reset them to prevent monolithic growth: **PowerShell:** ```powershell # Only reset if files are non-empty and no archive exists yet if ((Test-Path ".gsd/DECISIONS.md") -and (Get-Content ".gsd/DECISIONS.md" | Measure-Object -Line).Lines -gt 5) { Set-Content ".gsd/DECISIONS.md" "# Decisions`n`n---`n" } if ((Test-Path ".gsd/JOURNAL.md") -and (Get-Content ".gsd/JOURNAL.md" | Measure-Object -Line).Lines -gt 5) { Set-Content ".gsd/JOURNAL.md" "# Journal`n`n---`n" } ``` **Bash:** ```bash if [ -f ".gsd/DECISIONS.md" ] && [ "$(wc -l < .gsd/DECISIONS.md)" -gt 5 ]; then printf '# Decisions\n\n---\n' > .gsd/DECISIONS.md fi if [ -f ".gsd/JOURNAL.md" ] && [ "$(wc -l < .gsd/JOURNAL.md)" -gt 5 ]; then printf '# Journal\n\n---\n' > .gsd/JOURNAL.md fi ``` > **Note:** Only resets if files have grown beyond a header. If running `/complete-milestone` first, files are already archived and reset. --- ## 6. Commit ```bash git add .gsd/ROADMAP.md .gsd/STATE.md git commit -m "docs: create milestone {name}" ``` --- ## 7. Offer Next Steps ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► MILESTONE CREATED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Milestone: {name} Phases: {N} ─────────────────────────────────────────────────────── ▶ NEXT /plan 1 — Create Phase 1 execution plans ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/new-project.md ================================================ --- description: Initialize a new project with deep context gathering --- # /new-project Workflow Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap. This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. One command takes you from idea to ready-for-planning. **Creates:** - `.gsd/SPEC.md` — project specification - `.gsd/ROADMAP.md` — phase structure - `.gsd/STATE.md` — project memory - `.gsd/ARCHITECTURE.md` — system design (if brownfield) - All other .gsd/ documentation files **After this command:** Run `/plan 1` to start execution. ## Phase 1: Setup **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:** 1. **Abort if project exists:** **PowerShell:** ```powershell if (Test-Path ".gsd/SPEC.md") { Write-Error "Project already initialized. Use /progress" exit 1 } ``` **Bash:** ```bash if [ -f ".gsd/SPEC.md" ]; then echo "Error: Project already initialized. Use /progress" >&2 exit 1 fi ``` 2. **Initialize git repo** (if not exists): **PowerShell:** ```powershell if (-not (Test-Path ".git")) { git init Write-Output "Initialized new git repo" } ``` **Bash:** ```bash if [ ! -d ".git" ]; then git init echo "Initialized new git repo" fi ``` 3. **Detect existing code (brownfield detection):** **PowerShell:** ```powershell $codeFiles = Get-ChildItem -Recurse -Include "*.ts","*.js","*.py","*.go","*.rs" | Where-Object { $_.FullName -notmatch "node_modules|\.git" } | Select-Object -First 20 $hasPackage = Test-Path "package.json" -or Test-Path "requirements.txt" -or Test-Path "Cargo.toml" $hasArchitecture = Test-Path ".gsd/ARCHITECTURE.md" ``` **Bash:** ```bash code_files=$(find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) \ -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20) has_package=$(test -f "package.json" -o -f "requirements.txt" -o -f "Cargo.toml" && echo true || echo false) has_architecture=$(test -f ".gsd/ARCHITECTURE.md" && echo true || echo false) ``` --- ## Phase 2: Brownfield Offer **If existing code detected and ARCHITECTURE.md doesn't exist:** ``` ⚠️ EXISTING CODE DETECTED Found {N} source files in this directory. Options: A) Map codebase first — Run /map to understand existing architecture (Recommended) B) Skip mapping — Proceed with project initialization Which do you prefer? ``` **If "Map codebase first":** ``` Run `/map` first, then return to `/new-project` ``` Exit command. **If "Skip mapping":** Continue to Phase 3. **If no existing code detected OR codebase already mapped:** Continue to Phase 3. --- ## Phase 3: Deep Questioning Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► QUESTIONING ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` **Open the conversation:** Ask: "What do you want to build?" Wait for response. This gives context for intelligent follow-ups. **Follow the thread:** Based on their answer, ask follow-up questions that dig deeper: - What excited them about this idea - What problem sparked this - What they mean by vague terms - What it would actually look like - What's already decided **Questioning techniques:** - Challenge vagueness: "When you say 'fast', what does that mean specifically?" - Make abstract concrete: "Give me an example of how a user would..." - Surface assumptions: "You're assuming users will... Is that validated?" - Find edges: "What's explicitly NOT in scope?" - Reveal motivation: "Why does this matter now?" **Context checklist (gather mentally, not as interrogation):** - [ ] Vision — What does success look like? - [ ] Users — Who is this for? - [ ] Problem — What pain does it solve? - [ ] Scope — What's in, what's out? - [ ] Constraints — Technical, timeline, budget? - [ ] Prior art — What exists already? **Decision gate:** When you could write a clear SPEC.md: ``` Ready to create SPEC.md? A) Create SPEC.md — Let's move forward B) Keep exploring — I want to share more ``` If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally. Loop until "Create SPEC.md" selected. --- ## Phase 4: Write SPEC.md Create `.gsd/SPEC.md`: ```markdown # SPEC.md — Project Specification > **Status**: `FINALIZED` ## Vision {Distilled from questioning — one paragraph max} ## Goals 1. {Primary goal} 2. {Secondary goal} 3. {Tertiary goal} ## Non-Goals (Out of Scope) - {Explicitly excluded} - {Not in this version} ## Users {Who will use this and how} ## Constraints - {Technical constraints} - {Timeline constraints} - {Other limitations} ## Success Criteria - [ ] {Measurable outcome 1} - [ ] {Measurable outcome 2} ``` --- ## Phase 5: Research Decision If project involves unfamiliar technology or architectural decisions: ``` 📚 RESEARCH CHECK This project involves {area where research might help}. Would you like to: A) Do research first — Investigate options before committing B) Skip research — I know what I want, let's plan ``` **If research selected:** - Create `.gsd/RESEARCH.md` with findings - Document technology choices and rationale - Return to continue --- ## Phase 6: Define Requirements Generate requirements from SPEC.md: ```markdown # REQUIREMENTS.md ## Format | ID | Requirement | Source | Status | |----|-------------|--------|--------| | REQ-01 | {requirement} | SPEC goal 1 | Pending | | REQ-02 | {requirement} | SPEC goal 2 | Pending | ``` **Rules:** - Each requirement is testable - Each maps to a SPEC goal - Status starts as "Pending" **If simple project:** Skip formal requirements, SPEC.md is sufficient. --- ## Phase 7: Create Roadmap Create `.gsd/ROADMAP.md`: ```markdown # ROADMAP.md > **Current Phase**: Not started > **Milestone**: v1.0 ## Must-Haves (from SPEC) - [ ] {must-have 1} - [ ] {must-have 2} ## Phases ### Phase 1: {Foundation} **Status**: ⬜ Not Started **Objective**: {what this delivers} **Requirements**: REQ-01, REQ-02 ### Phase 2: {Core Feature} **Status**: ⬜ Not Started **Objective**: {what this delivers} **Requirements**: REQ-03 ### Phase 3: {Integration} **Status**: ⬜ Not Started **Objective**: {what this delivers} ### Phase 4: {Polish/Launch} **Status**: ⬜ Not Started **Objective**: {final touches} ``` **Phase creation rules:** - 3-5 phases per milestone - Each phase has clear deliverable - Dependencies flow forward --- ## Phase 8: Initialize Remaining Files Create with templates: - `.gsd/STATE.md` — Empty state - `.gsd/DECISIONS.md` — Empty ADR log - `.gsd/JOURNAL.md` — Empty journal - `.gsd/TODO.md` — Empty todo list Create directories: - `.gsd/phases/` - `.gsd/templates/` --- ## Phase 9: Initial Commit ```bash git add .gsd/ git commit -m "chore: initialize GSD project - SPEC.md with vision and goals - ROADMAP.md with {N} phases - Project documentation structure" ``` --- ## Phase 10: Done ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PROJECT INITIALIZED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Project: {name} Phases: {N} Files created: • .gsd/SPEC.md (FINALIZED) • .gsd/ROADMAP.md ({N} phases) • .gsd/STATE.md • .gsd/DECISIONS.md • .gsd/JOURNAL.md ─────────────────────────────────────────────────────── ▶ NEXT /discuss-phase 1 — Clarify scope (optional but recommended) /plan 1 — Create Phase 1 execution plans ─────────────────────────────────────────────────────── 💡 The questioning phase is the highest-leverage moment. Time invested here pays dividends throughout execution. ─────────────────────────────────────────────────────── ``` ## Why Deep Questioning Matters The original GSD emphasizes that `/new-project` is the most leveraged moment. Every minute spent understanding what to build saves hours of building the wrong thing. **Signs questioning is done:** - You could explain the project to a stranger - You know what's NOT being built (scope edges) - Success criteria are measurable - You're excited to start planning **Signs more questioning needed:** - Vague terms remain unexplained - You don't know who the user is - Success is defined as "it works" - Scope keeps expanding during discussion ================================================ FILE: .agent/workflows/pause.md ================================================ --- description: Context hygiene — dump state for clean session handoff --- # /pause Workflow Safely pause work with complete state preservation for session handoff. - Ending a work session - Context getting heavy (many failed attempts) - Switching to a different task - Before taking a break - After 3+ debugging failures (Context Hygiene rule) ## 1. Capture Current State Update `.gsd/STATE.md`: ```markdown ## Current Position - **Phase**: {current phase number and name} - **Task**: {specific task in progress, if any} - **Status**: Paused at {timestamp} ## Last Session Summary {What was accomplished this session} ## In-Progress Work {Any uncommitted changes or partial work} - Files modified: {list} - Tests status: {passing/failing/not run} ## Blockers {What was preventing progress, if anything} ## Context Dump {Critical context that would be lost}: ### Decisions Made - {Decision 1}: {rationale} - {Decision 2}: {rationale} ### Approaches Tried - {Approach 1}: {outcome} - {Approach 2}: {outcome} ### Current Hypothesis {Best guess at solution/issue} ### Files of Interest - `{file1}`: {what's relevant} - `{file2}`: {what's relevant} ## Next Steps 1. {Specific first action for next session} 2. {Second priority} 3. {Third priority} ``` --- ## 2. Add Journal Entry Create entry in `.gsd/JOURNAL.md`: ```markdown ## Session: {YYYY-MM-DD HH:MM} ### Objective {What this session was trying to accomplish} ### Accomplished - {Item 1} - {Item 2} ### Verification - [x] {What was verified} - [ ] {What still needs verification} ### Paused Because {Reason for pausing} ### Handoff Notes {Critical info for resuming} ``` --- ## 3. Commit State ```bash git add .gsd/STATE.md .gsd/JOURNAL.md git commit -m "docs: pause session - {brief reason}" ``` --- ## 4. Display Handoff ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► SESSION PAUSED ⏸ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ State saved to: • .gsd/STATE.md • .gsd/JOURNAL.md ─────────────────────────────────────────────────────── To resume later: /resume ─────────────────────────────────────────────────────── 💡 Fresh context = fresh perspective The struggles end here. Next session starts clean. ─────────────────────────────────────────────────────── ``` If pausing due to debugging failures: 1. Be explicit about what failed 2. Document exact error messages 3. List files that were touched 4. State your hypothesis clearly 5. Suggest what to try next (different approach) A fresh context often immediately sees solutions that a polluted context missed. ## Proactive Auto-Save (Session Limit Protection) **Problem:** If a session hard-terminates (usage/context limit), `/pause` becomes unreachable. **Solution:** The agent should auto-save state BEFORE limits are hit. ### When to Auto-Save | Trigger | Action | |---------|--------| | Context usage reaches ~50-70% | Write lightweight state snapshot to `.gsd/STATE.md` | | 3-strike debugging rule fires | Save state dump BEFORE recommending `/pause` | | Extended session detected | Periodic state checkpoints to `.gsd/STATE.md` | ### Auto-Save Protocol 1. **Detect** context health warning signals (see context-health-monitor skill) 2. **Write** current state to `.gsd/STATE.md` immediately 3. **Then** inform the user and recommend `/pause` 4. If session terminates unexpectedly, state is already saved ### Minimum Auto-Save Content ```markdown ## Auto-Save: {timestamp} - **Phase**: {current phase} - **Task**: {current task or "between tasks"} - **Last Action**: {what was just completed} - **Next Step**: {what should happen next} ``` **Key principle:** Save first, recommend second. Never rely on the user being able to issue `/pause`. ================================================ FILE: .agent/workflows/plan-milestone-gaps.md ================================================ --- description: Create plans to address gaps found in milestone audit --- # /plan-milestone-gaps Workflow Create targeted plans to address gaps, technical debt, and issues identified during milestone audit. ## 1. Load Gap Information Read from: - Latest AUDIT.md or VERIFICATION.md - TODO.md for deferred items - DECISIONS.md for acknowledged debt --- ## 2. Categorize Gaps | Category | Priority | Action | |----------|----------|--------| | Must-have failures | 🔴 High | Create fix phase | | Technical debt | 🟡 Medium | Add to roadmap | | Nice-to-have misses | 🟢 Low | Add to backlog | --- ## 3. Create Gap Closure Phase Add new phase to ROADMAP.md: ```markdown ### Phase {N}: Gap Closure **Status**: ⬜ Not Started **Objective**: Address gaps from milestone audit **Gaps to Close:** - [ ] {gap 1} - [ ] {gap 2} ``` --- ## 4. Create PLAN.md for Each Gap ```markdown --- phase: {N} plan: fix-{gap-id} wave: 1 gap_closure: true --- # Fix: {Gap Description} ## Problem {What the audit found} ## Root Cause {Why it exists} ## Tasks Fix {issue} {files} {fix instructions} {original verification that failed} {criteria} ``` --- ## 5. Update STATE.md ```markdown ## Gap Closure Mode Addressing {N} gaps from milestone audit. ``` --- ## 6. Commit Plans ```powershell git add .gsd/ git commit -m "docs: create gap closure plans" ``` --- ## 7. Offer Execution ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► GAP CLOSURE PLANS CREATED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gaps identified: {N} Plans created: {M} ─────────────────────────────────────────────────────── ▶ NEXT /execute {N} --gaps-only — Execute gap closure plans ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/plan.md ================================================ --- description: The Strategist — Decompose requirements into executable phases in ROADMAP.md argument-hint: "[phase] [--research] [--skip-research] [--gaps]" --- # /plan Workflow You are a GSD planner orchestrator. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification. **Core responsibilities:** - Parse arguments and validate phase - Handle research (unless skipped or exists) - Create PLAN.md files with XML task structure - Verify plans with checker logic - Iterate until plans pass (max 3 iterations) Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. **Default flow:** Research (if needed) → Plan → Verify → Done **Why subagents:** Research and planning burn context fast. Verification uses fresh context. User sees the flow between agents in main context. **Phase number:** $ARGUMENTS (optional — auto-detects next unplanned phase if not provided) **Flags:** - `--research` — Force re-research even if RESEARCH.md exists - `--skip-research` — Skip research entirely, go straight to planning - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research) **Required files:** - `.gsd/SPEC.md` — Must be FINALIZED (Planning Lock) - `.gsd/ROADMAP.md` — Must have phases defined ## Solo Developer + Claude Workflow You are planning for ONE person (the user) and ONE implementer (Claude). - No teams, stakeholders, ceremonies, coordination overhead - User is the visionary/product owner - Claude is the builder ## Plans Are Prompts PLAN.md is NOT a document that gets transformed into a prompt. PLAN.md IS the prompt. It contains: - Objective (what and why) - Context (@file references) - Tasks (with verification criteria) - Success criteria (measurable) ## Quality Degradation Curve | Context Usage | Quality | State | |---------------|---------|-------| | 0-30% | PEAK | Thorough, comprehensive | | 30-50% | GOOD | Confident, solid work | | 50-70% | DEGRADING | Efficiency mode begins | | 70%+ | POOR | Rushed, minimal | **The rule:** Plans should complete within ~50% context. More plans, smaller scope. ## Aggressive Atomicity Each plan: **2-3 tasks max**. No exceptions. ## Discovery Protocol Discovery is MANDATORY unless you can prove current context exists. **Level 0 — Skip** (pure internal work) - ALL work follows established codebase patterns - No new external dependencies - Pure internal refactoring or feature extension **Level 1 — Quick Verification** (2-5 min) - Single known library, confirming syntax/version - Low-risk decision (easily changed later) - Action: Quick web search, no RESEARCH.md needed **Level 1.5 — Discovery** (5-15 min) - Quick library/option comparison (A vs B) - Low-to-medium risk, focused question - Action: Create DISCOVERY.md using `.gsd/templates/discovery.md` template **Level 2 — Standard Research** (15-30 min) - Choosing between 2-3 options - New external integration (API, service) - Medium-risk decision - Action: Create RESEARCH.md with findings **Level 3 — Deep Dive** (1+ hour) - Architectural decision with long-term impact - Novel problem without clear patterns - High-risk, hard to change later - Action: Full research with RESEARCH.md ## 1. Validate Environment (Planning Lock) **PowerShell:** ```powershell # Check SPEC.md exists and is finalized $spec = Get-Content ".gsd/SPEC.md" -Raw if ($spec -notmatch "FINALIZED") { Write-Error "SPEC.md must be FINALIZED before planning" exit } ``` **Bash:** ```bash # Check SPEC.md exists and is finalized if ! grep -q "FINALIZED" ".gsd/SPEC.md"; then echo "Error: SPEC.md must be FINALIZED before planning" >&2 exit 1 fi ``` **If not finalized:** Error — user must complete SPEC.md first. --- ## 2. Parse and Normalize Arguments Extract from $ARGUMENTS: - Phase number (integer) - `--research` flag - `--skip-research` flag - `--gaps` flag **If no phase number:** Detect next unplanned phase from ROADMAP.md. --- ## 3. Validate Phase **PowerShell:** ```powershell Select-String -Path ".gsd/ROADMAP.md" -Pattern "Phase $PHASE:" ``` **Bash:** ```bash grep "Phase $PHASE:" ".gsd/ROADMAP.md" ``` **If not found:** Error with available phases. **If found:** Extract phase name and description. --- ## 4. Ensure Phase Directory **PowerShell:** ```powershell $PHASE_DIR = ".gsd/phases/$PHASE" if (-not (Test-Path $PHASE_DIR)) { New-Item -ItemType Directory -Path $PHASE_DIR } ``` **Bash:** ```bash PHASE_DIR=".gsd/phases/$PHASE" mkdir -p "$PHASE_DIR" ``` --- ## 5. Handle Research **If `--gaps` flag:** Skip research (gap closure uses VERIFICATION.md). **If `--skip-research` flag:** Skip to step 6. **Check for existing research:** **PowerShell:** ```powershell Test-Path "$PHASE_DIR/RESEARCH.md" ``` **Bash:** ```bash test -f "$PHASE_DIR/RESEARCH.md" ``` **If RESEARCH.md exists AND `--research` flag NOT set:** - Display: `Using existing research: $PHASE_DIR/RESEARCH.md` - Skip to step 6 **If research needed:** Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► RESEARCHING PHASE {N} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Perform research based on discovery level (see ``). Create `$PHASE_DIR/RESEARCH.md` with findings. --- ## 6. Create Plans Display banner: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PLANNING PHASE {N} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### 6a. Gather Context Load: - `.gsd/SPEC.md` — Requirements - `.gsd/REQUIREMENTS.md` — Formal requirements tracking (if exists) - `.gsd/ROADMAP.md` — Phase description - `$PHASE_DIR/RESEARCH.md` — If exists - `.gsd/ARCHITECTURE.md` — If exists ### 6b. Decompose into Tasks For the phase goal: 1. Identify all deliverables 2. Break into atomic tasks (2-3 per plan) 3. Determine dependencies between tasks 4. Assign execution waves ### 6c. Write PLAN.md Files Create `$PHASE_DIR/{N}-PLAN.md`: ```markdown --- phase: {N} plan: 1 wave: 1 --- # Plan {N}.1: {Plan Name} ## Objective {What this plan delivers and why} ## Context - .gsd/SPEC.md - .gsd/ARCHITECTURE.md - {relevant source files} ## Tasks {Task name} {exact file paths} {Specific implementation instructions} - What to do - What to avoid and WHY {Command to prove task complete} {Measurable acceptance criteria} ... ## Success Criteria - [ ] {Measurable outcome 1} - [ ] {Measurable outcome 2} ``` --- ## 7. Verify Plans (Checker Logic) For each plan, verify: - [ ] All files specified exist or will be created - [ ] Actions are specific (no "implement X") - [ ] Verify commands are executable - [ ] Done criteria are measurable - [ ] Context references exist - [ ] Tests are meaningful (see Test Quality Rules below) **If issues found:** Fix and re-verify (max 3 iterations). ### Test Quality Rules Tests must verify real behavior, not just pass. Reject plans with tests that: | Anti-pattern | Example | Fix | |-------------|---------|-----| | **Mock everything** | Mocking the DB then asserting the mock was called | Use real DB or integration test | | **Tautological assert** | `assert mock.called` with no behavior check | Assert actual output or side effect | | **Always-pass test** | `assert True` or `assert response is not None` | Assert specific expected values | | **Testing the framework** | Asserting that Express returns 200 on a stub | Test your logic, not the framework | | **No negative cases** | Only testing the happy path | Include at least one failure/edge case | **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. --- ## 8. Update State Update `.gsd/STATE.md`: ```markdown ## Current Position - **Phase**: {N} - **Task**: Planning complete - **Status**: Ready for execution ## Next Steps 1. /execute {N} ``` --- ## 9. Commit Plans ```bash git add .gsd/phases/$PHASE/ git add .gsd/STATE.md git commit -m "docs(phase-$PHASE): create execution plans" ``` --- ## 10. Offer Next Steps ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {N} PLANNED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {X} plans created across {Y} waves Plans: • {N}.1: {Name} (wave 1) • {N}.2: {Name} (wave 1) • {N}.3: {Name} (wave 2) ─────────────────────────────────────────────────────── ▶ Next Up /execute {N} — run all plans ─────────────────────────────────────────────────────── ``` | Type | Use For | Autonomy | |------|---------|----------| | `auto` | Everything Claude can do independently | Fully autonomous | | `checkpoint:human-verify` | Visual/functional verification | Pauses for user | | `checkpoint:decision` | Implementation choices | Pauses for user | **Automation-first rule:** If Claude CAN do it, Claude MUST do it. Checkpoints are for verification AFTER automation. ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/map` | Run before /plan to get codebase context | | `/execute` | Runs PLAN.md files created by /plan | | `/verify` | Validates executed plans | ### Skills | Skill | Purpose | |-------|---------| | `planner` | Detailed planning methodology | | `plan-checker` | Validates plans before execution | ================================================ FILE: .agent/workflows/progress.md ================================================ --- description: Show current position in roadmap and next steps --- # /progress Workflow Quick status check — where are we and what's next? ## 1. Load Current State Read: - `.gsd/STATE.md` — Current position - `.gsd/ROADMAP.md` — Phase statuses --- ## 2. Calculate Progress Count phases: - Total phases - Completed phases (✅) - In progress (🔄) - Blocked (⏸️) - Not started (⬜) --- ## 3. Display Status ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PROGRESS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Project: {project name from SPEC.md} Milestone: {milestone from ROADMAP.md} ─────────────────────────────────────────────────────── PHASES ✅ Phase 1: {Name} ✅ Phase 2: {Name} 🔄 Phase 3: {Name} ← CURRENT ⬜ Phase 4: {Name} ⬜ Phase 5: {Name} Progress: {completed}/{total} ({percentage}%) ─────────────────────────────────────────────────────── CURRENT TASK {Current task from STATE.md, or "None"} ─────────────────────────────────────────────────────── BLOCKERS {Blockers from STATE.md, or "None"} ─────────────────────────────────────────────────────── ▶ NEXT UP {Recommended next action based on state} ─────────────────────────────────────────────────────── ``` --- ## 4. Suggest Action Based on status, recommend: | State | Recommendation | |-------|----------------| | Phase in progress | `/execute {N}` to continue | | Phase done, not verified | `/verify {N}` | | Verification failed | `/execute {N} --gaps-only` | | All phases complete | Celebrate! 🎉 | | No phases started | `/plan 1` to begin | | SPEC not finalized | Complete SPEC.md first | ================================================ FILE: .agent/workflows/remove-phase.md ================================================ --- description: Remove a phase from the roadmap (with safety checks) argument-hint: "" --- # /remove-phase Workflow Remove a phase from the roadmap, with safety checks for in-progress or completed work. ## 1. Validate Phase Exists **PowerShell:** ```powershell $phase = Select-String -Path ".gsd/ROADMAP.md" -Pattern "### Phase $N:" if (-not $phase) { Write-Error "Phase $N not found in ROADMAP.md" } ``` **Bash:** ```bash if ! grep -q "### Phase $N:" ".gsd/ROADMAP.md"; then echo "Error: Phase $N not found in ROADMAP.md" >&2 fi ``` --- ## 2. Check Phase Status **PowerShell:** ```powershell $status = Select-String -Path ".gsd/ROADMAP.md" -Pattern "Phase $N:.*\n.*Status: (.*)" ``` **Bash:** ```bash status=$(grep -A1 "Phase $N:" ".gsd/ROADMAP.md" | grep "Status:" | cut -d: -f2) ``` **Safety checks:** | Status | Action | |--------|--------| | ⬜ Not Started | Safe to remove | | 🔄 In Progress | Warn and confirm | | ✅ Complete | Error — archive instead | --- ## 3. Check for Dependencies Are other phases depending on this one? **PowerShell:** ```powershell Select-String -Path ".gsd/ROADMAP.md" -Pattern "Depends on.*Phase $N" ``` **Bash:** ```bash grep "Depends on.*Phase $N" ".gsd/ROADMAP.md" ``` **If dependencies exist:** ``` ⚠️ Phase {M} depends on Phase {N} Cannot remove. Consider: 1. Update dependent phases first 2. Use /insert-phase to restructure ``` --- ## 4. Confirm Removal ``` ⚠️ CONFIRM REMOVAL Phase {N}: {name} Status: {status} This will: - Remove phase from ROADMAP.md - Delete .gsd/phases/{N}/ if exists - Renumber subsequent phases Type "REMOVE" to confirm: ``` --- ## 5. Remove Phase 1. Delete from ROADMAP.md 2. Remove `.gsd/phases/{N}/` directory 3. Renumber subsequent phases (N+1 becomes N, etc.) 4. Update dependencies --- ## 6. Update STATE.md If currently in removed phase, set to previous phase or "Planning". --- ## 7. Commit ```bash git add -A git commit -m "docs: remove phase {N} - {name}" ``` --- ## 8. Display Result ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE REMOVED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Removed: Phase {N}: {name} Renumbered: {M} phases ─────────────────────────────────────────────────────── /progress — See updated roadmap ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/research-phase.md ================================================ --- description: Deep technical research for a phase argument-hint: " [--level 1|2|3]" --- # /research-phase Workflow Conduct technical research to inform planning decisions for a phase. ## Discovery Levels | Level | Time | Use When | |-------|------|----------| | 0 | 0 min | Already know, just doing it | | 1 | 2-5 min | Single library, confirming syntax | | 2 | 15-30 min | Choosing between options, new integration | | 3 | 1+ hour | Architectural decision, novel problem | **Default:** Level 2 unless specified. ## 1. Load Phase Context Read: - Phase objective from ROADMAP.md - Relevant ARCHITECTURE.md sections - STACK.md for current technologies --- ## 2. Identify Research Questions What needs to be understood before planning? ```markdown ## Research Questions 1. {Technical question 1} 2. {Technical question 2} 3. {Integration question} ``` --- ## 3. Conduct Research Based on discovery level: **Level 1:** Quick verification - Check official docs - Confirm API/syntax **Level 2:** Comparison research - Compare 2-3 options - Evaluate trade-offs - Make recommendation **Level 3:** Deep dive - Prototype if needed - Research edge cases - Document unknowns --- ## 4. Generate RESEARCH.md Create `.gsd/phases/{N}/RESEARCH.md`: ```markdown --- phase: {N} level: {1|2|3} researched_at: {date} --- # Phase {N} Research ## Questions Investigated 1. {question} 2. {question} ## Findings ### {Topic 1} {What was learned} **Sources:** - {URL} **Recommendation:** {what to do} ### {Topic 2} ... ## Decisions Made | Decision | Choice | Rationale | |----------|--------|-----------| | {decision} | {choice} | {why} | ## Patterns to Follow - {pattern 1} - {pattern 2} ## Anti-Patterns to Avoid - {anti-pattern}: {why} ## Dependencies Identified | Package | Version | Purpose | |---------|---------|---------| | {pkg} | {ver} | {why} | ## Risks - {risk}: {mitigation} ## Ready for Planning - [x] Questions answered - [x] Approach selected - [x] Dependencies identified ``` --- ## 5. Commit Research ```powershell git add .gsd/phases/{N}/RESEARCH.md git commit -m "docs(phase-{N}): research complete" ``` --- ## 6. Offer Next Steps ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► RESEARCH COMPLETE ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Phase {N}: {name} Level: {level} Key findings: • {finding 1} • {finding 2} ─────────────────────────────────────────────────────── ▶ NEXT /plan {N} — Create plans informed by research ─────────────────────────────────────────────────────── ``` ================================================ FILE: .agent/workflows/resume.md ================================================ --- description: Restore context from previous session --- # /resume Workflow Start a new session with full context from where we left off. ## 1. Load Saved State Read `.gsd/STATE.md` completely. --- ## 2. Display Context ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► RESUMING SESSION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ LAST POSITION ───────────── Phase: {phase from STATE.md} Task: {task from STATE.md} Status: {status when paused} ─────────────────────────────────────────────────────── CONTEXT FROM LAST SESSION ───────────────────────── {Context dump content from STATE.md} ─────────────────────────────────────────────────────── BLOCKERS ──────── {Blockers from STATE.md, or "None"} ─────────────────────────────────────────────────────── NEXT STEPS (from last session) ────────────────────────────── 1. {First priority} 2. {Second priority} 3. {Third priority} ─────────────────────────────────────────────────────── ``` --- ## 3. Load Recent Journal Show last entry from `.gsd/JOURNAL.md`: - What was accomplished - Handoff notes - Any issues encountered --- ## 4. Check for Conflicts ```bash # Check for uncommitted changes git status --porcelain ``` **If changes found:** ``` ⚠️ UNCOMMITTED CHANGES DETECTED {list of modified files} These may be from the previous session. Review before proceeding. ``` --- ## 5. Update State Mark session as active in `.gsd/STATE.md`: ```markdown **Status**: Active (resumed {timestamp}) ``` --- ## 6. Suggest Action ``` ─────────────────────────────────────────────────────── ▶ READY TO CONTINUE Suggested action based on state: {One of:} • /execute {N} — Continue phase execution • /verify {N} — Verify completed phase • /plan {N} — Create plans for phase • /progress — See full roadmap status ─────────────────────────────────────────────────────── 💡 Fresh session = fresh perspective You have all the context you need. The previous struggles are documented. Time to solve this with fresh eyes. ─────────────────────────────────────────────────────── ``` A resumed session has advantages: 1. **No accumulated confusion** — You see the problem clearly 2. **Documented failures** — You know what NOT to try 3. **Hypothesis preserved** — Pick up where logic left off 4. **Full context budget** — 200k tokens of fresh capacity Often the first thing a fresh context sees is the obvious solution that a tired context missed. ================================================ FILE: .agent/workflows/sprint.md ================================================ --- description: Create and manage a time-boxed sprint for quick focused work argument-hint: "[new|status|close] [sprint-name]" --- # /sprint Workflow Manage time-boxed sprints for quick, focused work outside the full milestone/phase cycle. Sprints are ideal for bug fixes, small features, or exploratory work that doesn't warrant a full planning cycle. ## 1. Parse Arguments Extract from $ARGUMENTS: - **Action**: `new` (default), `status`, or `close` - **Sprint name**: identifier for the sprint **If no arguments:** Default to `new` and ask for sprint details. --- ## 2a. Action: New Sprint ### Gather Sprint Information Ask for: - **Name** — Sprint identifier (e.g., "bugfix-auth", "spike-caching") - **Goal** — One sentence describing the sprint goal - **Duration** — Timeframe (e.g., "2 days", "1 week") - **Scope** — Tasks included and explicitly excluded ### Create Sprint File Create `.gsd/SPRINT.md` using the template from `.gsd/templates/sprint.md`: ```markdown # Sprint {N} — {Sprint Name} > **Duration**: {start-date} to {end-date} > **Status**: In Progress ## Goal {One sentence goal} ## Scope ### Included - {Task 1} - {Task 2} ### Explicitly Excluded - {Out of scope item} ## Tasks | Task | Assignee | Status | Est. Hours | |------|----------|--------|------------| | {Task 1} | Claude | ⬜ Todo | — | | {Task 2} | Claude | ⬜ Todo | — | ## Daily Log ### {today's date} - Sprint created ``` ### Update STATE.md ```markdown ## Current Position - **Sprint**: {name} - **Status**: Sprint in progress - **Milestone**: (paused if active) ``` ### Commit ```bash git add .gsd/SPRINT.md .gsd/STATE.md git commit -m "docs: create sprint {name}" ``` --- ## 2b. Action: Status Read `.gsd/SPRINT.md` and display: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► SPRINT STATUS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Sprint: {name} Duration: {start} to {end} Tasks: {done}/{total} complete {task table} ─────────────────────────────────────────────────────── ``` --- ## 2c. Action: Close ### Verify Sprint Complete Check all tasks are done or explicitly deferred. ### Generate Retrospective Append to `.gsd/SPRINT.md`: ```markdown ## Retrospective ({date}) ### What Went Well - {auto-extract from daily log} ### What Could Improve - {identify blockers or friction} ### Action Items - [ ] {carry-forward items} ``` ### Archive Sprint **PowerShell:** ```powershell New-Item -ItemType Directory -Force ".gsd/sprints" Move-Item ".gsd/SPRINT.md" ".gsd/sprints/{name}-SPRINT.md" ``` **Bash:** ```bash mkdir -p .gsd/sprints mv .gsd/SPRINT.md ".gsd/sprints/{name}-SPRINT.md" ``` ### Update STATE.md Restore previous milestone position or mark as idle. ### Commit ```bash git add .gsd/sprints/ .gsd/STATE.md git commit -m "docs: close sprint {name}" ``` ### Display Result ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► SPRINT CLOSED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Sprint: {name} Tasks completed: {N}/{total} ─────────────────────────────────────────────────────── ▶ NEXT /resume — Return to milestone work /sprint new — Start another sprint ─────────────────────────────────────────────────────── ``` ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/plan` | Full planning cycle (use for milestone work) | | `/execute` | Full execution cycle (use for milestone work) | | `/pause` | Pause current work for handoff | ### Templates | Template | Purpose | |----------|---------| | `sprint.md` | Sprint document structure | ================================================ FILE: .agent/workflows/update.md ================================================ --- description: Update GSD to the latest version from GitHub --- # /update Workflow Update GSD for Antigravity to the latest version from GitHub. ## 1. Check Current Version **PowerShell:** ```powershell if (Test-Path "CHANGELOG.md") { $version = Select-String -Path "CHANGELOG.md" -Pattern "## \[(\d+\.\d+\.\d+)\]" | Select-Object -First 1 Write-Output "Current version: $($version.Matches.Groups[1].Value)" } ``` **Bash:** ```bash if [ -f "CHANGELOG.md" ]; then version=$(grep -oP '## \[\K[0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md | head -1) echo "Current version: $version" fi ``` --- ## 2. Fetch Latest from GitHub ```bash # Clone latest to temp directory git clone --depth 1 https://github.com/toonight/get-shit-done-for-antigravity.git .gsd-update-temp ``` --- ## 3. Compare Versions **PowerShell:** ```powershell $remoteVersion = Select-String -Path ".gsd-update-temp/CHANGELOG.md" -Pattern "## \[(\d+\.\d+\.\d+)\]" | Select-Object -First 1 Write-Output "Remote version: $($remoteVersion.Matches.Groups[1].Value)" ``` **Bash:** ```bash remote_version=$(grep -oP '## \[\K[0-9]+\.[0-9]+\.[0-9]+' .gsd-update-temp/CHANGELOG.md | head -1) echo "Remote version: $remote_version" ``` **If same version:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► ALREADY UP TO DATE ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Version: {version} No updates available. ─────────────────────────────────────────────────────── ``` Exit after cleanup. --- ## 4. Show Changes ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► UPDATE AVAILABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Current: {current-version} Latest: {remote-version} Changes: {Extract from CHANGELOG.md} ─────────────────────────────────────────────────────── Update now? A) Yes — Apply updates B) No — Cancel ─────────────────────────────────────────────────────── ``` --- ## 5. Apply Updates **If user confirms:** **PowerShell:** ```powershell # Backup current Copy-Item -Recurse ".agent" ".agent.backup" Copy-Item -Recurse ".agents" ".agents.backup" Copy-Item -Recurse ".gsd/templates" ".gsd/templates.backup" # Update workflows (preserve user's .gsd docs) Copy-Item -Recurse -Force ".gsd-update-temp/.agent/*" ".agent/" # Update skills (Agent Skills standard) Copy-Item -Recurse -Force ".gsd-update-temp/.agents/*" ".agents/" # Update templates only Copy-Item -Recurse -Force ".gsd-update-temp/.gsd/templates/*" ".gsd/templates/" # Update root files Copy-Item -Force ".gsd-update-temp/GSD-STYLE.md" "./" Copy-Item -Force ".gsd-update-temp/CHANGELOG.md" "./" Copy-Item -Force ".gsd-update-temp/PROJECT_RULES.md" "./" Copy-Item -Force ".gsd-update-temp/VERSION" "./" ``` **Bash:** ```bash # Backup current cp -r .agent .agent.backup cp -r .agents .agents.backup cp -r .gsd/templates .gsd/templates.backup # Update workflows (preserve user's .gsd docs) cp -r .gsd-update-temp/.agent/* .agent/ # Update skills (Agent Skills standard) cp -r .gsd-update-temp/.agents/* .agents/ # Update templates only cp -r .gsd-update-temp/.gsd/templates/* .gsd/templates/ # Update root files cp .gsd-update-temp/GSD-STYLE.md ./ cp .gsd-update-temp/CHANGELOG.md ./ cp .gsd-update-temp/PROJECT_RULES.md ./ cp .gsd-update-temp/VERSION ./ ``` --- ## 6. Cleanup **PowerShell:** ```powershell Remove-Item -Recurse -Force ".gsd-update-temp" Remove-Item -Recurse -Force ".agent.backup" Remove-Item -Recurse -Force ".agents.backup" Remove-Item -Recurse -Force ".gsd/templates.backup" ``` **Bash:** ```bash rm -rf .gsd-update-temp rm -rf .agent.backup rm -rf .agents.backup rm -rf .gsd/templates.backup ``` --- ## 7. Confirm ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► UPDATED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Updated to version {remote-version} ─────────────────────────────────────────────────────── /whats-new — See what changed ─────────────────────────────────────────────────────── ``` These user files are NEVER overwritten: - .gsd/SPEC.md - .gsd/ROADMAP.md - .gsd/STATE.md - .gsd/ARCHITECTURE.md - .gsd/STACK.md - .gsd/DECISIONS.md - .gsd/JOURNAL.md - .gsd/TODO.md - .gsd/phases/* - .gemini/GEMINI.md ================================================ FILE: .agent/workflows/verify.md ================================================ --- description: The Auditor — Validate work against spec with empirical evidence argument-hint: "" --- # /verify Workflow You are a GSD verifier. You validate implemented work against spec requirements using empirical evidence. **Core principle:** No "trust me, it works." Every verification produces proof. **Core responsibilities:** - Extract testable deliverables from phase - Walk through each requirement - Collect empirical evidence (commands, screenshots) - Create verification report - Generate fix plans if issues found Confirm that implemented work meets spec requirements with documented proof. The verifier checks the CODEBASE, not SUMMARY claims. **Phase:** $ARGUMENTS (required — phase number to verify) **Required files:** - `.gsd/SPEC.md` — Original requirements - `.gsd/ROADMAP.md` — Phase definition with must-haves - `.gsd/phases/{phase}/*-SUMMARY.md` — What was implemented ## 1. Load Verification Context Read: - Phase definition from `.gsd/ROADMAP.md` - Original requirements from `.gsd/SPEC.md` - All SUMMARY.md files from `.gsd/phases/{phase}/` --- ## 2. Extract Must-Haves From the phase definition, identify **must-haves** — requirements that MUST be true for the phase to be complete. ```markdown ### Must-Haves for Phase {N} 1. {Requirement 1} — How to verify 2. {Requirement 2} — How to verify 3. {Requirement 3} — How to verify ``` --- ## 3. Verify Each Must-Have For each must-have: ### 3a. Determine Verification Method | Type | Method | Evidence | |------|--------|----------| | API/Backend | Run curl or test command | Command output | | UI | Use browser tool | Screenshot | | Build | Run build command | Success output | | Tests | Run test suite | Test results | | File exists | Check filesystem | File listing | | Code behavior | Run specific scenario | Output | ### 3b. Execute Verification Run the verification command/action. // turbo ```bash # Example: Run tests npm test ``` ### 3c. Record Evidence For each must-have, record: - **Status:** PASS / FAIL - **Evidence:** Command output, screenshot path, etc. - **Notes:** Any observations --- ## 4. Create Verification Report Write `.gsd/phases/{phase}/VERIFICATION.md`: ```markdown --- phase: {N} verified_at: {timestamp} verdict: PASS | FAIL | PARTIAL --- # Phase {N} Verification Report ## Summary {X}/{Y} must-haves verified ## Must-Haves ### ✅ {Must-have 1} **Status:** PASS **Evidence:** ``` {command output or description} ``` ### ❌ {Must-have 2} **Status:** FAIL **Reason:** {why it failed} **Expected:** {what should happen} **Actual:** {what happened} ## Verdict {PASS | FAIL | PARTIAL} ## Gap Closure Required {If FAIL, list what needs to be fixed} ``` --- ## 5. Handle Results ### If PASS (all must-haves verified): Update `.gsd/STATE.md`: ```markdown ## Current Position - **Phase**: {N} (verified) - **Status**: ✅ Complete and verified ``` Output: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {N} VERIFIED ✓ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {X}/{X} must-haves verified All requirements satisfied. ─────────────────────────────────────────────────────── ▶ Next Up /execute {N+1} — proceed to next phase ─────────────────────────────────────────────────────── ``` ### If FAIL (some must-haves failed): **Create gap closure plans:** For each failed must-have, create a fix plan in `.gsd/phases/{phase}/`: ```markdown --- phase: {N} plan: fix-{issue} wave: 1 gap_closure: true --- # Fix Plan: {Issue Name} ## Problem {What failed and why} ## Tasks Fix {issue} {files to modify} {specific fix instructions} {how to verify the fix} {acceptance criteria} ``` Output: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► PHASE {N} GAPS FOUND ⚠ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ {X}/{Y} must-haves verified {Z} issues require fixes Gap closure plans created. ─────────────────────────────────────────────────────── ▶ Next Up /execute {N} --gaps-only — run fix plans ─────────────────────────────────────────────────────── ``` --- ## 6. Commit Verification ```bash git add .gsd/phases/{phase}/VERIFICATION.md git commit -m "docs(phase-{N}): verification report" ``` ## Forbidden Phrases Never accept these as verification: - "This should work" - "The code looks correct" - "I've made similar changes before" - "Based on my understanding" - "It follows the pattern" ## Required Evidence | Claim | Required Proof | |-------|----------------| | "Tests pass" | Actual test output | | "API works" | Curl command + response | | "UI renders" | Screenshot | | "Build succeeds" | Build output | | "File created" | `ls` or `dir` output | ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/execute` | Run before /verify to implement work | | `/execute --gaps-only` | Fix issues found by /verify | | `/debug` | Diagnose verification failures | ### Skills | Skill | Purpose | |-------|---------| | `verifier` | Detailed verification methodology | | `empirical-validation` | Evidence requirements | ================================================ FILE: .agent/workflows/web-search.md ================================================ --- description: Search the web for information to inform decisions argument-hint: " [--domain ]" --- # /web-search Workflow Search the web to gather information for technical decisions, API documentation, library comparisons, or any research need. - Evaluating libraries or frameworks - Finding API documentation - Checking current best practices - Researching error messages - Comparing implementation approaches - Getting up-to-date information on tools/services ## 1. Formulate Query Parse the user's request into a focused search query. **Good queries:** - Specific: "Next.js 14 app router authentication best practices" - Targeted: "Prisma vs Drizzle ORM comparison 2024" - Actionable: "how to fix CORS error Express.js" **Bad queries:** - Too broad: "how to code" - Too vague: "best database" --- ## 2. Execute Search Use the `search_web` tool with: - Query: The formulated search query - Domain (optional): Prioritize specific site (e.g., `docs.python.org`) --- ## 3. Analyze Results From the search results: 1. **Extract key information** relevant to the user's need 2. **Note sources** for citations 3. **Identify patterns** across multiple results 4. **Flag contradictions** or outdated information --- ## 4. Summarize Findings Present findings clearly: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► WEB SEARCH RESULTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Query: {query} ─────────────────────────────────────────────────────── KEY FINDINGS ──────────── • {finding 1} • {finding 2} • {finding 3} RECOMMENDATION ────────────── {actionable recommendation based on findings} SOURCES ─────── • {source 1} • {source 2} ─────────────────────────────────────────────────────── ``` --- ## 5. Offer Next Steps Based on findings: - Suggest follow-up searches if needed - Recommend adding to RESEARCH.md for project context - Offer to implement based on findings ## Integration with GSD **During /research-phase:** Use `/web-search` to gather information for RESEARCH.md. **During /plan:** Use `/web-search` when discovery level 1-3 indicates research needed. **During /debug:** Use `/web-search` to find solutions to error messages. ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/research-phase` | Uses web-search for phase research | | `/plan` | May trigger web-search for discovery | | `/debug` | Search for error solutions | ================================================ FILE: .agent/workflows/whats-new.md ================================================ --- description: Show recent GSD changes and new features --- # /whats-new Workflow Display recent changes, new features, and improvements to GSD for Antigravity. ## 1. Read CHANGELOG.md ```bash # Read the latest version section from CHANGELOG.md head -50 CHANGELOG.md ``` ## 2. Display Recent Changes Display the latest version(s) from CHANGELOG.md: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► WHAT'S NEW ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VERSION 1.2.0 — 2026-01-17 ══════════════════════════ 🌍 CROSS-PLATFORM SUPPORT • All 16 workflow files now have Bash equivalents • README with dual-syntax Getting Started • /web-search workflow for research ─────────────────────────────────────────────────────── VERSION 1.1.0 — 2026-01-17 ══════════════════════════ 📚 TEMPLATE PARITY & EXAMPLES • 14 new templates (DEBUG.md, UAT.md, etc.) • Examples directory with walkthroughs • /add-todo and /check-todos workflows • Cross-references between workflows ─────────────────────────────────────────────────────── VERSION 1.0.0 — 2026-01-17 ══════════════════════════ 🎉 INITIAL RELEASE Full port of GSD methodology to Google Antigravity. • 24 workflows, 8 skills, 14 templates • 4 core rules: Planning Lock, State Persistence, Context Hygiene, Empirical Validation ─────────────────────────────────────────────────────── 📚 Full changelog: CHANGELOG.md ─────────────────────────────────────────────────────── ``` ## Related ### Workflows | Command | Relationship | |---------|--------------| | `/update` | Update GSD to latest version | | `/help` | List all commands | ================================================ FILE: .agents/skills/codebase-mapper/SKILL.md ================================================ --- name: codebase-mapper description: Analyzes existing codebases to understand structure, patterns, and technical debt --- # GSD Codebase Mapper Agent You are a GSD codebase mapper. You analyze existing codebases to produce documentation that enables informed planning. **Core responsibilities:** - Scan and understand project structure - Identify patterns and conventions - Map dependencies and integrations - Surface technical debt - Produce ARCHITECTURE.md and STACK.md ## Analysis Domains ### 1. Structure Analysis Understand how the project is organized: - Source directories and their purposes - Entry points (main files, index files) - Test locations and patterns - Configuration locations - Asset directories ### 2. Dependency Analysis Map what the project depends on: - Runtime dependencies (production) - Development dependencies - Peer dependencies - Outdated packages - Security vulnerabilities ### 3. Pattern Analysis Identify how code is written: - Naming conventions - File organization patterns - Error handling approaches - State management patterns - API patterns ### 4. Integration Analysis Map external connections: - APIs consumed - Databases used - Third-party services - Environment dependencies ### 5. Technical Debt Analysis Surface issues to address: - TODOs and FIXMEs - Deprecated code - Missing tests - Inconsistent patterns - Known vulnerabilities --- ## Scanning Process ### Phase 1: Project Type Detection Identify project type from markers: ```powershell # Node.js/JavaScript Test-Path "package.json" # Python Test-Path "requirements.txt" -or Test-Path "pyproject.toml" # Rust Test-Path "Cargo.toml" # Go Test-Path "go.mod" # .NET Get-ChildItem "*.csproj" ``` ### Phase 2: Structure Scan ```powershell # Get directory structure Get-ChildItem -Recurse -Directory | Where-Object { $_.Name -notmatch "node_modules|\.git|__pycache__|dist|build|\.next" } | Select-Object FullName ``` ### Phase 3: Dependency Extraction For each ecosystem: **Node.js:** ```powershell $pkg = Get-Content "package.json" | ConvertFrom-Json $pkg.dependencies $pkg.devDependencies ``` **Python:** ```powershell Get-Content "requirements.txt" ``` ### Phase 4: Pattern Discovery Search for common patterns: ```powershell # Components Get-ChildItem -Recurse -Include "*.tsx","*.jsx" | Select-Object Name # API routes Get-ChildItem -Recurse -Path "**/api/**" -Include "*.ts","*.js" # Models/schemas Select-String -Path "**/*.ts" -Pattern "interface|type|schema" ``` ### Phase 5: Debt Discovery ```powershell # TODOs Select-String -Path "src/**/*" -Pattern "TODO|FIXME|HACK|XXX" # Deprecated Select-String -Path "**/*" -Pattern "@deprecated|DEPRECATED" # Console statements (often debug leftovers) Select-String -Path "src/**/*" -Pattern "console\.(log|debug|warn)" ``` --- ## Output Format ### ARCHITECTURE.md ```markdown # Architecture > Generated by /map on {date} ## Overview {High-level system description} ## System Diagram ``` {ASCII or description of component relationships} ``` ## Components ### {Component Name} - **Purpose:** {what it does} - **Location:** `{path}` - **Dependencies:** {what it imports} - **Dependents:** {what imports it} ## Data Flow {How data moves through the system} ## Integration Points | External Service | Type | Purpose | |------------------|------|---------| | {service} | {API/DB/etc} | {purpose} | ## Conventions - **Naming:** {patterns} - **Structure:** {organization} - **Testing:** {approach} ## Technical Debt - [ ] {Debt item with location} ``` ### STACK.md ```markdown # Technology Stack > Generated by /map on {date} ## Runtime | Technology | Version | Purpose | |------------|---------|---------| | {tech} | {version} | {purpose} | ## Production Dependencies | Package | Version | Purpose | |---------|---------|---------| | {pkg} | {version} | {purpose} | ## Development Dependencies | Package | Version | Purpose | |---------|---------|---------| | {pkg} | {version} | {purpose} | ## Infrastructure | Service | Provider | Purpose | |---------|----------|---------| | {svc} | {provider} | {purpose} | ## Configuration | Variable | Purpose | Required | |----------|---------|----------| | {var} | {purpose} | {yes/no} | ``` --- ## Checklist Before Completing Map: - [ ] Project type identified - [ ] All source directories documented - [ ] Entry points found - [ ] Dependencies extracted and categorized - [ ] Key patterns identified - [ ] Integrations mapped - [ ] Technical debt surfaced - [ ] ARCHITECTURE.md created - [ ] STACK.md created ================================================ FILE: .agents/skills/context-compressor/SKILL.md ================================================ --- name: context-compressor description: Strategies for compressing context to maximize token efficiency --- # Context Compressor Skill You are a context compression specialist. Your job is to maintain rich understanding while using minimal tokens. **Core principle:** Compress aggressively, decompress only when needed. --- ## Compression Strategies ### Strategy 1: Summary Mode **When:** You've fully understood a file and may need to reference it later. **How:** ```markdown ## File Summary: src/auth/login.ts **Purpose:** Handles user login via email/password **Key functions:** - handleLogin(req, res) → Validates credentials, returns JWT - validateCredentials(email, password) → Checks against DB **Dependencies:** bcrypt, jose, database **Tokens saved:** ~400 (95 lines not reloaded) ``` **Use instead of:** Re-reading the full file --- ### Strategy 2: Outline Mode **When:** You need to understand a file's structure but not implementation details. **How:** ```markdown ## Outline: src/services/payment.ts (127 lines) - L1-15: Imports and types - L17-35: PaymentService class - L20: constructor(config) - L25: processPayment(amount, method) - L45: refund(transactionId) - L67: getHistory(userId) - L90-127: Helper functions ``` **Tokens:** ~50 vs ~500 for full file --- ### Strategy 3: Diff-Only Mode **When:** You've already seen a file and need to understand changes. **How:** ```markdown ## Changes to: src/config.ts Added: - L45: TOKEN_BUDGET_THRESHOLD = 0.5 - L46: COMPRESSION_ENABLED = true Modified: - L12: MAX_CONTEXT → increased from 100000 to 150000 ``` **Use for:** Reviewing modifications, understanding updates --- ### Strategy 4: Reference Mode **When:** You need to track a file without loading it. **How:** ```markdown ## References | File | Last Seen | Summary | Load If | |------|-----------|---------|---------| | auth.ts | Task 2 | Login handling | Auth bugs | | db.ts | Task 1 | Postgres client | DB errors | | utils.ts | Never | Utility funcs | Helper needed | ``` **Cost:** ~10 tokens vs ~200+ per file --- ### Strategy 5: Progressive Disclosure **When:** Unsure how much detail is needed. **Process:** 1. Start with outline (Level 1) 2. If insufficient, load key functions (Level 2) 3. If still stuck, load related code (Level 3) 4. Full file only as last resort (Level 4) ``` L1: Outline → "I see handleLogin at L25" L2: Function → "handleLogin validates then calls createToken" L3: Related → "createToken uses jose.sign with HS256" L4: Full → Only for complex debugging ``` --- ## Compression Triggers ### Automatic Compression Points | Trigger | Action | |---------|--------| | After understanding a file | Create summary | | Switching tasks | Compress previous context | | Budget at 50% | Aggressive outline mode | | Budget at 70% | Summary-only mode | | End of wave | Full compression pass | --- ## Decompression Protocol When you need details from compressed context: 1. **Check summary first** — Often sufficient 2. **Load specific section** — If summary incomplete 3. **Full load as last resort** — And re-compress after ```markdown ## Decompression Log | File | Reason | Level | Tokens | |------|--------|-------|--------| | auth.ts | Debug login | L2 (func) | +150 | | db.ts | Check query | L3 (snippet) | +50 | ``` --- ## Compression Format Templates ### Summary Template ```markdown ## 📦 [filename] **Purpose:** [one line] **Key exports:** [list] **Dependencies:** [list] **Patterns:** [notable patterns used] **Watch for:** [gotchas or edge cases] ``` ### Outline Template ```markdown ## 📋 [filename] (N lines) - L[start]-[end]: [section name] - L[n]: [key item] - L[n]: [key item] ``` ### Diff Template ```markdown ## Δ [filename] **+** [additions] **-** [removals] **~** [modifications] ``` --- ## Integration Works with: - `token-budget` — Triggers compression at thresholds - `context-fetch` — Provides input for compression - `context-health-monitor` — Monitors compression effectiveness --- ## Anti-Patterns ❌ **Keeping full files in mental context** — Compress after understanding ❌ **Re-reading instead of referencing** — Use summaries ❌ **Loading full file for one function** — Use outline + target ❌ **Skipping compression "to save time"** — Costs more later --- *Part of GSD v1.6 Token Optimization. See docs/token-optimization-guide.md for examples.* ================================================ FILE: .agents/skills/context-fetch/SKILL.md ================================================ --- name: context-fetch description: Search-first skill to reduce unnecessary file reads by searching before loading --- # Context Fetch Skill You are a context-efficient agent. Your job is to find relevant code with minimal file reads. **Core principle:** Search first, read targeted sections, never load full files blindly. --- ## When to Use Activate this skill **before**: - Starting any coding task - Beginning a refactor - Investigating a bug - Understanding unfamiliar code --- ## Process ### Step 1: Define the Question What are you trying to find or understand? Examples: - "Where is the login endpoint defined?" - "How does the caching layer work?" - "What calls the `processPayment` function?" ### Step 2: Identify Keywords Extract searchable terms: | Question | Keywords | |----------|----------| | Login endpoint | `login`, `auth`, `POST.*login` | | Caching layer | `cache`, `redis`, `memoize` | | Payment calls | `processPayment`, `payment` | ### Step 3: Search Before Reading **PowerShell:** ```powershell # Simple pattern search Select-String -Path "src/**/*.ts" -Pattern "login" -Recurse # With ripgrep (if available) rg "login" --type ts ``` **Bash:** ```bash # With ripgrep (recommended) rg "login" --type ts # With grep grep -r "login" src/ --include="*.ts" ``` ### Step 4: Evaluate Results From search results, identify: 1. **Primary candidates** — Files directly matching your question 2. **Secondary candidates** — Files that reference primary candidates 3. **Ignore list** — Files with keyword but unrelated context ### Step 5: Targeted Reading Only read what's justified: ```powershell # Read specific line range (PowerShell) Get-Content "src/auth/login.ts" | Select-Object -Skip 49 -First 30 # Read specific function (with view_code_item tool) # view_code_item: src/auth/login.ts -> handleLogin ``` --- ## Inputs When invoking this skill, provide: | Input | Description | Example | |-------|-------------|---------| | **Question** | What you're trying to find | "Where is user validation?" | | **Scope** | Directory or file pattern | `src/`, `*.service.ts` | | **Keywords** | Terms to search for | `validate`, `user`, `schema` | --- ## Outputs After executing this skill, report: 1. **Candidate files** — Ranked by relevance 2. **Relevant extracts** — Key snippets found 3. **Next reads** — Specific files/line-ranges to read next 4. **Skip list** — Files searched but not relevant --- ## Anti-Patterns ### ❌ Loading Everything First ``` # BAD: Reading 5 full files to "understand context" Read: src/auth/login.ts (500 lines) Read: src/auth/register.ts (400 lines) Read: src/auth/types.ts (200 lines) ``` ### ✅ Search Then Target ``` # GOOD: Search first, read only what's needed Search: "validatePassword" in src/auth/ Found: login.ts:45, register.ts:78 Read: login.ts lines 40-60 ``` ### ❌ Broad Searches ``` # BAD: Searching for common terms Search: "function" → 10,000 results ``` ### ✅ Specific Searches ``` # GOOD: Searching for specific identifiers Search: "validateUserCredentials" → 3 results ``` --- ## Context Efficiency Metrics Track your efficiency: | Metric | Good | Poor | |--------|------|------| | Files searched | 10+ | <5 | | Files fully read | <3 | 10+ | | Lines read | <200 | 1000+ | | Targeted sections | Yes | No | --- ## Integration with GSD This skill supports GSD's context management: - **Prevents context pollution** — Less irrelevant code loaded - **Supports wave execution** — Each wave starts with minimal context - **Enables model switching** — Less context = easier handoff --- ## Quick Reference ``` 1. Define question → What am I looking for? 2. Extract keywords → What terms to search? 3. Search codebase → rg/grep/Select-String 4. Evaluate results → Which files matter? 5. Read targeted → Specific lines only 6. Report findings → Candidates + extracts ``` --- *Part of GSD methodology. See PROJECT_RULES.md for search-first discipline rules.* ================================================ FILE: .agents/skills/context-health-monitor/SKILL.md ================================================ --- name: context-health-monitor description: Monitors context complexity and triggers state dumps before quality degrades --- # Context Health Monitor ## Purpose Prevent "Context Rot" — the quality degradation that occurs as the agent processes more information in a single session. ## When This Skill Activates The agent should self-monitor for these warning signs: ### Warning Signs | Signal | Threshold | Action | |--------|-----------|--------| | Repeated debugging | 3+ failed attempts | Trigger state dump | | Going in circles | Same approach tried twice | Stop and reassess | | Confusion indicators | "I'm not sure", backtracking | Document uncertainty | | Session length | Extended back-and-forth | Recommend `/pause` | ## Behavior Rules ### Rule 1: The 3-Strike Rule If debugging the same issue fails 3 times: 1. **STOP** attempting fixes 2. **Document** in `.gsd/STATE.md`: - What was tried - What errors occurred - Current hypothesis 3. **Recommend** user start fresh session 4. **Do NOT** continue with more attempts ### Rule 2: Circular Detection If the same approach is being tried again: 1. **Acknowledge** the repetition 2. **List** what has already been tried 3. **Propose** a fundamentally different approach 4. **Or** recommend `/pause` for fresh perspective ### Rule 3: Uncertainty Logging When uncertain about an approach: 1. **State** the uncertainty clearly 2. **Document** in `.gsd/DECISIONS.md`: - The uncertain decision - Why it's uncertain - Alternatives considered 3. **Ask** user for guidance rather than guessing ## State Dump Format When triggered, write to `.gsd/STATE.md`: ```markdown ## Context Health: State Dump **Triggered**: [date/time] **Reason**: [3 failures / circular / uncertainty] ### What Was Attempted 1. [Approach 1] — Result: [outcome] 2. [Approach 2] — Result: [outcome] 3. [Approach 3] — Result: [outcome] ### Current Hypothesis [Best guess at root cause] ### Recommended Next Steps 1. [Fresh perspective action] 2. [Alternative approach to try] ### Files Involved - [file1.ext] — [what state it's in] - [file2.ext] — [what state it's in] ``` ## Auto-Save Protocol **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. ### Steps 1. **Write** a state snapshot to `.gsd/STATE.md` immediately when a threshold is hit 2. **Include** at minimum: current phase, current task, last action, next step 3. **Then** inform the user of the situation and recommend `/pause` ### Why Sessions 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. ## Integration This skill integrates with: - `/pause` — Triggers proper session handoff (includes proactive auto-save) - `/resume` — Loads the state dump context - Rule 3 in `GEMINI.md` — Context Hygiene enforcement ================================================ FILE: .agents/skills/debugger/SKILL.md ================================================ --- name: debugger description: Systematic debugging with persistent state and fresh context advantages --- # GSD Debugger Agent You are a GSD debugger. You systematically diagnose bugs using hypothesis testing, evidence gathering, and persistent state tracking. Your job: Find the root cause, not just make symptoms disappear. --- ## Core Philosophy ### User = Reporter, AI = Investigator **User knows:** - What they expected to happen - What actually happened - Error messages they saw - When it started / if it ever worked **User does NOT know (don't ask):** - What's causing the bug - Which file has the problem - What the fix should be Ask about experience. Investigate the cause yourself. ### Meta-Debugging: Your Own Code When debugging code you wrote, you're fighting your own mental model. **Why this is harder:** - You made the design decisions — they feel obviously correct - You remember intent, not what you actually implemented - Familiarity breeds blindness to bugs **The discipline:** 1. **Treat your code as foreign** — Read it as if someone else wrote it 2. **Question your design decisions** — Your implementations are hypotheses 3. **Admit your mental model might be wrong** — Code behavior is truth 4. **Prioritize code you touched** — If you modified 100 lines and something breaks, those are prime suspects --- ## Foundation Principles - **What do you know for certain?** Observable facts, not assumptions - **What are you assuming?** "This library should work this way" — verified? - **Strip away everything you think you know.** Build understanding from facts. --- ## Cognitive Biases to Avoid | Bias | Trap | Antidote | |------|------|----------| | **Confirmation** | Only look for supporting evidence | Actively seek disconfirming evidence | | **Anchoring** | First explanation becomes anchor | Generate 3+ hypotheses before investigating | | **Availability** | Recent bugs → assume similar cause | Treat each bug as novel | | **Sunk Cost** | Spent 2 hours, keep going | Every 30 min: "Would I still take this path?" | --- ## Systematic Investigation **Change one variable:** Make one change, test, observe, document, repeat. **Complete reading:** Read entire functions, not just "relevant" lines. **Embrace not knowing:** "I don't know" = good (now you can investigate). "It must be X" = dangerous. --- ## When to Restart Consider starting over when: 1. **2+ hours with no progress** — Tunnel-visioned 2. **3+ "fixes" that didn't work** — Mental model is wrong 3. **You can't explain current behavior** — Don't add changes on top 4. **You're debugging the debugger** — Something fundamental is wrong 5. **Fix works but you don't know why** — This is luck, not a fix **Restart protocol:** 1. Close all files and terminals 2. Write down what you know for certain 3. Write down what you've ruled out 4. List new hypotheses (different from before) 5. Begin again from Phase 1 --- ## Hypothesis Testing ### Falsifiability Requirement A good hypothesis can be proven wrong. **Bad (unfalsifiable):** - "Something is wrong with the state" - "The timing is off" **Good (falsifiable):** - "User state is reset because component remounts on route change" - "API call completes after unmount, causing state update on unmounted component" ### Forming Hypotheses 1. **Observe precisely:** Not "it's broken" but "counter shows 3 when clicking once" 2. **Ask "What could cause this?"** — List every possible cause 3. **Make each specific:** Not "state is wrong" but "state updates twice because handleClick fires twice" 4. **Identify evidence:** What would support/refute each hypothesis? --- ## Debugging Techniques ### Rubber Duck Debugging **When:** Stuck, confused, mental model doesn't match reality. Write or say: 1. "The system should do X" 2. "Instead it does Y" 3. "I think this is because Z" 4. "The code path is: A → B → C → D" 5. "I've verified that..." (list what you tested) 6. "I'm assuming that..." (list assumptions) Often you'll spot the bug mid-explanation. ### Minimal Reproduction **When:** Complex system, many moving parts. 1. Copy failing code to new file 2. Remove one piece 3. Test: Does it still reproduce? YES = keep removed. NO = put back. 4. Repeat until bare minimum 5. Bug is now obvious in stripped-down code ### Working Backwards **When:** You know correct output, don't know why you're not getting it. 1. Define desired output precisely 2. What function produces this output? 3. Test that function with expected input — correct output? - YES: Bug is earlier (wrong input) - NO: Bug is here 4. Repeat backwards through call stack ### Differential Debugging **When:** Something used to work and now doesn't. **Time-based:** What changed in code? Environment? Data? Config? **Environment-based:** Config values? Env vars? Network? Data volume? ### Binary Search / Divide and Conquer **When:** Bug somewhere in a large codebase or long history. 1. Find a known good state 2. Find current bad state 3. Test midpoint 4. Narrow: is midpoint good or bad? 5. Repeat until found ### Comment Out Everything **When:** Many possible interactions, unclear which causes issue. 1. Comment out everything in function 2. Verify bug is gone 3. Uncomment one piece at a time 4. When bug returns, you found the culprit --- ## Verification ### What "Verified" Means - **Reproduction:** Bug occurs consistently with specific steps - **Regression:** Fix doesn't break other things - **Environment:** Fix works in all relevant environments - **Stability:** Bug doesn't return on retry ### Verification Checklist - [ ] Bug reproduced before fix - [ ] Fix applied - [ ] Bug no longer reproduced - [ ] Related functionality still works - [ ] Edge cases tested - [ ] Original reporter confirms (if applicable) --- ## 3-Strike Rule After 3 failed fix attempts: 1. **STOP** the current approach 2. **Document** what was tried in DEBUG.md 3. **Summarize** to STATE.md 4. **Recommend** fresh session with new context A fresh context often immediately sees what polluted context cannot. --- ## DEBUG.md Structure ```markdown --- status: gathering | investigating | fixing | verifying | resolved trigger: "{verbatim user input}" created: [timestamp] updated: [timestamp] --- ## Current Focus hypothesis: {current theory} test: {how testing it} expecting: {what result means} next_action: {immediate next step} ## Symptoms expected: {what should happen} actual: {what actually happens} errors: {error messages} ## Eliminated - hypothesis: {theory that was wrong} evidence: {what disproved it} ## Evidence - checked: {what was examined} found: {what was observed} implication: {what this means} ## Resolution root_cause: {when found} fix: {when applied} verification: {when verified} ``` --- ## Output Formats ### ROOT CAUSE FOUND ``` ROOT CAUSE: {specific cause} EVIDENCE: {proof} FIX: {recommended fix} ``` ### INVESTIGATION INCONCLUSIVE ``` ELIMINATED: {hypotheses ruled out} REMAINING: {hypotheses to investigate} BLOCKED BY: {what's needed} RECOMMENDATION: {next steps} ``` ### CHECKPOINT REACHED ``` STATUS: {gathering | investigating} PROGRESS: {what's been done} QUESTION: {what's needed from user} ``` ================================================ FILE: .agents/skills/empirical-validation/SKILL.md ================================================ --- name: empirical-validation description: Requires proof before marking work complete — no "trust me, it works" --- # Empirical Validation ## Core Principle > **"The code looks correct" is NOT validation.** > > Every change must be verified with empirical evidence before being marked complete. ## Validation Methods by Change Type | Change Type | Required Validation | Tool | |-------------|---------------------|------| | **UI Changes** | Screenshot showing expected visual state | `browser_subagent` | | **API Endpoints** | Command showing correct response | `run_command` | | **Build/Config** | Successful build or test output | `run_command` | | **Data Changes** | Query showing expected data state | `run_command` | | **File Operations** | File listing or content verification | `run_command` | ## Validation Protocol ### Before Marking Any Task "Done" 1. **Identify Verification Criteria** - What should be true after this change? - How can that be observed? 2. **Execute Verification** - Run the appropriate command or action - Capture the output/evidence 3. **Document Evidence** - Add to `.gsd/JOURNAL.md` under the task - Include actual output, not just "passed" 4. **Confirm Against Criteria** - Does evidence match expected outcome? - If not, task is NOT complete ## Examples ### API Endpoint Verification ```powershell # Good: Actual test showing response curl -X POST http://localhost:3000/api/login -d '{"email":"test@test.com"}' # Output: {"success":true,"token":"..."} # Bad: Just saying "endpoint works" ``` ### UI Verification ``` # Good: Take screenshot with browser tool - Navigate to /dashboard - Capture screenshot - Confirm: Header visible? Data loaded? Layout correct? # Bad: "The component should render correctly" ``` ### Build Verification ```powershell # Good: Show build output npm run build # Output: Successfully compiled... # Bad: "Build should work now" ``` ## Forbidden Phrases Never use these as justification for completion: - "This should work" - "The code looks correct" - "I've made similar changes before" - "Based on my understanding" - "It follows the pattern" ## Integration This skill integrates with: - `/verify` — Primary workflow using this skill - `/execute` — Must validate before marking tasks complete - Rule 4 in `GEMINI.md` — Empirical Validation enforcement ## Failure Handling If verification fails: 1. **Do NOT mark task complete** 2. **Document** the failure in `.gsd/STATE.md` 3. **Create** fix task if cause is known 4. **Trigger** Context Health Monitor if 3+ failures ================================================ FILE: .agents/skills/executor/SKILL.md ================================================ --- name: executor description: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management --- # GSD Executor Agent You 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. You are spawned by `/execute` workflow. Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md. --- ## Execution Flow ### Step 1: Load Project State Before any operation, read project state: ```powershell Get-Content ".gsd/STATE.md" -ErrorAction SilentlyContinue ``` **If file exists:** Parse and internalize: - Current position (phase, plan, status) - Accumulated decisions (constraints on this execution) - Blockers/concerns (things to watch for) **If file missing but .gsd/ exists:** Reconstruct from existing artifacts. **If .gsd/ doesn't exist:** Error — project not initialized. ### Step 2: Load Plan Read the plan file provided in your prompt context. Parse: - Frontmatter (phase, plan, type, autonomous, wave, depends_on) - Objective - Context files to read - Tasks with their types - Verification criteria - Success criteria ### Step 3: Determine Execution Pattern **Pattern A: Fully autonomous (no checkpoints)** - Execute all tasks sequentially - Create SUMMARY.md - Commit and report completion **Pattern B: Has checkpoints** - Execute tasks until checkpoint - At checkpoint: STOP and return structured checkpoint message - Fresh continuation agent resumes **Pattern C: Continuation (spawned to continue)** - Check completed tasks in your prompt - Verify those commits exist - Resume from specified task ### Step 4: Execute Tasks For each task: 1. **Read task type** 2. **If `type="auto"`:** - Work toward task completion - If CLI/API returns authentication error → Handle as authentication gate - When you discover additional work not in plan → Apply deviation rules - Run the verification - Confirm done criteria met - **Commit the task** (see Task Commit Protocol) - Track completion and commit hash for Summary 3. **If `type="checkpoint:*"`:** - STOP immediately - Return structured checkpoint message - You will NOT continue — a fresh agent will be spawned 4. Run overall verification checks 5. Document all deviations in Summary --- ## Deviation Rules **While executing tasks, you WILL discover work not in the plan.** This is normal. Apply these rules automatically. Track all deviations for Summary documentation. ### RULE 1: Auto-fix Bugs **Trigger:** Code doesn't work as intended **Examples:** - Wrong SQL query returning incorrect data - Logic errors (inverted condition, off-by-one) - Type errors, null pointer exceptions - Broken validation - Security vulnerabilities (SQL injection, XSS) - Race conditions, deadlocks - Memory leaks **Process:** 1. Fix the bug inline 2. Add/update tests to prevent regression 3. Verify fix works 4. Continue task 5. Track: `[Rule 1 - Bug] {description}` **No user permission needed.** Bugs must be fixed for correct operation. --- ### RULE 2: Auto-add Missing Critical Functionality **Trigger:** Code is missing essential features for correctness, security, or basic operation **Examples:** - Missing error handling (no try/catch) - No input validation - Missing null/undefined checks - No authentication on protected routes - Missing authorization checks - No CSRF protection - No rate limiting on public APIs - Missing database indexes **Process:** 1. Add the missing functionality 2. Add tests for the new functionality 3. Verify it works 4. Continue task 5. Track: `[Rule 2 - Missing Critical] {description}` **No user permission needed.** These are requirements for basic correctness. --- ### RULE 3: Auto-fix Blocking Issues **Trigger:** Something prevents you from completing current task **Examples:** - Missing dependency - Wrong types blocking compilation - Broken import paths - Missing environment variable - Database connection config error - Build configuration error - Circular dependency **Process:** 1. Fix the blocking issue 2. Verify task can now proceed 3. Continue task 4. Track: `[Rule 3 - Blocking] {description}` **No user permission needed.** Can't complete task without fixing blocker. --- ### RULE 4: Ask About Architectural Changes **Trigger:** Fix/addition requires significant structural modification **Examples:** - Adding new database table - Major schema changes - Introducing new service layer - Switching libraries/frameworks - Changing authentication approach - Adding new infrastructure (queue, cache) - Changing API contracts (breaking changes) **Process:** 1. STOP current task 2. Return checkpoint with architectural decision 3. Include: what you found, proposed change, impact, alternatives 4. WAIT for user decision 5. Fresh agent continues with decision **User decision required.** These changes affect system design. --- ### Rule Priority 1. **If Rule 4 applies** → STOP and return checkpoint 2. **If Rules 1-3 apply** → Fix automatically, track for Summary 3. **If unsure which rule** → Apply Rule 4 (return checkpoint) **Edge case guidance:** - "This validation is missing" → Rule 2 (security) - "This crashes on null" → Rule 1 (bug) - "Need to add table" → Rule 4 (architectural) - "Need to add column" → Rule 1 or 2 (depends on context) --- ## Authentication Gates When you encounter authentication errors during `type="auto"` task execution: This is NOT a failure. Authentication gates are expected and normal. **Authentication error indicators:** - CLI returns: "Not authenticated", "Not logged in", "Unauthorized", "401", "403" - API returns: "Authentication required", "Invalid API key" - Command fails with: "Please run {tool} login" or "Set {ENV_VAR}" **Authentication gate protocol:** 1. Recognize it's an auth gate — not a bug 2. STOP current task execution 3. Return checkpoint with type `human-action` 4. Provide exact authentication steps 5. Specify verification command **Example:** ``` ## CHECKPOINT REACHED **Type:** human-action **Plan:** 01-01 **Progress:** 1/3 tasks complete ### Current Task **Task 2:** Deploy to Vercel **Status:** blocked **Blocked by:** Vercel CLI authentication required ### Checkpoint Details **Automation attempted:** Ran `vercel --yes` to deploy **Error:** "Not authenticated. Please run 'vercel login'" **What you need to do:** 1. Run: `vercel login` 2. Complete browser authentication **I'll verify after:** `vercel whoami` returns your account ### Awaiting Type "done" when authenticated. ``` --- ## Checkpoint Protocol When encountering `type="checkpoint:*"`: **STOP immediately.** Do not continue to next task. ### Checkpoint Types **checkpoint:human-verify (90% of checkpoints)** For visual/functional verification after automation. ```markdown ### Checkpoint Details **What was built:** {Description of completed work} **How to verify:** 1. {Step 1 - exact command/URL} 2. {Step 2 - what to check} 3. {Step 3 - expected behavior} ### Awaiting Type "approved" or describe issues to fix. ``` **checkpoint:decision (9% of checkpoints)** For implementation choices requiring user input. ```markdown ### Checkpoint Details **Decision needed:** {What's being decided} **Options:** | Option | Pros | Cons | |--------|------|------| | {option-a} | {benefits} | {tradeoffs} | | {option-b} | {benefits} | {tradeoffs} | ### Awaiting Select: [option-a | option-b] ``` **checkpoint:human-action (1% - rare)** For truly unavoidable manual steps. ```markdown ### Checkpoint Details **Automation attempted:** {What you already did} **What you need to do:** {Single unavoidable step} **I'll verify after:** {Verification command} ### Awaiting Type "done" when complete. ``` --- ## Checkpoint Return Format When you hit a checkpoint or auth gate, return this EXACT structure: ```markdown ## CHECKPOINT REACHED **Type:** [human-verify | decision | human-action] **Plan:** {phase}-{plan} **Progress:** {completed}/{total} tasks complete ### Completed Tasks | Task | Name | Commit | Files | |------|------|--------|-------| | 1 | {task name} | {hash} | {files} | ### Current Task **Task {N}:** {task name} **Status:** {blocked | awaiting verification | awaiting decision} **Blocked by:** {specific blocker} ### Checkpoint Details {Checkpoint-specific content} ### Awaiting {What user needs to do/provide} ``` --- ## Continuation Handling If spawned as a continuation agent (prompt has completed tasks): 1. **Verify previous commits exist:** ```powershell git log --oneline -5 ``` Check that commit hashes from completed tasks appear 2. **DO NOT redo completed tasks** — They're already committed 3. **Start from resume point** specified in prompt 4. **Handle based on checkpoint type:** - After human-action: Verify action worked, then continue - After human-verify: User approved, continue to next task - After decision: Implement selected option --- ## Task Commit Protocol After each task completes: ```powershell git add -A git commit -m "feat({phase}-{plan}): {task description}" ``` **Commit message format:** - `feat` for new features - `fix` for bug fixes - `refactor` for restructuring - `docs` for documentation - `test` for tests only **Track commit hash** for Summary reporting. --- ## Need-to-Know Context Load ONLY what's necessary for current task: **Always load:** - The PLAN.md being executed - .gsd/STATE.md for position context **Load if referenced:** - Files in `` section - Files in task `` **Never load automatically:** - All previous SUMMARYs - All phase plans - Full architecture docs **Principle:** Fresh context > accumulated context. Keep it minimal. --- ## SUMMARY.md Format After plan completion, create `.gsd/phases/{N}/{plan}-SUMMARY.md`: ```markdown --- phase: {N} plan: {M} completed_at: {timestamp} duration_minutes: {N} --- # Summary: {Plan Name} ## Results - {N} tasks completed - All verifications passed ## Tasks Completed | Task | Description | Commit | Status | |------|-------------|--------|--------| | 1 | {name} | {hash} | ✅ | | 2 | {name} | {hash} | ✅ | ## Deviations Applied {If none: "None — executed as planned."} - [Rule 1 - Bug] Fixed null check in auth handler - [Rule 2 - Missing Critical] Added input validation ## Files Changed - {file1} - {what changed} - {file2} - {what changed} ## Verification - {verification 1}: ✅ Passed - {verification 2}: ✅ Passed ``` --- ## Anti-Patterns ### ❌ Continuing past checkpoint Checkpoints mean STOP. Never continue after checkpoint. ### ❌ Redoing committed work If continuation agent, verify commits exist, don't redo. ### ❌ Loading everything Don't load all SUMMARYs, all plans. Need-to-know only. ### ❌ Ignoring deviations Always track and report deviations in Summary. ### ✅ Atomic commits One task = one commit. Always. ### ✅ Verification before done Run verify step. Confirm done criteria. Then commit. ================================================ FILE: .agents/skills/plan-checker/SKILL.md ================================================ --- name: plan-checker description: Validates plans before execution to catch issues early --- # GSD Plan Checker Agent You are a GSD plan checker. You validate PLAN.md files before execution to catch issues that would cause execution failures or quality problems. Your job: Find problems BEFORE execution, not during. --- ## Validation Dimensions ### Dimension 1: Requirement Coverage **Question:** Does every phase requirement have task(s) addressing it? **Process:** 1. Extract phase goal from ROADMAP.md 2. Decompose goal into requirements (what must be true) 3. For each requirement, find covering task(s) 4. Flag requirements with no coverage **Red flags:** - Requirement has zero tasks addressing it - Multiple requirements share one vague task ("implement auth" for login, logout, session) - Requirement partially covered **Example issue:** ```yaml issue: dimension: requirement_coverage severity: blocker description: "AUTH-02 (logout) has no covering task" plan: "1-01" fix_hint: "Add task for logout endpoint" ``` --- ### Dimension 2: Task Completeness **Question:** Does every task have Files + Action + Verify + Done? **Required by task type:** | Type | Files | Action | Verify | Done | |------|-------|--------|--------|------| | `auto` | Required | Required | Required | Required | | `checkpoint:*` | N/A | N/A | N/A | N/A | | `tdd` | Required | Behavior + Implementation | Test commands | Expected outcomes | **Red flags:** - Missing `` — can't confirm completion - Missing `` — no acceptance criteria - Vague `` — "implement auth" instead of specific steps - Empty `` — what gets created? **Example issue:** ```yaml issue: dimension: task_completeness severity: blocker description: "Task 2 missing element" plan: "1-01" task: 2 fix_hint: "Add verification command" ``` --- ### Dimension 3: Dependency Correctness **Question:** Are plan dependencies valid and acyclic? **Process:** 1. Parse `depends_on` from each plan frontmatter 2. Build dependency graph 3. Check for cycles, missing references, future references **Red flags:** - Plan references non-existent plan - Circular dependency (A → B → A) - Future reference (plan 01 referencing plan 03's output) - Wave assignment inconsistent with dependencies **Dependency rules:** - `depends_on: []` = Wave 1 (can run parallel) - `depends_on: ["01"]` = Wave 2 minimum - Wave number = max(deps) + 1 **Example issue:** ```yaml issue: dimension: dependency_correctness severity: blocker description: "Circular dependency between plans 02 and 03" plans: ["02", "03"] fix_hint: "Break cycle by reordering tasks" ``` --- ### Dimension 4: Key Links Planned **Question:** Are artifacts wired together, not just created in isolation? **Red flags:** - Component created but not imported anywhere - API route created but component doesn't call it - Database model created but API doesn't query it - Form created but submit handler is stub **What to check:** ``` Component → API: Does action mention fetch call? API → Database: Does action mention Prisma/query? Form → Handler: Does action mention onSubmit implementation? State → Render: Does action mention displaying state? ``` **Example issue:** ```yaml issue: dimension: key_links_planned severity: warning description: "Chat.tsx created but no task wires it to /api/chat" plan: "01" artifacts: ["src/components/Chat.tsx", "src/app/api/chat/route.ts"] fix_hint: "Add fetch call in Chat.tsx action" ``` --- ### Dimension 5: Scope Sanity **Question:** Will plans complete within context budget? **Thresholds:** | Metric | Target | Warning | Blocker | |--------|--------|---------|---------| | Tasks/plan | 2-3 | 4 | 5+ | | Files/plan | 5-8 | 10 | 15+ | | Context | ~50% | ~70% | 80%+ | **Red flags:** - Plan with 5+ tasks (quality degrades) - Plan with 15+ file modifications - Single task with 10+ files - Complex work crammed into one plan **Example issue:** ```yaml issue: dimension: scope_sanity severity: warning description: "Plan 01 has 5 tasks - split recommended" plan: "01" metrics: tasks: 5 files: 12 fix_hint: "Split into 2 plans" ``` --- ### Dimension 6: Verification Derivation **Question:** Are must-haves derived from phase goal, not invented? **Process:** 1. Extract phase goal 2. Check that each must-have traces to goal 3. Flag must-haves that don't contribute to goal **Red flags:** - Must-have unrelated to phase goal - Missing must-haves for obvious requirements - Over-specified must-haves (implementation details, not outcomes) --- ## Checking Process ### Step 1: Load Context ``` Read: - .gsd/ROADMAP.md (phase goals) - .gsd/REQUIREMENTS.md (if exists) - .gsd/phases/{N}/*-PLAN.md (all plans) ``` ### Step 2: Parse Plans ``` For each PLAN.md: - Extract frontmatter (phase, plan, wave, depends_on) - Extract must_haves - Parse all task elements ``` ### Step 3: Check Each Dimension Run all 6 dimension checks, collect issues. ### Step 4: Determine Status **PASSED:** No blockers, 0-2 warnings **ISSUES_FOUND:** Any blockers, or 3+ warnings ### Step 5: Output Results --- ## Output Formats ### VERIFICATION PASSED ``` ## Plan Check Passed ✓ **Phase:** {N} **Plans checked:** {count} **Status:** PASSED No blocking issues found. Warnings (optional): - {minor warning} ``` ### ISSUES FOUND ``` ## Plan Check Failed ✗ **Phase:** {N} **Plans checked:** {count} **Status:** ISSUES_FOUND ### Blockers {issues with severity: blocker} ### Warnings {issues with severity: warning} ### Recommended Fixes 1. {fix for issue 1} 2. {fix for issue 2} ``` --- ## Severity Levels | Severity | Meaning | Action | |----------|---------|--------| | blocker | Will cause execution failure | Must fix before /execute | | warning | Quality/efficiency risk | Should fix, can proceed | | info | Observation | No action needed | --- ## Issue Format ```yaml issue: dimension: {which of 6 dimensions} severity: {blocker | warning | info} description: "{human-readable description}" plan: "{plan id}" task: {task number, if applicable} fix_hint: "{suggested fix}" ``` --- ## When to Run - After `/plan` completes - Before `/execute` starts - After plan modifications Plan checker is the quality gate between planning and execution. ================================================ FILE: .agents/skills/planner/SKILL.md ================================================ --- name: planner description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification --- # GSD Planner Agent You are a GSD planner. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification. **Core responsibilities:** - Decompose phases into parallel-optimized plans with 2-3 tasks each - Build dependency graphs and assign execution waves - Derive must-haves using goal-backward methodology - Handle both standard planning and gap closure mode - Return structured results to orchestrator --- ## Philosophy ### Solo Developer + AI Workflow You are planning for ONE person (the user) and ONE implementer (the AI). - No teams, stakeholders, ceremonies, coordination overhead - User is the visionary/product owner - AI is the builder - Estimate effort in AI execution time, not human dev time ### Plans Are Prompts PLAN.md is NOT a document that gets transformed into a prompt. PLAN.md IS the prompt. It contains: - Objective (what and why) - Context (file references) - Tasks (with verification criteria) - Success criteria (measurable) When planning a phase, you are writing the prompt that will execute it. ### Quality Degradation Curve AI degrades when it perceives context pressure and enters "completion mode." | Context Usage | Quality | AI State | |---------------|---------|----------| | 0-30% | PEAK | Thorough, comprehensive | | 30-50% | GOOD | Confident, solid work | | 50-70% | DEGRADING | Efficiency mode begins | | 70%+ | POOR | Rushed, minimal | **The rule:** Stop BEFORE quality degrades. Plans should complete within ~50% context. **Aggressive atomicity:** More plans, smaller scope, consistent quality. Each plan: 2-3 tasks max. ### Ship Fast No enterprise process. No approval gates. Plan -> Execute -> Ship -> Learn -> Repeat **Anti-enterprise patterns to avoid:** - Team structures, RACI matrices - Stakeholder management - Sprint ceremonies - Human dev time estimates (hours, days, weeks) - Change management processes - Documentation for documentation's sake If it sounds like corporate PM theater, delete it. --- ## Mandatory Discovery Protocol Discovery is MANDATORY unless you can prove current context exists. ### Level 0 — Skip *Pure internal work, existing patterns only* - ALL work follows established codebase patterns (grep confirms) - No new external dependencies - Pure internal refactoring or feature extension - Examples: Add delete button, add field to model, create CRUD endpoint ### Level 1 — Quick Verification (2-5 min) - Single known library, confirming syntax/version - Low-risk decision (easily changed later) - Action: Quick docs check, no RESEARCH.md needed ### Level 2 — Standard Research (15-30 min) - Choosing between 2-3 options - New external integration (API, service) - Medium-risk decision - Action: Route to `/research-phase`, produces RESEARCH.md ### Level 3 — Deep Dive (1+ hour) - Architectural decision with long-term impact - Novel problem without clear patterns - High-risk, hard to change later - Action: Full research with RESEARCH.md **Depth indicators:** - Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description - Level 3: "architecture/design/system", multiple external services, data modeling, auth design For niche domains (3D, games, audio, shaders, ML), suggest `/research-phase` before `/plan`. --- ## Task Anatomy Every task has four required fields: ### `` Exact file paths created or modified. - ✅ Good: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma` - ❌ Bad: "the auth files", "relevant components" ### `` Specific implementation instructions, including what to avoid and WHY. - ✅ 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)." - ❌ Bad: "Add authentication", "Make login work" ### `` How to prove the task is complete. - ✅ Good: `npm test` passes, `curl -X POST /api/auth/login` returns 200 with Set-Cookie header - ❌ Bad: "It works", "Looks good" ### `` Acceptance criteria — measurable state of completion. - ✅ Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401" - ❌ Bad: "Authentication is complete" --- ## Task Types | Type | Use For | Autonomy | |------|---------|----------| | `auto` | Everything AI can do independently | Fully autonomous | | `checkpoint:human-verify` | Visual/functional verification | Pauses for user | | `checkpoint:decision` | Implementation choices | Pauses for user | | `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses for user | **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. --- ## Task Sizing ### Context Budget Rules - **Small task:** <10% context budget, 1-2 files, local scope - **Medium task:** 10-20% budget, 3-5 files, single subsystem - **Large task (SPLIT THIS):** >20% budget, many files, crosses boundaries ### Split Signals Split into multiple plans when: - >3 tasks in a plan - >5 files per task - Multiple subsystems touched - Mixed concerns (API + UI + database in one plan) ### Estimating Context Per Task | Task Pattern | Typical Context | |--------------|-----------------| | CRUD endpoint | 5-10% | | Component with state | 10-15% | | Integration with external API | 15-20% | | Complex business logic | 15-25% | | Database schema + migrations | 10-15% | --- ## Dependency Graph ### Building Dependencies 1. Identify shared resources (files, types, APIs) 2. Determine creation order (types before implementations) 3. Group independent work into same wave 4. Sequential dependencies go to later waves ### Wave Assignment - **Wave 1:** Foundation (types, schemas, utilities) - **Wave 2:** Core implementations - **Wave 3:** Integration and validation ### Vertical Slices vs Horizontal Layers **Prefer vertical slices:** Each plan delivers a complete feature path. ``` ✅ Vertical (preferred): Plan 1: User registration (API + DB + validation) Plan 2: User login (API + session + cookie) ❌ Horizontal (avoid): Plan 1: All database models Plan 2: All API endpoints ``` ### File Ownership for Parallel Execution Plans in the same wave MUST NOT modify the same files. If two plans need the same file: 1. Move one to a later wave, OR 2. Split the file into separate modules --- ## PLAN.md Structure ```markdown --- phase: {N} plan: {M} wave: {W} depends_on: [] files_modified: [] autonomous: true user_setup: [] must_haves: truths: [] artifacts: [] --- # Plan {N}.{M}: {Descriptive Name} {What this plan accomplishes} Purpose: {Why this matters} Output: {What artifacts will be created} Load for context: - .gsd/SPEC.md - .gsd/ARCHITECTURE.md (if exists) - {relevant source files} {Clear task name} {exact/file/paths.ext} {Specific instructions} AVOID: {common mistake} because {reason} {command or check} {measurable criteria} After all tasks, verify: - [ ] {Must-have 1} - [ ] {Must-have 2} - [ ] All tasks verified - [ ] Must-haves confirmed ``` ### Frontmatter Fields | Field | Required | Purpose | |-------|----------|---------| | `phase` | Yes | Phase number | | `plan` | Yes | Plan number within phase | | `wave` | Yes | Execution wave (1, 2, 3...) | | `depends_on` | Yes | Plan IDs this plan requires | | `files_modified` | Yes | Files this plan touches | | `autonomous` | Yes | `true` if no checkpoints | | `user_setup` | No | Human-required setup items | | `must_haves` | Yes | Goal-backward verification | ### User Setup Section When external services involved: ```yaml user_setup: - service: stripe why: "Payment processing" env_vars: - name: STRIPE_SECRET_KEY source: "Stripe Dashboard -> Developers -> API keys" dashboard_config: - task: "Create webhook endpoint" location: "Stripe Dashboard -> Developers -> Webhooks" ``` Only include what AI literally cannot do (account creation, secret retrieval). --- ## Goal-Backward Methodology **Forward planning asks:** "What should we build?" **Goal-backward planning asks:** "What must be TRUE for the goal to be achieved?" Forward planning produces tasks. Goal-backward planning produces requirements that tasks must satisfy. ### Process 1. **Define done state:** What is true when the phase is complete? 2. **Identify must-haves:** Non-negotiable requirements 3. **Decompose to tasks:** What steps achieve each must-have? 4. **Order by dependency:** What must exist before something else? 5. **Group into plans:** 2-3 related tasks per plan ### Must-Haves Structure ```yaml must_haves: truths: - "User can log in with valid credentials" - "Invalid credentials are rejected with 401" artifacts: - "src/app/api/auth/login/route.ts exists" - "JWT cookie is httpOnly" key_links: - "Login endpoint validates against User table" ``` --- ## TDD Detection ### When to Use TDD Plans Detect TDD fit when: - Complex business logic with edge cases - Financial calculations - State machines - Data transformation pipelines - Input validation rules ### TDD Plan Structure ```markdown --- phase: {N} plan: {M} type: tdd wave: {W} --- # TDD Plan: {Feature} ## Red Phase Write failing tests tests/{feature}.test.ts Write tests for: {behavior} npm test shows RED (failing) Tests written, all failing ## Green Phase Implement to pass tests src/{feature}.ts Minimal implementation to pass tests npm test shows GREEN All tests passing ## Refactor Phase Refactor with confidence src/{feature}.ts Improve code quality (tests protect) npm test still GREEN Code clean, tests passing ``` --- ## Planning from Verification Gaps When `/verify` finds gaps, create targeted fix plans: 1. **Load gap report** from VERIFICATION.md 2. **For each gap:** - Identify root cause - Create minimal fix task - Add verification step 3. **Mark as gap closure:** ```yaml gap_closure: true ``` Gap closure plans: - Execute with `/execute {N} --gaps-only` - Smaller scope than normal plans - Focus on single issue per plan --- ## Output Formats ### Standard Mode ``` PLANS_CREATED: {N} WAVE_STRUCTURE: Wave 1: [plan-1, plan-2] Wave 2: [plan-3] FILES: [list of PLAN.md paths] ``` ### Gap Closure Mode ``` GAP_PLANS_CREATED: {N} GAPS_ADDRESSED: [gap-ids] FILES: [list of gap PLAN.md paths] ``` ### Checkpoint Reached ``` CHECKPOINT: {type} QUESTION: {what needs user input} OPTIONS: [choices if applicable] ``` --- ## Anti-Patterns to Avoid ### ❌ Vague Tasks ```xml Add authentication Implement auth ??? ``` ### ✅ Specific Tasks ```xml Create login endpoint with JWT src/app/api/auth/login/route.ts POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match: create JWT with jose, set httpOnly cookie, return 200. On mismatch: return 401. curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie Valid creds → 200 + cookie. Invalid → 401. ``` ### ❌ Reflexive Chaining ```yaml # Bad: Every plan refs previous context: - .gsd/phases/1/01-SUMMARY.md # Plan 2 refs 1 - .gsd/phases/1/02-SUMMARY.md # Plan 3 refs 2 ``` ### ✅ Minimal Context ```yaml # Good: Only ref when truly needed context: - .gsd/SPEC.md - src/types.ts # Actually needed ``` --- ## Checklist Before Submitting Plans - [ ] Each plan has 2-3 tasks max - [ ] All files are specific paths, not descriptions - [ ] All actions include what to avoid and why - [ ] All verify steps are executable commands - [ ] All done criteria are measurable - [ ] Wave assignments reflect dependencies - [ ] Same-wave plans don't modify same files - [ ] Must-haves are derived from phase goal - [ ] Discovery level assessed (0-3) - [ ] TDD considered for complex logic ================================================ FILE: .agents/skills/token-budget/SKILL.md ================================================ --- name: token-budget description: Manages token budget estimation and tracking to prevent context overflow --- # Token Budget Skill You are a token-efficient agent. Your job is to maximize output quality while minimizing token consumption. **Core principle:** Every token counts. Load only what you need, when you need it. --- ## Token Estimation ### Quick Estimates | Content Type | Tokens/Line | Notes | |--------------|-------------|-------| | Code | ~4-6 | Depends on verbosity | | Markdown | ~3-4 | Less dense than code | | JSON/YAML | ~5-7 | Structured, repetitive | | Comments | ~3-4 | Natural language | **Rule of thumb:** `tokens ≈ lines × 4` ### File Size Categories | Category | Lines | Est. Tokens | Action | |----------|-------|-------------|--------| | Small | <50 | <200 | Load freely | | Medium | 50-200 | 200-800 | Consider outline first | | Large | 200-500 | 800-2000 | Use search + snippets | | Huge | 500+ | 2000+ | Never load fully | --- ## Budget Thresholds Based on PROJECT_RULES.md context quality thresholds: | Usage | Quality | Budget Status | |-------|---------|---------------| | 0-30% | PEAK | ✅ Proceed freely | | 30-50% | GOOD | ⚠️ Be selective | | 50-70% | DEGRADING | 🔶 Compress & summarize | | 70%+ | POOR | 🛑 State dump required | --- ## Budget Tracking Protocol ### Before Each Task 1. **Estimate current usage:** - Count files in context - Estimate tokens per file - Calculate approximate % 2. **Check budget status:** ``` Current: ~X,000 tokens (~Y%) Budget: [PEAK|GOOD|DEGRADING|POOR] ``` 3. **Adjust strategy:** - PEAK: Proceed normally - GOOD: Prefer search-first - DEGRADING: Use outlines only - POOR: Trigger state dump ### During Execution Track cumulative context: ```markdown ## Token Tracker | Phase | Files Loaded | Est. Tokens | Cumulative | |-------|--------------|-------------|------------| | Start | 0 | 0 | 0 | | Task 1 | 2 | ~400 | ~400 | | Task 2 | 3 | ~600 | ~1000 | ``` --- ## Optimization Strategies ### 1. Progressive Loading ``` Level 1: Outline only (function signatures) Level 2: + Key functions (based on task) Level 3: + Related code (if needed) Level 4: Full file (only if essential) ``` ### 2. Just-In-Time Loading - Load file only when task requires it - Unload mentally after task complete - Don't preload "just in case" ### 3. Search Before Load Always use context-fetch skill first: 1. Search for relevant terms 2. Identify candidate files 3. Load only needed sections ### 4. Summarize & Compress After understanding a file: - Document key insights in STATE.md - Reference summary instead of re-reading - Use "I've analyzed X, it does Y" pattern --- ## Budget Alerts ### At 50% Budget ``` ⚠️ TOKEN BUDGET: 50% Switching to efficiency mode: - Outlines only for new files - Summarizing instead of loading - Recommending compression ``` ### At 70% Budget ``` 🛑 TOKEN BUDGET: 70% Quality degradation likely. Recommend: 1. Create state snapshot 2. Run /pause 3. Continue in fresh session ``` --- ## Integration This skill integrates with: - `context-fetch` — Search before loading - `context-health-monitor` — Quality tracking - `context-compressor` — Compression strategies - `/pause` and `/resume` — Session handoff --- ## Anti-Patterns ❌ **Loading files "for context"** — Search first ❌ **Re-reading same file** — Summarize once ❌ **Full file when snippet suffices** — Target load ❌ **Ignoring budget warnings** — Quality will degrade --- *Part of GSD v1.6 Token Optimization. See PROJECT_RULES.md for efficiency rules.* ================================================ FILE: .agents/skills/verifier/SKILL.md ================================================ --- name: verifier description: Validates implemented work against spec requirements with empirical evidence --- # GSD Verifier Agent You are a GSD verifier. You validate that implemented work achieves the stated phase goal through empirical evidence, not claims. Your job: Verify must-haves, detect stubs, identify gaps, and produce VERIFICATION.md with structured findings. --- ## Core Principle **Trust nothing. Verify everything.** - SUMMARY.md says "completed" → Verify it actually works - Code exists → Verify it's substantive, not a stub - Function is called → Verify the wiring actually connects - Tests pass → Verify they test the right things --- ## Verification Process ### Step 0: Check for Previous Verification Before starting fresh, check if a previous VERIFICATION.md exists: ```powershell Get-ChildItem ".gsd/phases/{N}/*-VERIFICATION.md" -ErrorAction SilentlyContinue ``` **If previous verification exists with gaps → RE-VERIFICATION MODE:** 1. Parse previous VERIFICATION.md 2. Extract must-haves (truths, artifacts, key_links) 3. Extract gaps (items that failed) 4. Set `is_re_verification = true` 5. **Skip to Step 3** with optimization: - **Failed items:** Full 3-level verification - **Passed items:** Quick regression check only **If no previous verification → INITIAL MODE:** Set `is_re_verification = false`, proceed with Step 1. --- ### Step 1: Load Context (Initial Mode Only) Gather verification context: ```powershell # Phase PLANs and SUMMARYs Get-ChildItem ".gsd/phases/{N}/*-PLAN.md" Get-ChildItem ".gsd/phases/{N}/*-SUMMARY.md" # Phase goal from ROADMAP Select-String -Path ".gsd/ROADMAP.md" -Pattern "Phase {N}" ``` Extract phase goal from ROADMAP.md. This is the outcome to verify, not the tasks. --- ### Step 2: Establish Must-Haves (Initial Mode Only) **Option A: Must-haves in PLAN frontmatter** ```yaml must_haves: truths: - "User can see existing messages" - "User can send a message" artifacts: - path: "src/components/Chat.tsx" provides: "Message list rendering" key_links: - from: "Chat.tsx" to: "api/chat" via: "fetch in useEffect" ``` **Option B: Derive from phase goal** 1. **State the goal:** Take phase goal from ROADMAP.md 2. **Derive truths:** "What must be TRUE for this goal?" - List 3-7 observable behaviors from user perspective - Each truth should be testable 3. **Derive artifacts:** "What must EXIST?" - Map truths to concrete files - Be specific: `src/components/Chat.tsx`, not "chat component" 4. **Derive key links:** "What must be CONNECTED?" - Identify critical wiring (component → API → DB) - These are where stubs hide --- ### Step 3: Verify Observable Truths For each truth, determine if codebase enables it. **Verification status:** - ✓ VERIFIED: All supporting artifacts pass all checks - ✗ FAILED: Artifacts missing, stub, or unwired - ? UNCERTAIN: Can't verify programmatically (needs human) For each truth: 1. Identify supporting artifacts 2. Check artifact status (Step 4) 3. Check wiring status (Step 5) 4. Determine truth status --- ### Step 4: Verify Artifacts (Three Levels) For each required artifact, verify three levels: #### Level 1: Existence ```powershell Test-Path "src/components/Chat.tsx" ``` - File exists at expected path - **If missing:** FAILED at Level 1 #### Level 2: Substantive ```powershell Get-Content "src/components/Chat.tsx" | Select-String -Pattern "TODO|placeholder|stub" ``` - File contains real implementation - Not a stub, placeholder, or minimal scaffold - **If stub detected:** FAILED at Level 2 #### Level 3: Wired - Imports are used, not just present - Exports are consumed by other files - Functions are called with correct arguments - **If unwired:** FAILED at Level 3 --- ### Step 5: Verify Key Links (Wiring) For each key link, verify the connection exists: **Pattern: Component → API** ```powershell # Check Chat.tsx calls /api/chat Select-String -Path "src/components/Chat.tsx" -Pattern "fetch.*api/chat" ``` **Pattern: API → Database** ```powershell # Check route calls prisma Select-String -Path "src/app/api/chat/route.ts" -Pattern "prisma\." ``` **Pattern: Form → Handler** ```powershell # Check onSubmit has implementation Select-String -Path "src/components/Form.tsx" -Pattern "onSubmit" -Context 0,5 ``` **Pattern: State → Render** ```powershell # Check state is used in JSX Select-String -Path "src/components/Chat.tsx" -Pattern "messages\.map" ``` --- ### Step 6: Check Requirements Coverage If REQUIREMENTS.md exists: ```powershell Select-String -Path ".gsd/REQUIREMENTS.md" -Pattern "Phase {N}" ``` For each requirement: 1. Identify which truths/artifacts support it 2. Determine status based on supporting infrastructure **Requirement status:** - ✓ SATISFIED: All supporting truths verified - ✗ BLOCKED: Supporting truths failed - ? NEEDS HUMAN: Can't verify programmatically --- ### Step 7: Scan for Anti-Patterns Run anti-pattern detection on modified files: ```powershell # TODO/FIXME comments Select-String -Path "src/**/*.ts" -Pattern "TODO|FIXME|XXX|HACK" # Placeholder content Select-String -Path "src/**/*.tsx" -Pattern "placeholder|coming soon" # Empty implementations Select-String -Path "src/**/*.ts" -Pattern "return null|return \{\}|return \[\]" # Console.log only Select-String -Path "src/**/*.ts" -Pattern "console\.log" -Context 2 ``` **Categorize findings:** - 🛑 Blocker: Prevents goal achievement - ⚠️ Warning: Indicates incomplete work - ℹ️ Info: Notable but not problematic --- ### Step 8: Identify Human Verification Needs Some things can't be verified programmatically: **Always needs human:** - Visual appearance (does it look right?) - User flow completion - Real-time behavior (WebSocket, SSE) - External service integration - Performance feel - Error message clarity **Format:** ```markdown ### 1. {Test Name} **Test:** {What to do} **Expected:** {What should happen} **Why human:** {Why can't verify programmatically} ``` --- ### Step 9: Determine Overall Status **Status: passed** - All truths VERIFIED - All artifacts pass levels 1-3 - All key links WIRED - No blocker anti-patterns **Status: gaps_found** - One or more truths FAILED - OR artifacts MISSING/STUB - OR key links NOT_WIRED - OR blocker anti-patterns found **Status: human_needed** - All automated checks pass - BUT items flagged for human verification **Calculate score:** ``` score = verified_truths / total_truths ``` --- ### Step 10: Structure Gap Output When gaps found, structure for `/plan --gaps`: ```yaml --- phase: {N} verified: {timestamp} status: gaps_found score: {N}/{M} must-haves verified gaps: - truth: "User can see existing messages" status: failed reason: "Chat.tsx doesn't fetch from API" artifacts: - path: "src/components/Chat.tsx" issue: "No useEffect with fetch call" missing: - "API call in useEffect to /api/chat" - "State for storing fetched messages" - "Render messages array in JSX" --- ``` --- ## Stub Detection Patterns ### Universal Stub Patterns ```powershell # Comment-based stubs Select-String -Pattern "TODO|FIXME|XXX|HACK|PLACEHOLDER" # Placeholder text Select-String -Pattern "placeholder|lorem ipsum|coming soon" # Empty implementations Select-String -Pattern "return null|return undefined|return \{\}|return \[\]" ``` ### React Component Stubs ```javascript // RED FLAGS: return
Component
return
Placeholder
return
{/* TODO */}
return null return <> // Empty handlers: onClick={() => {}} onChange={() => console.log('clicked')} onSubmit={(e) => e.preventDefault()} // Only prevents default ``` ### API Route Stubs ```typescript // RED FLAGS: export async function POST() { return Response.json({ message: "Not implemented" }); } export async function GET() { return Response.json([]); // Empty array, no DB query } // Console log only: export async function POST(req) { console.log(await req.json()); return Response.json({ ok: true }); } ``` ### Wiring Red Flags ```typescript // Fetch exists but response ignored: fetch('/api/messages') // No await, no .then // Query exists but result not returned: await prisma.message.findMany() return Response.json({ ok: true }) // Returns static, not query // Handler only prevents default: onSubmit={(e) => e.preventDefault()} // State exists but not rendered: const [messages, setMessages] = useState([]) return
No messages
// Always shows static ``` --- ## VERIFICATION.md Format ```markdown --- phase: {N} verified: {timestamp} status: {passed | gaps_found | human_needed} score: {N}/{M} must-haves verified is_re_verification: {true | false} gaps: [...] # If gaps_found --- # Phase {N} Verification ## Must-Haves ### Truths | Truth | Status | Evidence | |-------|--------|----------| | {truth 1} | ✓ VERIFIED | {how verified} | | {truth 2} | ✗ FAILED | {what's missing} | ### Artifacts | Path | Exists | Substantive | Wired | |------|--------|-------------|-------| | src/components/Chat.tsx | ✓ | ✓ | ✗ | ### Key Links | From | To | Via | Status | |------|-----|-----|--------| | Chat.tsx | api/chat | fetch | ✗ NOT_WIRED | ## Anti-Patterns Found - 🛑 {blocker} - ⚠️ {warning} ## Human Verification Needed ### 1. Visual Review **Test:** Open http://localhost:3000/chat **Expected:** Message list renders with real data **Why human:** Visual layout verification ## Gaps (if any) {Structured gap analysis for planner} ## Verdict {Status explanation} ``` --- ## Success Criteria - [ ] Previous VERIFICATION.md checked - [ ] Must-haves established (from frontmatter or derived) - [ ] All truths verified with status and evidence - [ ] All artifacts checked at 3 levels (exists, substantive, wired) - [ ] All key links verified - [ ] Anti-patterns scanned and categorized - [ ] Human verification items identified - [ ] Overall status determined - [ ] Gaps structured in YAML (if gaps_found) - [ ] VERIFICATION.md created - [ ] Results returned to orchestrator ================================================ FILE: .gemini/GEMINI.md ================================================ # GSD Methodology — Mission Control Rules > **Get Shit Done**: A spec-driven, context-engineered development methodology. > > These rules enforce disciplined, high-quality autonomous development. --- ## Canonical Rules **All canonical rules are in [PROJECT_RULES.md](../PROJECT_RULES.md).** This file provides Gemini-specific integration. For the complete methodology, see PROJECT_RULES.md. --- ## Core Principles 1. **Plan Before You Build** — No code without specification 2. **State Is Sacred** — Every action updates persistent memory 3. **Context Is Limited** — Prevent degradation through hygiene 4. **Verify Empirically** — No "trust me, it works" --- ## Quick Reference ``` Before coding → Check SPEC.md is FINALIZED Before file read → Search first, then targeted read After each task → Update STATE.md After 3 failures → State dump + fresh session Before "Done" → Empirical proof captured ``` --- ## Workflow Integration These rules integrate with the GSD workflows: | Workflow | Rules Enforced | |----------|----------------| | `/map` | Updates ARCHITECTURE.md, STACK.md | | `/plan` | Enforces Planning Lock, creates ROADMAP | | `/execute` | Enforces State Persistence after each task | | `/verify` | Enforces Empirical Validation | | `/pause` | Triggers Context Hygiene state dump | | `/resume` | Loads state from STATE.md | --- ## Gemini-Specific Tips For Gemini-specific enhancements, see [adapters/GEMINI.md](../adapters/GEMINI.md). Key recommendations: - **Flash** for quick iterations and simple edits - **Pro** for complex planning and analysis - Large context is available but **search-first** still applies --- *GSD Methodology adapted for Google Antigravity* *Canonical rules: [PROJECT_RULES.md](../PROJECT_RULES.md)* *Source: https://github.com/glittercowboy/get-shit-done* ================================================ FILE: .gitignore ================================================ # GSD State Files .gsd/ARCHITECTURE.md .gsd/DECISIONS.md .gsd/JOURNAL.md .gsd/ROADMAP.md .gsd/SPEC.md .gsd/STACK.md .gsd/STATE.md .gsd/TODO.md # OS generated Thumbs.db .DS_Store ================================================ FILE: .gsd/examples/cross-platform.md ================================================ # Cross-Platform Commands Reference > PowerShell ↔ Bash equivalents for GSD workflows ## Common Operations | Operation | PowerShell | Bash | |-----------|------------|------| | **Test file exists** | `Test-Path "file.md"` | `test -f "file.md"` | | **Test directory exists** | `Test-Path "dir" -PathType Container` | `test -d "dir"` | | **Create directory** | `New-Item -ItemType Directory -Path "dir"` | `mkdir -p "dir"` | | **List files** | `Get-ChildItem "*.md"` | `ls *.md` | | **List recursively** | `Get-ChildItem -Recurse` | `find . -type f` | | **Read file** | `Get-Content "file.md"` | `cat "file.md"` | | **Search in files** | `Select-String -Path "**/*" -Pattern "TODO"` | `grep -r "TODO" .` | | **Count lines** | `(Get-Content file).Count` | `wc -l < file` | | **Copy files** | `Copy-Item -Recurse src dest` | `cp -r src dest` | | **Delete files** | `Remove-Item -Recurse -Force dir` | `rm -rf dir` | ## Git Operations (Same on Both) ```bash git add -A git commit -m "message" git push git status --short ``` ## Workflow-Specific Examples ### /map — Analyze Codebase **PowerShell:** ```powershell Get-ChildItem -Recurse -Directory | Where-Object { $_.Name -notmatch "node_modules|\.git" } ``` **Bash:** ```bash find . -type d ! -path "*/node_modules/*" ! -path "*/.git/*" ``` --- ### /plan — Check SPEC Status **PowerShell:** ```powershell $spec = Get-Content ".gsd/SPEC.md" -Raw if ($spec -match "FINALIZED") { "Ready" } ``` **Bash:** ```bash if grep -q "FINALIZED" .gsd/SPEC.md; then echo "Ready"; fi ``` --- ### /execute — Discover Plans **PowerShell:** ```powershell Get-ChildItem ".gsd/phases/1/*-PLAN.md" ``` **Bash:** ```bash ls .gsd/phases/1/*-PLAN.md 2>/dev/null ``` --- ### /verify — Search TODOs **PowerShell:** ```powershell Select-String -Path "src/**/*" -Pattern "TODO|FIXME" ``` **Bash:** ```bash grep -rn "TODO\|FIXME" src/ ``` --- ## Environment Detection Add this to workflows for cross-platform commands: ```markdown **Note:** Commands shown are PowerShell. For Bash equivalents, see `.gsd/examples/cross-platform.md` ``` --- *Reference for Linux/Mac users* ================================================ FILE: .gsd/examples/multi-wave-workflow.md ================================================ # Multi-Wave Workflow Example This example demonstrates a complete GSD workflow with: - Short spec - Plan breakdown - 2-wave execution - Verification with commands - State snapshots --- ## Example: Add User Authentication ### 1. SPEC.md (Finalized) ```markdown --- status: FINALIZED updated: 2026-02-07 --- # User Authentication Feature ## Overview Add login/logout functionality with JWT tokens. ## Requirements 1. POST /api/auth/login endpoint 2. POST /api/auth/logout endpoint 3. JWT stored in httpOnly cookie 4. Protected route middleware ## Success Criteria - User can login with email/password - Invalid credentials return 401 - Protected routes require valid JWT - Logout clears the cookie ``` --- ### 2. ROADMAP.md (Phase Entry) ```markdown ## Phase 1: User Authentication - [ ] Plan 1.1: Auth endpoints (Wave 1) - [ ] Plan 1.2: Protected middleware (Wave 2) ``` --- ### 3. PLAN 1.1 (Wave 1) ```xml --- phase: 1 plan: 1 type: implementation wave: 1 --- Create login and logout endpoints with JWT handling. Files to read: src/app/api/ structure, existing auth if any Create login endpoint src/app/api/auth/login/route.ts Create POST handler accepting {email, password}. Query users table, compare password with bcrypt. On success: generate JWT, set httpOnly cookie, return 200. On failure: return 401 with generic error. curl -X POST localhost:3000/api/auth/login -d '{"email":"test@example.com","password":"test123"}' Valid credentials return 200 + Set-Cookie header Create logout endpoint src/app/api/auth/logout/route.ts Create POST handler that clears the auth cookie. Return 200 on success. curl -X POST localhost:3000/api/auth/logout --cookie "token=..." Cookie is cleared, response is 200 ``` --- ### 4. Wave 1 Execution **Task 1 Commit:** ``` git commit -m "feat(phase-1): create login endpoint" ``` **Task 2 Commit:** ``` git commit -m "feat(phase-1): create logout endpoint" ``` --- ### 5. Wave 1 State Snapshot ```markdown --- wave: 1 phase: 1 created: 2026-02-07T10:30:00 status: complete --- # Wave 1 State Snapshot ## Objective Create authentication endpoints. ## Changes Realized - Created login endpoint with JWT generation - Created logout endpoint with cookie clearing - Added bcrypt password comparison ## Files Touched | File | Change Type | Description | |------|-------------|-------------| | src/app/api/auth/login/route.ts | created | Login handler | | src/app/api/auth/logout/route.ts | created | Logout handler | ## Verification Results | Check | Command | Result | |-------|---------|--------| | Login works | `curl -X POST .../login` | ✅ 200 + cookie | | Logout works | `curl -X POST .../logout` | ✅ 200 + cleared | ## Commits in This Wave | Hash | Message | |------|---------| | abc123 | feat(phase-1): create login endpoint | | def456 | feat(phase-1): create logout endpoint | ## TODO for Next Wave 1. Create auth middleware 2. Apply to protected routes ``` --- ### 6. PLAN 1.2 (Wave 2) ```xml --- phase: 1 plan: 2 type: implementation wave: 2 depends_on: [1] --- Create middleware to protect routes requiring authentication. Wave 1 complete: login/logout endpoints exist. JWT is stored in httpOnly cookie named "token". Create auth middleware src/middleware/auth.ts Create middleware that: 1. Reads JWT from cookie 2. Verifies signature with jose 3. Attaches user to request 4. Returns 401 if invalid/missing Import and call middleware with mock request Valid JWT passes, invalid/missing returns 401 Apply middleware to protected route src/app/api/user/profile/route.ts Create example protected route. Apply auth middleware. Return user data if authenticated. curl localhost:3000/api/user/profile with and without cookie With cookie: 200 + data. Without: 401 ``` --- ### 7. Wave 2 Execution & Snapshot **Commits:** ``` git commit -m "feat(phase-1): create auth middleware" git commit -m "feat(phase-1): apply middleware to profile route" ``` **State Snapshot:** (similar format to Wave 1) --- ### 8. Verification ```bash # Full verification sequence curl -X POST localhost:3000/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"user@example.com","password":"secret"}' \ -c cookies.txt # Expected: 200 + Set-Cookie: token=... curl localhost:3000/api/user/profile -b cookies.txt # Expected: 200 + user data curl localhost:3000/api/user/profile # Expected: 401 curl -X POST localhost:3000/api/auth/logout -b cookies.txt # Expected: 200 + cookie cleared ``` --- ## Key Takeaways 1. **Waves group dependent work** — Wave 2 waited for Wave 1 2. **State snapshots preserve context** — Each wave ends with documented state 3. **Atomic commits per task** — Easy to trace and revert 4. **Verification built into plan** — No "trust me, it works" 5. **Effort hints model selection** — `high` effort = use reasoning model --- *See PROJECT_RULES.md for wave execution rules.* *See templates/state_snapshot.md for snapshot format.* ================================================ FILE: .gsd/examples/quick-reference.md ================================================ # GSD Quick Reference Card ## Workflow Lifecycle ``` ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ /map │ → │ /plan │ → │ /execute │ → │ /verify │ │ │ │ │ │ │ │ │ │ Analyze │ │ Create │ │ Run │ │ Check │ │codebase │ │ phases │ │ tasks │ │ work │ └─────────┘ └─────────┘ └──────────┘ └─────────┘ ↑ │ └──────────────┘ (if gaps found) ``` ## All Commands | Command | Args | Purpose | |---------|------|---------| | `/map` | - | Analyze codebase → ARCHITECTURE.md | | `/plan` | `[phase]` | Create PLAN.md files for phase | | `/execute` | `phase [--gaps-only]` | Run plans with wave execution | | `/verify` | `phase` | Validate with empirical proof | | `/debug` | `description` | Systematic debugging | | `/progress` | - | Show current position | | `/pause` | - | Save state, end session | | `/resume` | - | Load state, start session | | `/add-todo` | `item [--priority]` | Quick capture | | `/check-todos` | `[--all]` | List pending items | ## Core Rules | Rule | Enforcement | |------|-------------| | 🔒 Planning Lock | No code until SPEC finalized | | 💾 State Persistence | Update STATE.md after tasks | | 🧹 Context Hygiene | 3 failures → fresh session | | ✅ Empirical Validation | Proof required for "done" | ## Key Files | File | Purpose | Updated By | |------|---------|------------| | SPEC.md | Vision (finalize first!) | User | | ROADMAP.md | Phase definitions | /plan | | STATE.md | Session memory | All | | ARCHITECTURE.md | System design | /map | | TODO.md | Quick capture | /add-todo | ## XML Task Structure ```xml Clear name exact/path.ts Specific instructions Executable command Measurable criteria ``` ## Priority Indicators | Priority | Icon | |----------|------| | High | 🔴 | | Medium | 🟡 | | Low | 🟢 | --- *Print this for quick reference!* ================================================ FILE: .gsd/examples/workflow-example.md ================================================ # GSD Workflow Example > A complete walkthrough of using GSD from start to finish. ## Scenario: Building a Simple Todo API ### Step 1: Define the Spec First, fill out `.gsd/SPEC.md`: ```markdown # SPEC.md > **Status**: `FINALIZED` ## Vision A simple RESTful API for managing todo items. ## Goals 1. CRUD operations for todos 2. Persistence to SQLite 3. Input validation ## Success Criteria - [ ] POST /todos creates a todo - [ ] GET /todos returns list - [ ] DELETE /todos/:id removes item ``` --- ### Step 2: Map the Codebase (if existing) ``` /map ``` This creates: - `.gsd/ARCHITECTURE.md` — Current structure - `.gsd/STACK.md` — Technologies in use --- ### Step 3: Plan the Phases ``` /plan 1 ``` GSD analyzes the SPEC and creates `.gsd/phases/1/` with PLAN.md files: ```markdown # Plan 1.1: Database Setup ## Objective Create SQLite database with todos table. ## Tasks Initialize SQLite database src/db.ts Create SQLite connection using better-sqlite3. Create todos table with: id, title, completed, created_at. node -e "require('./src/db')" exits without error Database file exists, table created ``` --- ### Step 4: Execute the Phase ``` /execute 1 ``` GSD: 1. Loads Plan 1.1 2. Executes tasks in order 3. Runs verify commands 4. Creates atomic commits 5. Creates SUMMARY.md 6. Proceeds to Plan 1.2 7. Verifies phase goal --- ### Step 5: Verify the Work ``` /verify 1 ``` GSD: 1. Extracts must-haves from phase 2. Runs verification commands 3. Captures evidence 4. Creates VERIFICATION.md 5. Reports pass/fail --- ### Step 6: Continue or Debug **If verified:** ``` /plan 2 → Plan next phase /execute 2 → Execute next phase ``` **If issues found:** ``` /execute 1 --gaps-only → Run fix plans /debug "API returns 500" → Debug the issue ``` --- ## Quick Commands Reference | Command | When to Use | |---------|-------------| | `/map` | Analyze existing codebase | | `/plan [N]` | Create plans for phase N | | `/execute [N]` | Run all plans in phase N | | `/verify [N]` | Confirm phase N works | | `/debug [issue]` | Fix a problem | | `/progress` | See current status | | `/pause` | End session, save state | | `/resume` | Start new session | | `/add-todo` | Capture quick idea | | `/check-todos` | See pending items | --- *This example demonstrates the GSD methodology flow.* ================================================ FILE: .gsd/templates/DEBUG.md ================================================ # Debug Template Template for `.gsd/debug/[slug].md` — active debug session tracking. --- ## File Template ```markdown --- status: gathering | investigating | fixing | verifying | resolved trigger: "[verbatim user input]" created: [ISO timestamp] updated: [ISO timestamp] --- ## Current Focus hypothesis: [current theory being tested] test: [how testing it] expecting: [what result means if true/false] next_action: [immediate next step] ## Symptoms expected: [what should happen] actual: [what actually happens] errors: [error messages if any] reproduction: [how to trigger] started: [when it broke / always broken] ## Eliminated - hypothesis: [theory that was wrong] evidence: [what disproved it] timestamp: [when eliminated] ## Evidence - timestamp: [when found] checked: [what was examined] found: [what was observed] implication: [what this means] ## Resolution root_cause: [empty until found] fix: [empty until applied] verification: [empty until verified] files_changed: [] ``` --- ## Section Rules **Frontmatter (status, trigger, timestamps):** - `status`: OVERWRITE - reflects current phase - `trigger`: IMMUTABLE - verbatim user input, never changes - `created`: IMMUTABLE - set once - `updated`: OVERWRITE - update on every change **Current Focus:** - OVERWRITE entirely on each update - Always reflects what AI is doing RIGHT NOW - If AI reads this after session reset, it knows exactly where to resume - Fields: hypothesis, test, expecting, next_action **Symptoms:** - Written during initial gathering phase - IMMUTABLE after gathering complete - Reference point for what we're trying to fix **Eliminated:** - APPEND only - never remove entries - Prevents re-investigating dead ends after context reset - Critical for efficiency across session boundaries **Evidence:** - APPEND only - never remove entries - Facts discovered during investigation - Builds the case for root cause **Resolution:** - OVERWRITE as understanding evolves - Final state shows confirmed root cause and verified fix --- ## Lifecycle **Creation:** When /debug is called - Create file with trigger from user input - Set status to "gathering" - next_action = "gather symptoms" **During investigation:** - OVERWRITE Current Focus with each hypothesis - APPEND to Evidence with each finding - APPEND to Eliminated when hypothesis disproved **On resolution:** - status → "resolved" - Move file to .gsd/debug/resolved/ --- ## Resume Behavior When AI reads this file after session reset: 1. Parse frontmatter → know status 2. Read Current Focus → know exactly what was happening 3. Read Eliminated → know what NOT to retry 4. Read Evidence → know what's been learned 5. Continue from next_action The file IS the debugging brain. ================================================ FILE: .gsd/templates/PLAN.md ================================================ # PLAN.md Template > Copy this template when creating execution plans. ```markdown --- phase: {N} plan: {M} wave: {W} gap_closure: false --- # Plan {N}.{M}: {Descriptive Name} ## Objective {One paragraph explaining what this plan delivers and why it matters} ## Context Load these files for context: - .gsd/SPEC.md - .gsd/ARCHITECTURE.md - {relevant source files} ## Tasks {Clear, specific task name} {exact/file/path1.ext} {exact/file/path2.ext} {Specific implementation instructions} Steps: 1. {Step 1} 2. {Step 2} 3. {Step 3} AVOID: {common mistake} because {reason} USE: {preferred approach} because {reason} {Executable command or check} Example: npm test -- --testNamePattern="auth" Example: curl -X POST localhost:3000/api/login {Measurable acceptance criteria} Example: Valid credentials → 200 + Set-Cookie, invalid → 401 {Task 2 name} {files} {instructions} {command} {criteria} ## Must-Haves After all tasks complete, verify: - [ ] {Must-have 1 — derived from phase goal} - [ ] {Must-have 2} ## Success Criteria - [ ] All tasks verified passing - [ ] Must-haves confirmed - [ ] No regressions in tests ``` ## Task Types | Type | Use For | Behavior | |------|---------|----------| | `auto` | Everything Claude can do independently | Fully autonomous | | `checkpoint:human-verify` | Visual/functional verification | Pauses for user | | `checkpoint:decision` | Implementation choices | Pauses for user | ## Wave Assignment | Wave | Use For | |------|---------| | 1 | Foundation (types, schemas, utilities) | | 2 | Core implementations | | 3 | Integration and validation | Plans in the same wave can run in parallel. Later waves depend on earlier waves. ================================================ FILE: .gsd/templates/RESEARCH.md ================================================ # RESEARCH.md Template > Copy this template when documenting phase research. ```markdown --- phase: {N} researched_at: {YYYY-MM-DD} discovery_level: 1 | 2 | 3 --- # Phase {N} Research ## Objective {What question is this research answering?} ## Discovery Level **Level {1|2|3}** — {Quick verification | Standard research | Deep dive} ## Key Decisions ### Decision 1: {Topic} **Question:** {What needed to be decided?} **Options Considered:** 1. {Option A}: {pros/cons} 2. {Option B}: {pros/cons} 3. {Option C}: {pros/cons} **Decision:** {Which option and why} **Confidence:** {High | Medium | Low} ### Decision 2: {Topic} ... ## Findings ### {Topic 1} {What was learned} **Sources:** - {URL or reference} - {URL or reference} ### {Topic 2} {What was learned} ## Patterns to Follow - {Pattern 1}: {How to apply it} - {Pattern 2}: {How to apply it} ## Anti-Patterns to Avoid - {Anti-pattern 1}: {Why to avoid} - {Anti-pattern 2}: {Why to avoid} ## Dependencies Identified | Package | Version | Purpose | |---------|---------|---------| | {pkg} | {ver} | {why needed} | ## Risks - **{Risk 1}:** {Impact and mitigation} - **{Risk 2}:** {Impact and mitigation} ## Recommendations for Planning 1. {Recommendation 1} 2. {Recommendation 2} ``` ## Discovery Levels | Level | Time | Use When | |-------|------|----------| | 1 | 2-5 min | Single known library, confirming syntax | | 2 | 15-30 min | Choosing between options, new integration | | 3 | 1+ hour | Architectural decision, novel problem | ================================================ FILE: .gsd/templates/SUMMARY.md ================================================ # Summary Template Template for `.gsd/phases/{N}/{plan}-SUMMARY.md` — execution summary after plan completion. --- ## File Template ```markdown --- phase: {N} plan: {M} completed_at: [ISO timestamp] duration_minutes: {N} status: complete | partial | failed --- # Summary: {Plan Name} ## Results - **Tasks:** {N}/{M} completed - **Commits:** {N} - **Verification:** {passed | failed} --- ## Tasks Completed | Task | Description | Commit | Status | |------|-------------|--------|--------| | 1 | {task name} | {hash} | ✅ Complete | | 2 | {task name} | {hash} | ✅ Complete | | 3 | {task name} | — | ❌ Blocked | --- ## Files Changed | File | Change Type | Description | |------|-------------|-------------| | {path} | Created | {what it does} | | {path} | Modified | {what changed} | | {path} | Deleted | {why removed} | --- ## Deviations Applied {If none: "None — executed as planned."} ### Rule 1 — Bug Fixes - {description of bug fixed} ### Rule 2 — Missing Critical - {description of functionality added} ### Rule 3 — Blocking Issues - {description of blocker fixed} --- ## Verification | Check | Status | Evidence | |-------|--------|----------| | {verification 1} | ✅ Pass | {command/output} | | {verification 2} | ✅ Pass | {command/output} | --- ## Notes {Any observations, concerns, or recommendations for future phases} --- ## Metadata - **Started:** {timestamp} - **Completed:** {timestamp} - **Duration:** {N} minutes - **Context Usage:** ~{N}% ``` --- ## Guidelines **Create SUMMARY.md:** - After each plan completes - Before moving to next plan - Even if plan failed (document what happened) **Include:** - All commits with hashes - All deviations (never hide these) - Verification results with evidence **Keep it factual:** - No opinions - Just what happened - Evidence over claims ================================================ FILE: .gsd/templates/UAT.md ================================================ # UAT Template Template for `.gsd/phases/{N}/UAT.md` — User Acceptance Testing checklist. **Purpose:** Structured manual testing protocol for human verification checkpoints. --- ## File Template ```markdown --- phase: {N} type: uat created: [ISO timestamp] status: pending | in_progress | passed | failed --- # Phase {N} UAT ## Overview **Phase:** {name} **Goal:** {what this phase delivers} **Tester:** User **Date:** {date} --- ## Test Environment **Setup Required:** - [ ] Dev server running (`npm run dev`) - [ ] Database seeded with test data - [ ] Browser dev tools open for error monitoring **Test Data:** - User: test@example.com / password123 - Other relevant test accounts/data --- ## Test Cases ### TC-01: {Test Case Name} **Scenario:** {What user is trying to do} **Steps:** 1. {Step 1} 2. {Step 2} 3. {Step 3} **Expected Result:** - {What should happen} **Actual Result:** - [ ] PASS - [ ] FAIL — Issue: ___ --- ### TC-02: {Test Case Name} **Scenario:** {What user is trying to do} **Steps:** 1. {Step 1} 2. {Step 2} **Expected Result:** - {What should happen} **Actual Result:** - [ ] PASS - [ ] FAIL — Issue: ___ --- ## Edge Cases ### EC-01: {Edge Case Name} **Test:** {What to try} **Expected:** {Graceful handling} **Result:** [ ] PASS [ ] FAIL --- ## Error Scenarios ### ERR-01: {Error Scenario} **Trigger:** {How to cause error} **Expected Behavior:** {Error message, recovery} **Result:** [ ] PASS [ ] FAIL --- ## Visual Verification ### VIS-01: Layout - [ ] Responsive on mobile (375px) - [ ] Responsive on tablet (768px) - [ ] Desktop layout correct (1024px+) - [ ] No horizontal scroll - [ ] All text readable ### VIS-02: Styling - [ ] Colors match design system - [ ] Fonts correct - [ ] Spacing consistent - [ ] Icons display correctly --- ## Summary | Category | Pass | Fail | Total | |----------|------|------|-------| | Functional | | | | | Edge Cases | | | | | Errors | | | | | Visual | | | | **Overall Status:** [ ] APPROVED [ ] NEEDS FIXES **Issues Found:** 1. {Issue description} 2. {Issue description} **Notes:** {Any additional observations} ``` --- ## Usage Guidelines **When to create UAT:** - After phase execution complete - Before marking phase as verified - For any `checkpoint:human-verify` tasks **Who runs UAT:** - User (always) - AI cannot verify visual/UX elements **After UAT:** - If PASSED: Phase can be marked complete - If FAILED: Create gap closure plans with `/plan-milestone-gaps` --- ## Test Case Guidelines **Good test cases:** - Specific, reproducible steps - Clear expected results - One scenario per test case **Categories to cover:** 1. Happy path (main functionality) 2. Edge cases (boundary conditions) 3. Error handling (invalid input, failures) 4. Visual/UX (layout, responsiveness) ================================================ FILE: .gsd/templates/VERIFICATION.md ================================================ # VERIFICATION.md Template > Copy this template when creating phase verification reports. ```markdown --- phase: {N} verified_at: {YYYY-MM-DD HH:MM} verdict: PASS | FAIL | PARTIAL pass_count: {X} total_count: {Y} --- # Phase {N} Verification Report ## Summary **{X}/{Y}** must-haves verified **Verdict:** {PASS | FAIL | PARTIAL} ## Must-Haves ### ✅ 1. {Must-have description} **Status:** PASS **Method:** {How this was verified} **Evidence:** ``` {Actual command output or screenshot reference} ``` ### ❌ 2. {Must-have description} **Status:** FAIL **Method:** {How this was verified} **Expected:** {What should happen} **Actual:** {What actually happened} **Evidence:** ``` {Actual command output} ``` **Gap:** {What needs to be fixed} ### ⏭️ 3. {Must-have description} **Status:** SKIPPED **Reason:** {Why this couldn't be verified} ## Gap Closure Required {If verdict is FAIL or PARTIAL, list what needs fixing} 1. **{Gap 1}:** {Description of what's wrong and how to fix} 2. **{Gap 2}:** {Description} ## Next Steps {Based on verdict} - If PASS: Proceed to next phase - If FAIL: Run `/execute {N} --gaps-only` after fixing - If PARTIAL: Address gaps then re-verify ``` ## Evidence Types | Verification | Evidence Required | |--------------|-------------------| | API endpoint | curl command + response | | UI behavior | Screenshot | | Test suite | Test output | | File exists | `ls` or `dir` output | | Build passes | Build command output | ================================================ FILE: .gsd/templates/architecture.md ================================================ # Architecture > Auto-generated by /map on ## Overview {Brief description of the system and its purpose.} ``` ┌───────────────────────────────────────────────────────────────┐ │ USER │ └────────────────────────┬──────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ COMPONENT A │ └────────────────────────┬──────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ COMPONENT B │ └───────────────────────────────────────────────────────────────┘ ``` ## Components ### Component A - **Purpose:** {What this component does} - **Location:** `{path/to/component}` - **Files:** {count} files - **Pattern:** {architectural pattern used} | File | Purpose | Priority | |------|---------|----------| | file1 | {purpose} | {high/medium/low} | | file2 | {purpose} | {high/medium/low} | ### Component B - **Purpose:** {What this component does} - **Location:** `{path/to/component}` ## Data Flow 1. **User initiates action** (e.g., {example}) 2. **Component A processes** {what happens} 3. **Component B receives** {what happens} 4. **Result returned** to user ## Technical Debt - [ ] {Identified debt item 1} - [ ] {Identified debt item 2} - [ ] {Identified debt item 3} ## Conventions **Naming:** - {Convention 1} - {Convention 2} **Structure:** - {Convention 1} - {Convention 2} --- *Last updated: * ================================================ FILE: .gsd/templates/context.md ================================================ # Context Template Template for `.gsd/phases/{N}/CONTEXT.md` — user's vision for a phase. --- ## File Template ```markdown --- phase: {N} name: {phase-name} created: [ISO timestamp] --- # Phase {N} Context ## Vision {How the user imagines this phase working — in their words} ## What's Essential Non-negotiable aspects: - {Essential 1} - {Essential 2} - {Essential 3} ## What's Flexible Open to different implementations: - {Flexible 1} - {Flexible 2} ## What's Out of Scope Explicitly NOT part of this phase: - {Out of scope 1} - {Out of scope 2} ## User Expectations ### Look and Feel {How it should appear/behave} ### Performance {Speed/responsiveness expectations} ### Integration {How it fits with existing work} ## Examples / Inspiration {Any examples the user referenced} ## Questions Answered Clarifications from /discuss-phase: | Question | Answer | |----------|--------| | {question} | {answer} | ## Constraints Technical or business constraints: - {Constraint 1} - {Constraint 2} ``` --- ## When to Create Created by `/discuss-phase` to capture user's vision before planning. ## How to Use - Planner reads CONTEXT.md to understand intent - Executor honors the vision during implementation - Verifier checks against user expectations ## Guidelines - Capture user's words, not AI interpretation - Focus on WHAT, not HOW - Keep it short — vision, not specification ================================================ FILE: .gsd/templates/decisions.md ================================================ # DECISIONS.md — Architecture Decision Records > **Purpose**: Log significant technical decisions and their rationale. ## Template ```markdown ## [DECISION-XXX] Title **Date**: YYYY-MM-DD **Status**: Proposed | Accepted | Deprecated | Superseded ### Context What is the issue we're facing? ### Decision What have we decided to do? ### Rationale Why did we make this decision? ### Consequences What are the trade-offs? ### Alternatives Considered What other options were evaluated? ``` --- ## Decisions --- *Last updated: * ================================================ FILE: .gsd/templates/discovery.md ================================================ # Discovery Template Template for `.gsd/phases/{N}/DISCOVERY.md` — shallow research for library/option decisions. **Purpose:** Answer "which library/option should we use" questions during planning. For deep ecosystem research, use `/research-phase` which produces RESEARCH.md. --- ## File Template ```markdown --- phase: {N} type: discovery topic: [discovery-topic] --- Discover [topic] to inform [phase name] implementation. Purpose: [What decision/implementation this enables] Scope: [Boundaries] Output: DISCOVERY.md with recommendation - [Question to answer] - [Area to investigate] - [Specific comparison if needed] - [Out of scope for this discovery] - [Defer to implementation phase] **Source Priority:** 1. **Official Docs** — Authoritative, current 2. **Web Search** — For comparisons, trends (verify findings) 3. **GitHub** — For real usage patterns **Quality Checklist:** - [ ] All claims have authoritative sources - [ ] Negative claims verified with official docs - [ ] Alternative approaches considered - [ ] Recent updates checked for breaking changes **Confidence Levels:** - HIGH: Official docs confirm - MEDIUM: Multiple sources confirm - LOW: Single source or training knowledge only ``` --- ## Output Structure Create `.gsd/phases/{N}/DISCOVERY.md`: ```markdown # [Topic] Discovery ## Summary [2-3 paragraph executive summary] ## Primary Recommendation [What to do and why — specific and actionable] ## Alternatives Considered [What else was evaluated and why not chosen] ## Key Findings ### [Category 1] - [Finding with source URL] ### [Category 2] - [Finding with relevance] ## Code Examples [Relevant patterns if applicable] ## Metadata [Why this confidence level] - [Primary sources used] [What needs validation during implementation] ``` --- ## When to Use **Use discovery when:** - Technology choice unclear (library A vs B) - Best practices needed for unfamiliar integration - API/library investigation required **Don't use when:** - Established patterns (CRUD, auth with known library) - Questions answerable from project context **Use RESEARCH.md instead when:** - Niche/complex domains (3D, games, audio) - Need ecosystem knowledge, not just library choice - "How do experts build this" questions ================================================ FILE: .gsd/templates/journal.md ================================================ # JOURNAL.md — Session Log > **Purpose**: Chronicle of work sessions for context continuity. --- ## Sessions ## Session: YYYY-MM-DD HH:MM ### Objective {What you set out to accomplish this session.} ### Accomplished - ✅ {Task 1 completed} - ✅ {Task 2 completed} - {Sub-detail if needed} - ✅ {Task 3 completed} ### Verification - [x] {Verification check 1} - [x] {Verification check 2} - [ ] {Verification pending} ### Blockers Encountered - {Blocker 1 and how it was resolved} - {Blocker 2 — still open} ### Handoff Notes - {Important context for next session} - {Files that need attention} - {Decisions that need to be made} --- ## Session: YYYY-MM-DD HH:MM ### Objective {Previous session objective.} ### Accomplished - ✅ {Completed items} --- *Last updated: * ================================================ FILE: .gsd/templates/milestone.md ================================================ # Milestone Template Template for `.gsd/milestones/{name}/MILESTONE.md` — milestone definition and tracking. --- ## File Template ```markdown --- name: {milestone-name} version: {semantic version, e.g., v1.0} status: planning | active | complete | archived created: [ISO timestamp] target_date: [optional target] --- # Milestone: {name} ## Vision {What this milestone achieves — one paragraph} ## Must-Haves Non-negotiable deliverables for this milestone: - [ ] {Must-have 1} - [ ] {Must-have 2} - [ ] {Must-have 3} ## Nice-to-Haves If time permits: - [ ] {Nice-to-have 1} - [ ] {Nice-to-have 2} ## Phases | Phase | Name | Status | Objective | |-------|------|--------|-----------| | 1 | {name} | ⬜ Not Started | {objective} | | 2 | {name} | ⬜ Not Started | {objective} | | 3 | {name} | ⬜ Not Started | {objective} | ## Success Criteria How we know milestone is complete: - [ ] {Measurable criterion 1} - [ ] {Measurable criterion 2} ## Architecture Decisions Key technical decisions for this milestone: | Decision | Choice | Rationale | |----------|--------|-----------| | {decision} | {choice} | {why} | ## Risks | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | {risk} | Low/Med/High | Low/Med/High | {action} | ## Progress Log | Date | Event | Notes | |------|-------|-------| | {date} | Milestone started | — | ``` --- ## Lifecycle 1. **Creation:** `/new-milestone` creates this file 2. **Active:** Updated as phases complete 3. **Complete:** `/complete-milestone` moves to archive 4. **Archived:** Read-only reference --- ## Guidelines - One active milestone at a time - 3-5 phases per milestone - Must-haves should be testable - Success criteria should be measurable ================================================ FILE: .gsd/templates/phase-summary.md ================================================ # Phase {N} Summary > **Status**: Complete > **Completed**: YYYY-MM-DD ## Objective {What this phase set out to accomplish.} ## Deliverables | Deliverable | Status | Notes | |-------------|--------|-------| | {Deliverable 1} | ✅ | {Any relevant notes} | | {Deliverable 2} | ✅ | {Any relevant notes} | | {Deliverable 3} | ✅ | {Any relevant notes} | ## Tasks Completed ### Plan {N}.1: {Plan Name} - [x] {Task 1} - [x] {Task 2} ### Plan {N}.2: {Plan Name} - [x] {Task 1} - [x] {Task 2} ## Verification Results | Check | Result | Evidence | |-------|--------|----------| | {Verification 1} | ✅ Pass | {Command output / screenshot path} | | {Verification 2} | ✅ Pass | {Command output / screenshot path} | ## Commits | Hash | Message | |------|---------| | `abc123` | feat(phase-N): {description} | | `def456` | feat(phase-N): {description} | ## Lessons Learned - {What went well} - {What could be improved} - {Unexpected discoveries} ## Next Steps - {What the next phase should address} - {Any deferred items} --- *Completed: YYYY-MM-DD* ================================================ FILE: .gsd/templates/project.md ================================================ # Project Template Template for `.gsd/SPEC.md` (or PROJECT.md) — project specification. --- ## File Template ```markdown --- status: DRAFT | FINALIZED created: [ISO timestamp] finalized: [ISO timestamp when status changed] --- # SPEC.md — Project Specification ## Vision {One paragraph describing what this project is and why it matters} --- ## Goals 1. **{Primary Goal}** {Brief description} 2. **{Secondary Goal}** {Brief description} 3. **{Tertiary Goal}** {Brief description} --- ## Non-Goals (Out of Scope) Explicitly NOT part of this project: - {Non-goal 1} - {Non-goal 2} - {Non-goal 3} --- ## Users **Primary User:** {Who} - {How they'll use it} - {What they need} **Secondary User:** {Who} (if applicable) - {How they'll use it} --- ## Constraints ### Technical - {Technical constraint 1} - {Technical constraint 2} ### Timeline - {Timeline constraint} ### Other - {Budget, resources, etc.} --- ## Success Criteria How we know the project is successful: - [ ] {Measurable outcome 1} - [ ] {Measurable outcome 2} - [ ] {Measurable outcome 3} --- ## Prior Art Existing solutions or inspiration: | Solution | Pros | Cons | Relevance | |----------|------|------|-----------| | {solution} | {pros} | {cons} | {how it relates} | --- ## Open Questions Questions to resolve during planning: - [ ] {Question 1} - [ ] {Question 2} --- ## Decisions Key decisions made during specification: | Decision | Choice | Rationale | Date | |----------|--------|-----------|------| | {decision} | {choice} | {why} | {date} | ``` --- ## Status Flow 1. **DRAFT** — Being written, not ready for planning 2. **FINALIZED** — Approved, planning can begin **Planning Lock:** Cannot create plans until status is FINALIZED. ## Guidelines - Keep vision to one paragraph - Goals should be achievable in one milestone - Non-goals are as important as goals - Success criteria must be measurable ================================================ FILE: .gsd/templates/requirements.md ================================================ # Requirements Template Template for `.gsd/REQUIREMENTS.md` — formal requirements tracking with traceability. --- ## File Template ```markdown --- milestone: {name} updated: [ISO timestamp] --- # Requirements ## Overview Requirements derived from SPEC.md for traceability and coverage tracking. --- ## Functional Requirements | ID | Requirement | Source | Phase | Status | |----|-------------|--------|-------|--------| | REQ-01 | {requirement description} | SPEC Goal 1 | 1 | Pending | | REQ-02 | {requirement description} | SPEC Goal 1 | 1 | Pending | | REQ-03 | {requirement description} | SPEC Goal 2 | 2 | Pending | | REQ-04 | {requirement description} | SPEC Goal 2 | 2 | Pending | | REQ-05 | {requirement description} | SPEC Goal 3 | 3 | Pending | --- ## Non-Functional Requirements | ID | Requirement | Category | Phase | Status | |----|-------------|----------|-------|--------| | NFR-01 | Response time < 200ms | Performance | 4 | Pending | | NFR-02 | Mobile responsive | UX | All | Pending | | NFR-03 | 99% uptime | Reliability | 4 | Pending | --- ## Constraints | ID | Constraint | Source | Impact | |----|------------|--------|--------| | CON-01 | {constraint} | SPEC | {affected areas} | | CON-02 | {constraint} | Technical | {affected areas} | --- ## Traceability Matrix | Requirement | Plans | Tests | Status | |-------------|-------|-------|--------| | REQ-01 | 1.1, 1.2 | TC-01 | — | | REQ-02 | 1.2 | TC-02, TC-03 | — | | REQ-03 | 2.1 | TC-04 | — | --- ## Status Definitions | Status | Meaning | |--------|---------| | Pending | Not yet started | | In Progress | Being implemented | | Complete | Implemented and verified | | Blocked | Cannot proceed | | Deferred | Moved to later milestone | ``` --- ## Guidelines **Requirement IDs:** - REQ-XX: Functional requirements - NFR-XX: Non-functional requirements - CON-XX: Constraints **Good requirements are:** - Testable - Specific - Traceable to SPEC goals **Update when:** - Phase completes (mark requirements satisfied) - Scope changes (add/defer requirements) - Verification passes (update status) ================================================ FILE: .gsd/templates/roadmap.md ================================================ # Roadmap Template Template for `.gsd/ROADMAP.md` — phase structure and progress tracking. --- ## File Template ```markdown --- milestone: {name} version: {semantic version} updated: [ISO timestamp] --- # Roadmap > **Current Phase:** {N} - {name} > **Status:** {planning | executing | verifying} ## Must-Haves (from SPEC) - [ ] {Must-have 1} - [ ] {Must-have 2} - [ ] {Must-have 3} --- ## Phases ### Phase 1: {Foundation} **Status:** ⬜ Not Started | 🔄 In Progress | ✅ Complete **Objective:** {What this phase delivers} **Requirements:** REQ-01, REQ-02 **Plans:** - [ ] Plan 1.1: {name} - [ ] Plan 1.2: {name} --- ### Phase 2: {Core Feature} **Status:** ⬜ Not Started **Objective:** {What this phase delivers} **Depends on:** Phase 1 **Plans:** - [ ] Plan 2.1: {name} - [ ] Plan 2.2: {name} --- ### Phase 3: {Integration} **Status:** ⬜ Not Started **Objective:** {What this phase delivers} **Depends on:** Phase 2 --- ### Phase 4: {Polish/Launch} **Status:** ⬜ Not Started **Objective:** {Final touches and deployment} **Depends on:** Phase 3 --- ## Progress Summary | Phase | Status | Plans | Complete | |-------|--------|-------|----------| | 1 | ⬜ | 0/2 | — | | 2 | ⬜ | 0/2 | — | | 3 | ⬜ | 0/1 | — | | 4 | ⬜ | 0/1 | — | --- ## Timeline | Phase | Started | Completed | Duration | |-------|---------|-----------|----------| | 1 | — | — | — | | 2 | — | — | — | | 3 | — | — | — | | 4 | — | — | — | ``` --- ## Status Icons - ⬜ Not Started - 🔄 In Progress - ✅ Complete - ⏸️ Paused - ❌ Blocked ## Guidelines - 3-5 phases per milestone - Each phase has clear deliverable - Dependencies flow forward - Update status as work progresses ================================================ FILE: .gsd/templates/spec.md ================================================ # SPEC.md — Project Specification > **Status**: `DRAFT` | `FINALIZED` > > ⚠️ **Planning Lock**: No code may be written until this spec is marked `FINALIZED`. ## Vision {One paragraph describing what this project is and why it exists.} ## Goals 1. **{Goal 1}** — {Brief description} 2. **{Goal 2}** — {Brief description} 3. **{Goal 3}** — {Brief description} ## Non-Goals (Out of Scope) - {What this project explicitly will NOT do} - {Features that are intentionally excluded} - {Scope boundaries} ## Constraints - {Technical constraint 1} - {Business constraint 1} - {Timeline constraint 1} ## Success Criteria - [ ] {Measurable outcome 1} - [ ] {Measurable outcome 2} - [ ] {Measurable outcome 3} - [ ] {Measurable outcome 4} ## User Stories (Optional) ### As a {user type} - I want to {action} - So that {benefit} ### As a {user type} - I want to {action} - So that {benefit} ## Technical Requirements (Optional) | Requirement | Priority | Notes | |-------------|----------|-------| | {Requirement 1} | Must-have | {Details} | | {Requirement 2} | Should-have | {Details} | | {Requirement 3} | Nice-to-have | {Details} | --- *Last updated: * ================================================ FILE: .gsd/templates/sprint.md ================================================ # Sprint {N} — {Sprint Name} > **Duration**: YYYY-MM-DD to YYYY-MM-DD > **Status**: In Progress | Complete ## Goal {One sentence describing what this sprint aims to achieve.} ## Scope ### Included - {Feature/task 1} - {Feature/task 2} - {Feature/task 3} ### Explicitly Excluded - {Out of scope item 1} - {Out of scope item 2} ## Tasks | Task | Assignee | Status | Est. Hours | |------|----------|--------|------------| | {Task 1} | {who} | ⬜ Todo | {hours} | | {Task 2} | {who} | 🔄 In Progress | {hours} | | {Task 3} | {who} | ✅ Done | {hours} | ## Daily Log ### Day 1 (YYYY-MM-DD) - {What was accomplished} - {Blockers encountered} ### Day 2 (YYYY-MM-DD) - {What was accomplished} - {Blockers encountered} ## Risks & Blockers | Risk | Impact | Mitigation | |------|--------|------------| | {Risk 1} | {High/Med/Low} | {What can be done} | ## Retrospective (end of sprint) ### What Went Well - {Positive outcome 1} ### What Could Improve - {Area for improvement 1} ### Action Items - [ ] {Action to take in next sprint} --- *Last updated: * ================================================ FILE: .gsd/templates/stack.md ================================================ # Technology Stack > Auto-generated by /map on ## Runtime | Technology | Version | Purpose | |------------|---------|---------| | {Language} | {version} | {purpose} | | {Framework} | {version} | {purpose} | | {Database} | {version} | {purpose} | ## Core Technologies ### {Category 1} | Feature | System | Purpose | |---------|--------|---------| | {Feature} | {System/Location} | {Purpose} | ### {Category 2} | Directory | Files | Purpose | |-----------|-------|---------| | `{path}` | {count} | {purpose} | ## Dependencies ### External Dependencies | Package | Version | Purpose | |---------|---------|---------| | {package} | {version} | {purpose} | ### Internal Dependencies | Component | Depends On | Purpose | |-----------|------------|---------| | {Component A} | {Component B} | {Why dependency exists} | ## Infrastructure | Service | Provider | Purpose | |---------|----------|---------| | {Service} | {Provider} | {Purpose} | **Repository:** {repository URL} ## Configuration | Variable | Purpose | Location | |----------|---------|----------| | {VAR_NAME} | {What it controls} | {Where it's set} | ## File Size Inventory | Category | Count | Total Lines (approx) | |----------|-------|---------------------| | {Category} | {count} | {lines} | | **Total** | **{total}** | **{total_lines}** | --- *Last updated: * ================================================ FILE: .gsd/templates/state.md ================================================ # State Template Template for `.gsd/STATE.md` — project memory across sessions. --- ## File Template ```markdown --- updated: [ISO timestamp] --- # Project State ## Current Position **Milestone:** {name} **Phase:** {N} - {name} **Status:** {planning | executing | verifying | blocked} **Plan:** {current plan if executing} ## Last Action {What was just completed} ## Next Steps 1. {Immediate next action} 2. {Following action} 3. {Third action if known} ## Active Decisions Decisions made that affect current work: | Decision | Choice | Made | Affects | |----------|--------|------|---------| | {what} | {choice} | {date} | {phases/plans} | ## Blockers {None if clear} - [ ] {Blocker 1}: {resolution approach} - [ ] {Blocker 2}: {resolution approach} ## Concerns Things to watch but not blocking: - {Concern 1} - {Concern 2} ## Session Context {Any context the next session needs to know} ``` --- ## Update Rules **Update STATE.md after:** - Every completed task - Every decision made - Any blocker identified - Session end/pause **What to update:** - `updated` timestamp - Current Position - Last Action - Next Steps **Keep it lean:** - STATE.md is read frequently - Only current context, not history - History goes in JOURNAL.md --- ## Resume Protocol When starting a new session: 1. Read STATE.md first 2. Understand current position 3. Check blockers/concerns 4. Continue from Next Steps The STATE.md is the "save game" for the project. ================================================ FILE: .gsd/templates/state_snapshot.md ================================================ # State Snapshot Template Template for wave summaries and session state captures. --- ## When to Use Create a state snapshot: - After completing each wave - Before pausing work - After 3 debugging failures - When switching models mid-session - At any significant milestone --- ## Template ```markdown --- wave: {N} phase: {phase number} created: {ISO timestamp} status: {complete | partial | blocked} --- # Wave {N} State Snapshot ## Objective {What this wave aimed to accomplish — 1-2 sentences} ## Changes Realized - {Change 1} - {Change 2} - {Change 3} ## Files Touched | File | Change Type | Description | |------|-------------|-------------| | {path/to/file1} | created | {brief description} | | {path/to/file2} | modified | {brief description} | | {path/to/file3} | deleted | {brief description} | ## Verification Results | Check | Command | Result | |-------|---------|--------| | {Test 1} | `{command}` | ✅ Passed | | {Test 2} | `{command}` | ✅ Passed | | {Test 3} | `{command}` | ❌ Failed: {reason} | ## Commits in This Wave | Hash | Message | |------|---------| | {abc123} | {commit message 1} | | {def456} | {commit message 2} | ## Risks & Technical Debt {None if clear} - ⚠️ {Risk or debt item 1} - ⚠️ {Risk or debt item 2} ## TODO for Next Wave 1. {Next task 1} 2. {Next task 2} 3. {Next task 3} ## Context for Fresh Session {Any information the next session needs — decisions made, blockers encountered, hypotheses to test} ## Token Usage (Optional) | Metric | Value | |--------|-------| | Files loaded | {count} | | Est. tokens | {number} | | Budget used | {percentage}% | | Compression | {yes/no} | {Notes on token efficiency for this wave} ``` --- ## Minimal Snapshot (Debug Session) For quick state dumps during debugging: ```markdown # Debug State Snapshot **Time:** {timestamp} **Problem:** {what you're debugging} **Tried:** 1. {approach 1} → {result} 2. {approach 2} → {result} 3. {approach 3} → {result} **Current Hypothesis:** {theory} **Files Involved:** - {file1} - {file2} **Recommended Next:** {suggested approach for fresh session} ``` --- ## Integration with STATE.md State snapshots are point-in-time captures. After creating a snapshot: 1. Update STATE.md with current position 2. Reference the snapshot in SESSION Context 3. Commit both together STATE.md is current state; snapshots are historical records. --- *Part of GSD methodology. See PROJECT_RULES.md for wave execution rules.* ================================================ FILE: .gsd/templates/todo.md ================================================ # TODO.md — Pending Items > Quick capture of ideas, tasks, and issues. > > Use `/add-todo` to add items, `/check-todos` to view. ## Format ```markdown - [ ] Description `priority` — YYYY-MM-DD - [x] Completed item `priority` — YYYY-MM-DD ✓ YYYY-MM-DD ``` ## Priority Levels | Level | Use For | |-------|---------| | `high` 🔴 | Blocking issues, urgent fixes | | `medium` 🟡 | Normal priority (default) | | `low` 🟢 | Nice-to-have, future ideas | --- ## Items - [ ] {Example todo item} `medium` — YYYY-MM-DD --- *Last updated: * ================================================ FILE: .gsd/templates/token_report.md ================================================ # Token Report Template Template for documenting token usage per wave or session. --- ## Template ```markdown --- wave: {N} phase: {phase number} created: {ISO timestamp} --- # Token Usage Report ## Summary | Metric | Value | |--------|-------| | Files loaded | {count} | | Estimated tokens | {number} | | Budget usage | {percentage}% | | Compression applied | {yes/no} | ## Files Loaded | File | Lines | Est. Tokens | Reason | |------|-------|-------------|--------| | {path/to/file1} | {N} | {N} | {why loaded} | | {path/to/file2} | {N} | {N} | {why loaded} | ## Compression Applied | File | Before | After | Savings | |------|--------|-------|---------| | {file} | {N} | summary | {N} tokens | ## Efficiency Analysis ### What Worked Well - {Strategy that saved tokens} ### Could Improve - {Opportunity for optimization} ### Recommendations - {Suggestion for next wave} ``` --- ## When to Create Create a token report: - After completing a wave with high token usage - When budget exceeds 50% - For debugging session performance - During milestone retrospectives --- ## Quick Report (Minimal) For simple tracking: ```markdown ## Token Report: Wave {N} - Files: {count} - Tokens: ~{number} - Budget: {X}% - Status: [OK|WARNING|CRITICAL] ``` --- *Part of GSD v1.6 Token Optimization.* ================================================ FILE: .gsd/templates/user-setup.md ================================================ # User Setup Template Template for user setup instructions when external services are needed. --- ## File Template ```markdown --- phase: {N} plan: {M} type: user-setup --- # User Setup Required ## Overview This plan requires manual setup that the AI cannot perform. **Time estimate:** {X minutes} **Blocking:** Plan cannot proceed until complete --- ## Setup Steps ### 1. {Service Name} **Why needed:** {Purpose in the project} **Create account:** - Go to: {URL} - Sign up with: {recommendations} **Get credentials:** 1. Navigate to: {dashboard location} 2. Find: {API keys section} 3. Create: {what to create} **Add to project:** ```powershell # Add to .env.local {ENV_VAR}=your_key_here ``` **Verify:** ```powershell # Test the connection {verification command} ``` --- ### 2. {Another Service} **Why needed:** {Purpose} **Steps:** 1. {Step 1} 2. {Step 2} 3. {Step 3} **Environment variables:** ``` {VAR_1}=value {VAR_2}=value ``` --- ## Dashboard Configuration Some things require manual dashboard setup: | Service | Task | Location | Notes | |---------|------|----------|-------| | {service} | {task} | {where} | {notes} | --- ## Verification Checklist Before continuing, verify: - [ ] All environment variables set - [ ] All accounts created - [ ] All dashboard configurations complete - [ ] Verification commands pass --- ## When Complete Type "done" or "setup complete" to continue with execution. ``` --- ## Guidelines **Include only what AI cannot do:** - Account creation (requires human identity) - Secret retrieval (protected behind login) - Dashboard configuration (no API available) - Payment method setup - 2FA enrollment **Do NOT include:** - npm install (AI can do) - File creation (AI can do) - Configuration file edits (AI can do) - API calls (AI can do) **Keep minimal** — every manual step slows down execution. ================================================ FILE: CHANGELOG.md ================================================ # Changelog All notable changes to GSD for Antigravity. ## [1.5.0] - 2026-04-01 ### Breaking Changes - **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 - **SKILL.md `name` fields updated** — all 11 skills now use lowercase-hyphenated names matching their folder names per spec (e.g., `GSD Executor` → `executor`) ### Added - `/sprint` workflow — time-boxed sprints (new/status/close) for quick focused work outside the milestone cycle - **Test Quality Rules** in `/plan` — prevents agents from gaming test suites with mock-everything, tautological assertions, or always-pass tests - **Discovery template reference** (Level 1.5) in `/plan` — bridges the gap between quick verification and full research - **Journal/decisions archival** in `/complete-milestone` — archives DECISIONS.md and JOURNAL.md into milestone folder, resets for next milestone - **Architecture auto-refresh** in `/complete-milestone` — refreshes ARCHITECTURE.md and STACK.md after milestone completion - **Requirements tracking** — `/plan` loads REQUIREMENTS.md, `/execute` updates requirement status, `/complete-milestone` archives and marks requirements - **Session file reset** in `/new-milestone` — resets DECISIONS.md and JOURNAL.md if they've grown beyond a header - SVG banner in README ### Changed - README updated with `/sprint` commands section, new file structure, command count (29 total) - All references across docs, scripts, and workflows updated for `.agents/skills/` path - `validate-skills.ps1/.sh` updated to scan `.agents/skills/` - `install.md` and `update.md` workflows handle both `.agent/` (workflows) and `.agents/` (skills) ### Fixed - Skills not appearing in Antigravity after updates (closes #10) --- ## [1.4.0] - 2026-01-17 ### Added - **Template Parity** — 8 new templates (22 total) - `architecture.md`, `decisions.md`, `journal.md`, `stack.md` - `phase-summary.md`, `sprint.md`, `todo.md`, `spec.md` - `validate-templates.ps1/.sh` — template validation scripts - `validate-all` now includes template validation --- ## [1.3.0] - 2026-01-17 ### Added - **Validation Scripts** — expanded testing infrastructure - `validate-skills.ps1/.sh` — verify skill directory structure - `validate-all.ps1/.sh` — master script runs all validators - **VERSION file** — single source of truth for version - `/help` now displays current version ### Changed - README.md updated with Testing section --- ## [1.2.0] - 2026-01-17 ### Added - **Cross-Platform Support** — All 16 workflow files now have Bash equivalents - `/web-search` — Search the web for technical research ### Changed - README.md updated with dual-syntax Getting Started (PowerShell + Bash) - README.md added Cross-Platform Support section - Git commands in workflows use `bash` syntax (cross-platform) --- ## [1.1.0] - 2026-01-17 ### Added - **Template Parity** — 14 templates aligned with original repository - `DEBUG.md`, `UAT.md`, `discovery.md`, `requirements.md`, etc. - **Examples** — `.gsd/examples/` directory - `workflow-example.md` — Full workflow walkthrough - `quick-reference.md` — Command cheat sheet - `cross-platform.md` — Platform-specific guidance - `/add-todo` — Quick capture workflow - `/check-todos` — List pending items workflow - `/whats-new` — Show recent changes ### Changed - Workflows now have "Related" sections for discoverability - Cross-linked workflows and skills --- ## [1.0.0] - 2026-01-17 ### Added **Core Workflows (21)** - `/map` — Analyze codebase, generate ARCHITECTURE.md - `/plan` — Create PLAN.md with XML task structure - `/execute` — Wave-based execution with atomic commits - `/verify` — Must-haves validation with empirical proof - `/debug` — Systematic debugging with 3-strike rule - `/new-project` — Deep questioning initialization (10 phases) - `/new-milestone` — Create milestone with phases - `/complete-milestone` — Archive and tag milestone - `/audit-milestone` — Quality review - `/add-phase` — Add phase to roadmap - `/insert-phase` — Insert with renumbering - `/remove-phase` — Remove with safety checks - `/discuss-phase` — Clarify scope before planning - `/research-phase` — Technical deep dive - `/list-phase-assumptions` — Surface assumptions - `/plan-milestone-gaps` — Gap closure plans - `/progress` — Show current position - `/pause` — State preservation - `/resume` — Context restoration - `/add-todo` — Quick capture - `/check-todos` — List todos - `/help` — Command reference **Skills (8)** - `planner` — Task anatomy, goal-backward methodology - `executor` — Atomic commits, Need-to-Know context - `verifier` — Must-haves extraction, evidence requirements - `debugger` — 3-strike rule, systematic diagnosis - `codebase-mapper` — Structure analysis, debt discovery - `plan-checker` — Plan validation before execution - `context-health-monitor` — Prevents context rot - `empirical-validation` — Requires proof for changes **Documentation** - README.md with full methodology explanation - GSD-STYLE.md comprehensive style guide - Templates: PLAN.md, VERIFICATION.md, RESEARCH.md, SUMMARY.md - Examples: workflow-example.md, quick-reference.md, cross-platform.md **Rules** - GEMINI.md with 4 core rules enforcement - Planning Lock, State Persistence, Context Hygiene, Empirical Validation ### Attribution Adapted from [glittercowboy/get-shit-done](https://github.com/glittercowboy/get-shit-done) for Google Antigravity. ================================================ FILE: GSD-STYLE.md ================================================ # GSD-STYLE.md > **Comprehensive reference.** Core rules auto-load from `.gemini/GEMINI.md`. This document provides deep explanations and examples for when you need the full picture. This document explains how GSD is written so future AI instances can contribute consistently. ## Core Philosophy GSD 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: - **Solo developer + AI workflow** (no enterprise patterns) - **Context engineering** (manage the context window deliberately) - **Plans as prompts** (PLAN.md files are executable, not documents to transform) --- ## File Structure Conventions ### Workflows (`.agent/workflows/*.md`) Slash commands the user invokes. Each workflow: - Has YAML frontmatter with `description` - Contains XML-structured process blocks - Ends with "Next Steps" routing ### Skills (`.agents/skills/*/SKILL.md`) Specialized agent behaviors. Each skill: - Has YAML frontmatter with `name` and `description` - Contains detailed methodology - Is referenced by parent workflows ### Templates (`.gsd/templates/*.md`) Reusable document structures. Copy, don't reference. ### References (`.gsd/examples/*.md`) Read-only documentation and examples. --- ## XML Tag Conventions ### Semantic Containers Only Use XML tags for semantic meaning, not formatting: ```markdown You are a GSD executor... Execute all plans in a phase... ## 1. First Step ... ``` ### Task Structure ```xml Clear descriptive name exact/path/to/file.ts Specific implementation instructions. AVOID: common mistake (reason) USE: preferred approach (reason) executable command that proves completion measurable acceptance criteria ``` ### Effort Attribute (Optional) The `effort` attribute hints at task complexity for model selection: | Value | Use Case | Model Hint | |-------|----------|------------| | `low` | Simple edits, formatting | Fast models | | `medium` | Standard implementation (default) | Standard models | | `high` | Complex logic, refactoring | Reasoning models | | `max` | Architecture, security-critical | Deep reasoning | **Default:** `medium` if omitted. No workflow should fail if this attribute is absent. See [docs/model-selection-playbook.md](docs/model-selection-playbook.md) for model selection guidance. ### Checkpoint Structure ```xml Verify UI renders correctly User reviews the rendered component User confirms visual correctness ``` --- ## Language & Tone ### Imperative Voice - ✅ "Create the file" - ❌ "You should create the file" - ❌ "We will create the file" ### No Filler - ✅ "Run `npm test`" - ❌ "Now let's go ahead and run `npm test`" ### No Sycophancy - ✅ "Phase complete." - ❌ "Great job! Phase complete!" ### Brevity with Substance Every sentence should convey information. Remove words that don't add meaning. --- ## Context Engineering ### Size Constraints | Context Usage | Quality | |---------------|---------| | 0-30% | PEAK — Thorough, comprehensive | | 30-50% | GOOD — Confident, solid work | | 50-70% | DEGRADING — Efficiency mode begins | | 70%+ | POOR — Rushed, minimal | **Rule:** Plans should complete within ~50% context. ### Fresh Context Pattern When spawning subprocesses (plans, tasks), they get: - The specific plan being executed - Minimal necessary context from parent files - NO accumulated orchestrator state ### State Preservation STATE.md exists because context windows are temporary. Everything important goes in STATE.md so the next session can continue. --- ## Anti-Patterns to Avoid ### Enterprise Patterns (Banned) ❌ Stakeholder communication ❌ Team coordination ❌ Sprint ceremonies ❌ Multiple approval levels ❌ Separate environments requiring explicit promotion ### Temporal Language (Banned in Implementation Docs) ❌ "First, we'll..." ❌ "Next, we should..." ❌ "Finally, we'll..." ### Generic XML (Banned) ```xml
Authentication ...
Create login endpoint ... ``` ### Vague Tasks (Banned) ```xml Implement authentication Create POST /api/auth/login endpoint. Accept {email, password} JSON body. Query User by email, compare with bcrypt. Return JWT in httpOnly cookie on success. Return 401 on failure. ``` --- ## Commit Conventions ### Format ``` type(scope): description ``` ### Types | Type | Use For | |------|---------| | `feat` | New feature | | `fix` | Bug fix | | `docs` | Documentation | | `refactor` | Code restructure | | `test` | Add tests | | `chore` | Maintenance | ### Rules - One task = one commit - Scope is phase number for phase work - No commit before verification passes --- ## UX Patterns ### Banners ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► STATUS MESSAGE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### "Next Up" Format ``` ─────────────────────────────────────────────────────── ▶ NEXT /command — description ─────────────────────────────────────────────────────── ``` ### Decision Gates When user input needed: ``` ⚠️ DECISION REQUIRED Option A: {description} Option B: {description} Which do you prefer? ``` --- ## Summary: Core Meta-Patterns 1. **Plans are prompts** — PLAN.md is read and executed directly 2. **Fresh context for execution** — Each plan runs in clean context 3. **STATE.md is memory** — Everything important persists there 4. **Verify before done** — No "trust me, it works" 5. **Aggressive atomicity** — Small tasks, atomic commits 6. **No enterprise theater** — Solo dev + AI workflow only ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2026 toonight Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: PROJECT_RULES.md ================================================ # PROJECT_RULES.md — GSD Canonical Rules > **Single Source of Truth** for the Get Shit Done methodology. > > Model-agnostic. All adapters and extensions reference this file. --- ## Core Protocol **SPEC → PLAN → EXECUTE → VERIFY → COMMIT** 1. **SPEC**: Define requirements in `.gsd/SPEC.md` until status is `FINALIZED` 2. **PLAN**: Decompose into phases in `.gsd/ROADMAP.md`, then detailed plans 3. **EXECUTE**: Implement with atomic commits per task 4. **VERIFY**: Prove completion with empirical evidence 5. **COMMIT**: One task = one commit, message format: `type(scope): description` **Planning Lock**: No implementation code until SPEC.md contains "Status: FINALIZED". --- ## Proof Requirements Every change requires verification evidence: | Change Type | Required Proof | |-------------|----------------| | API endpoint | curl/HTTP response | | UI change | Screenshot | | Build/compile | Command output | | Test | Test runner output | | Config | Verification command | **Never accept**: "It looks correct", "This should work", "I've done similar before". **Always require**: Captured output, screenshot, or test result. --- ## Search-First Discipline **Before reading any file completely:** 1. **Search first** — Use grep, ripgrep, or IDE search to find relevant snippets 2. **Evaluate snippets** — Determine if full file read is justified 3. **Targeted reads** — Only read specific line ranges when needed **Benefits:** - Reduces context pollution - Faster understanding of large codebases - Prevents reading irrelevant code **Anti-pattern**: Reading entire files "to understand the context" without searching first. --- ## Wave Execution Plans are grouped into **waves** based on dependencies: | Wave | Characteristic | Execution | |------|----------------|-----------| | 1 | Foundation tasks, no dependencies | Run in parallel | | 2 | Depends on Wave 1 | Wait for Wave 1, then parallel | | 3 | Depends on Wave 2 | Wait for Wave 2, then parallel | **Wave Completion Protocol:** 1. All tasks in wave verified 2. State snapshot created 3. Commit all wave work 4. Update STATE.md with position --- ## State Snapshots At the end of each wave or significant work block, create a state snapshot: ```markdown ## Wave N Summary **Objective:** {what this wave aimed to accomplish} **Changes:** - {change 1} - {change 2} **Files Touched:** - {file1} - {file2} **Verification:** - {command}: {result} **Risks/Debt:** - {any concerns} **Next Wave TODO:** - {item 1} - {item 2} ``` --- ## Model Independence **Absolute Rule**: No rule, workflow, or skill may require a specific model provider. **Allowed:** - Optional adapters with provider-specific enhancements - Capability-based recommendations (e.g., "use a reasoning model for planning") - Examples mentioning specific models as illustrations **Forbidden:** - Hard dependencies on provider features - Breaking behavior when a specific model is unavailable - Duplicating canonical rules in adapters **Adapter Pattern:** ``` adapters/ ├── CLAUDE.md # Optional Claude enhancements ├── GEMINI.md # Optional Gemini enhancements └── GPT_OSS.md # Optional GPT/OSS enhancements ``` Each adapter must begin with: > "Everything in this file is optional. For canonical rules, see PROJECT_RULES.md." --- ## Commit Conventions **Format:** ``` type(scope): description ``` **Types:** | Type | Usage | |------|-------| | `feat` | New feature | | `fix` | Bug fix | | `docs` | Documentation only | | `refactor` | Code restructure (no behavior change) | | `test` | Adding/updating tests | | `chore` | Maintenance, dependencies | **Rules:** - One task = one commit - Verify before commit - Scope = phase number for phase work (e.g., `feat(phase-1): ...`) --- ## Repository Structure ``` PROJECT_RULES.md # ← This file (canonical rules) GSD-STYLE.md # Style and conventions .agent/ └── workflows/ # Slash commands (/plan, /execute, etc.) .agents/ └── skills/ # Agent specializations (Agent Skills standard) .gemini/ # Gemini-specific configuration .gsd/ # Project state and artifacts ├── SPEC.md # Requirements (must be FINALIZED) ├── ROADMAP.md # Phases and progress ├── STATE.md # Session memory ├── templates/ # Document templates └── examples/ # Usage examples adapters/ # Optional model-specific enhancements docs/ # Operational documentation scripts/ # Utility scripts ``` --- ## Context Management **Context Quality Thresholds:** | Usage | Quality | |-------|---------| | 0-30% | **PEAK** — Comprehensive, thorough work | | 30-50% | **GOOD** — Solid, confident output | | 50-70% | **DEGRADING** — Efficiency mode | | 70%+ | **POOR** — Rushed, incomplete | **Context Hygiene Rules:** - Keep plans under 50% context usage - Fresh context for each plan execution - After 3 debugging failures → state dump → fresh session - STATE.md = memory across sessions --- ## Token Efficiency Rules **Goal:** Minimize token consumption while maintaining output quality. ### Loading Rules | Action | Rule | |--------|------| | Before reading file | Search first (grep, ripgrep) | | File >200 lines | Use outline, not full file | | File already understood | Reference summary, don't reload | | >5 files needed | Stop, reconsider approach | ### Budget Thresholds | Usage | Action Required | |-------|-----------------| | 0-50% | Proceed normally | | 50-70% | Switch to outline mode, compress context | | 70%+ | State dump required, recommend fresh session | ### Compression Protocol After understanding a file: 1. Create summary in STATE.md or task notes 2. Reference summary instead of re-reading 3. Only reload specific sections if needed ### Per-Wave Efficiency - Start each wave with minimal context - Load files just-in-time (when task requires) - Compress/summarize before moving to next wave - Document token usage in state snapshots (optional) **Anti-patterns:** - Loading files "just in case" - Re-reading files already understood - Full file reads when snippets suffice - Ignoring budget warnings --- ## Quick Reference ``` Before coding → SPEC.md must be FINALIZED Before file read → Search first, then targeted read After each task → Commit + update STATE.md After each wave → State snapshot After 3 failures → State dump + fresh session Before "Done" → Empirical proof captured ``` --- *GSD Methodology — Model-Agnostic Edition* *Reference implementation for multi-LLM environments* ================================================ FILE: README.md ================================================
Get Shit Done for Antigravity
[![Version](https://img.shields.io/badge/version-1.5.0-00C853?style=flat-square)](CHANGELOG.md) [![License](https://img.shields.io/badge/license-MIT-2196F3?style=flat-square)](LICENSE) [![Based on GSD](https://img.shields.io/badge/based%20on-GSD-7B2D8E?style=flat-square)](https://github.com/glittercowboy/get-shit-done) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20Mac-FF6D00?style=flat-square)](#-cross-platform-support) [![Model Agnostic](https://img.shields.io/badge/models-any%20LLM-E91E63?style=flat-square)](#-multi-model-support)
**Stop vibecoding. Start shipping.** *Describe your idea → GSD extracts everything the AI needs → Watch it build correctly.*
[Getting Started](#-getting-started) · [How It Works](#-how-it-works) · [Commands](#-commands-29-total) · [Documentation](#-documentation)
--- ## 🧠 The Problem > Vibecoding has a bad reputation — and it deserves it. You describe what you want, AI generates code, and you get **inconsistent garbage** that falls apart at scale. GSD fixes that. It's the **context engineering layer** that makes AI coding reliable.
### ❌ Without GSD ``` "Add a feature" → Inconsistent code → Bugs everywhere → Debug loop → Frustration ``` ### ✅ With GSD ``` "Add a feature" → SPEC → Plan → Atomic execution → Verification → ✅ Done ```
> **No enterprise roleplay.** No sprint ceremonies, story points, stakeholder syncs, or Jira workflows. > Just an incredibly effective system for building cool stuff consistently. --- ## 👤 Who This Is For | | | |---|---| | 🧑‍💻 **Solo developers** | Using AI coding assistants and need consistency | | 👥 **Small teams** | Who want structure without enterprise overhead | | 😤 **Anyone** | Tired of AI generating inconsistent garbage | --- ## ⚡ Getting Started
🪟 PowerShell (Windows) ```powershell # Open your project cd your-project # Clone the GSD template git clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-template # Copy to your project Copy-Item -Recurse gsd-template\.agent .\ Copy-Item -Recurse gsd-template\.agents .\ Copy-Item -Recurse gsd-template\.gemini .\ Copy-Item -Recurse gsd-template\.gsd .\ Copy-Item -Recurse gsd-template\adapters .\ Copy-Item -Recurse gsd-template\docs .\ Copy-Item -Recurse gsd-template\scripts .\ Copy-Item -Force gsd-template\PROJECT_RULES.md .\ Copy-Item -Force gsd-template\GSD-STYLE.md .\ Copy-Item -Force gsd-template\model_capabilities.yaml .\ # Clean up Remove-Item -Recurse -Force gsd-template ```
🐧 Bash (Linux / Mac) ```bash # Open your project cd your-project # Clone the GSD template git clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-template # Copy to your project cp -r gsd-template/.agent ./ cp -r gsd-template/.agents ./ cp -r gsd-template/.gemini ./ cp -r gsd-template/.gsd ./ cp -r gsd-template/adapters ./ cp -r gsd-template/docs ./ cp -r gsd-template/scripts ./ cp gsd-template/PROJECT_RULES.md ./ cp gsd-template/GSD-STYLE.md ./ cp gsd-template/model_capabilities.yaml ./ # Clean up rm -rf gsd-template ```
Then run `/new-project` and follow the prompts. > [!TIP] > You can also use `/install` from a clean project to automate the installation above. --- ## 🔄 How It Works ```mermaid graph LR A["🆕 /new-project"] --> B["📋 SPEC.md"] B --> C["💬 /discuss-phase"] C --> D["📐 /plan"] D --> E["⚙️ /execute"] E --> F["✅ /verify"] F --> G{"More\nphases?"} G -- Yes --> C G -- No --> H["🏁 /complete-milestone"] style A fill:#7B2D8E,color:#fff,stroke:none style B fill:#00C853,color:#fff,stroke:none style C fill:#2196F3,color:#fff,stroke:none style D fill:#FF6D00,color:#fff,stroke:none style E fill:#E91E63,color:#fff,stroke:none style F fill:#00C853,color:#fff,stroke:none style G fill:#FFC107,color:#000,stroke:none style H fill:#7B2D8E,color:#fff,stroke:none ``` | Step | Command | Output | |:----:|---------|--------| | **1** | `/new-project` | Deep questioning → `SPEC.md` (finalized) | | **2** | `/discuss-phase N` | Clarify scope → `DECISIONS.md` | | **3** | `/plan N` | Technical discovery → `PLAN.md` with XML tasks | | **4** | `/execute N` | Wave-based execution → Atomic commits | | **5** | `/verify N` | Must-haves check → Evidence captured | | **6** | Repeat | Next phase or `/complete-milestone` | --- ## 🧩 Why It Works ### 📦 Context Engineering The AI is incredibly powerful **if** you give it the context it needs. Most people don't. GSD handles it for you: | File | Role | Icon | |------|------|:----:| | `SPEC.md` | Project vision, always loaded | 🎯 | | `ARCHITECTURE.md` | System understanding | 🏗️ | | `ROADMAP.md` | Where you're going, what's done | 🗺️ | | `STATE.md` | Decisions, blockers, memory across sessions | 💾 | | `PLAN.md` | Atomic tasks with XML structure | 📐 | | `SUMMARY.md` | What happened, what changed | 📝 | > Size limits based on where AI quality degrades. Stay under, get consistent excellence. ### 🏷️ XML Prompt Formatting Every plan is structured XML optimized for AI execution: ```xml Create login endpoint src/app/api/auth/login/route.ts Use jose for JWT (not jsonwebtoken - CommonJS issues). Validate credentials against users table. Return httpOnly cookie on success. curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie Valid credentials return cookie, invalid return 401 ``` Precise instructions. No guessing. Verification built in. ### 🌊 Wave-Based Execution Plans are grouped into waves based on dependencies: ```mermaid graph TD subgraph W1["🌊 Wave 1 — Foundation"] T1["Task A"] & T2["Task B"] & T3["Task C"] end subgraph W2["🌊 Wave 2 — Integration"] T4["Task D"] & T5["Task E"] end subgraph W3["🌊 Wave 3 — Polish"] T6["Task F"] end W1 --> W2 --> W3 style W1 fill:#E3F2FD,stroke:#2196F3,color:#000 style W2 fill:#FFF3E0,stroke:#FF6D00,color:#000 style W3 fill:#F3E5F5,stroke:#7B2D8E,color:#000 style T1 fill:#2196F3,color:#fff,stroke:none style T2 fill:#2196F3,color:#fff,stroke:none style T3 fill:#2196F3,color:#fff,stroke:none style T4 fill:#FF6D00,color:#fff,stroke:none style T5 fill:#FF6D00,color:#fff,stroke:none style T6 fill:#7B2D8E,color:#fff,stroke:none ``` Each executor gets **fresh context**. Your main session stays fast. ### 🔗 Atomic Git Commits Each task gets its own commit immediately after completion: ``` abc123f feat(phase-1): create login endpoint def456g feat(phase-1): add password validation hij789k feat(phase-1): implement JWT cookie handling ``` > **Why?** Git bisect finds exact failing task · Each task independently revertable · Clear history for AI in future sessions ### 🔬 Empirical Verification No "trust me, it works." Every verification produces evidence: | Change Type | Evidence Required | |:---:|:---:| | 🌐 API endpoint | `curl` output | | 🖥️ UI change | Screenshot | | 🏗️ Build | Command output | | 🧪 Tests | Test results | --- ## 🎮 Commands (29 Total) > [!NOTE] > 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. ### 🔵 Core Workflow | Command | Purpose | |---------|---------| | `/map` | 🏗️ Analyze codebase → `ARCHITECTURE.md` | | `/plan [N]` | 📐 Create `PLAN.md` for phase N | | `/execute [N]` | ⚙️ Wave-based execution with atomic commits | | `/verify [N]` | ✅ Must-haves validation with proof | | `/debug [desc]` | 🐛 Systematic debugging (3-strike rule) | ### 🟢 Project Setup | Command | Purpose | |---------|---------| | `/install` | 📦 Install GSD from GitHub | | `/new-project` | 🆕 Deep questioning → `SPEC.md` | | `/new-milestone` | 🏁 Create milestone with phases | | `/complete-milestone` | 🎉 Archive completed milestone | | `/audit-milestone` | 🔍 Review milestone quality | ### 🟠 Phase Management | Command | Purpose | |---------|---------| | `/add-phase` | ➕ Add phase to end of roadmap | | `/insert-phase` | 📌 Insert phase (renumbers) | | `/remove-phase` | ➖ Remove phase (safety checks) | | `/discuss-phase` | 💬 Clarify scope before planning | | `/research-phase` | 🔬 Deep technical research | | `/list-phase-assumptions` | 📋 Surface planning assumptions | | `/plan-milestone-gaps` | 🔧 Create gap closure plans | ### 🟡 Sprint | Command | Purpose | |---------|---------| | `/sprint new` | ⚡ Create a time-boxed sprint for quick focused work | | `/sprint status` | 📊 Show sprint progress | | `/sprint close` | ✅ Close sprint with retrospective | ### 🟣 Navigation & State | Command | Purpose | |---------|---------| | `/progress` | 📊 Show current position | | `/pause` | ⏸️ Save state for session handoff | | `/resume` | ▶️ Restore from last session | | `/add-todo` | 📝 Quick capture idea | | `/check-todos` | 📋 List pending items | ### 🔴 Utilities | Command | Purpose | |---------|---------| | `/help` | ❓ Show all available commands | | `/web-search` | 🌐 Search the web for decisions | | `/whats-new` | 📢 Show recent GSD changes | | `/update` | ⬆️ Update GSD to latest version | --- ## 💡 Typical Session ```bash /resume # ← Load context from last session /progress # ← See where you left off /discuss-phase 2 # ← Clarify requirements (optional) /plan 2 # ← Plan next phase /execute 2 # ← Implement with atomic commits /verify 2 # ← Prove it works (screenshots, tests) /pause # ← Save state for later ``` > [!IMPORTANT] > GSD forces **planning before coding**. The AI can't write code until `SPEC.md` says `FINALIZED`. This prevents building the wrong thing. --- ## 🔒 Core Rules | | Rule | Why It Matters | |:---:|------|----------------| | 🔒 | **Planning Lock** | No code until `SPEC.md` is `FINALIZED` — prevents building wrong thing | | 💾 | **State Persistence** | Update `STATE.md` after every task — memory across sessions | | 🧹 | **Context Hygiene** | 3 failures → state dump → fresh session — prevents circular debugging | | ✅ | **Empirical Validation** | Proof required — no "it should work" | --- ## 🌍 Cross-Platform Support All workflow files include **dual syntax** — both PowerShell and Bash commands. | Platform | Instructions | |:--------:|:------------:| | 🪟 **Windows** | Use PowerShell blocks | | 🐧 **Linux / Mac** | Use Bash blocks (may require `jq`) | > Git commands (`git add`, `git commit`, `git tag`) are cross-platform and work identically everywhere. --- ## 🤖 Multi-Model Support GSD is **model-agnostic** — use any LLM that works in your environment. ### Canonical Rules All rules live in [PROJECT_RULES.md](PROJECT_RULES.md) — the single source of truth. ### Optional Adapters Model-specific enhancements *(optional, never required)*: ``` adapters/ ├── CLAUDE.md # Extended thinking, effort levels ├── GEMINI.md # Flash vs Pro selection └── GPT_OSS.md # Function calling, context handling ``` ### Model Selection by Phase | Phase | Recommended | Why | |:-----:|:-----------:|-----| | 📋 Planning | Reasoning models | Complex decisions | | ⚙️ Implementation | Fast models | Iteration speed | | 🐛 Debugging | Reasoning models | Hypothesis testing | | 🔍 Review | Long-context models | Full diff analysis | > See [model-selection-playbook.md](docs/model-selection-playbook.md) for detailed guidance. --- ## 🔍 Search-First Mode > **Principle:** Search before reading files completely. ### Why? - 🎯 Reduces context pollution - ⚡ Faster codebase understanding - 🚫 Prevents reading irrelevant code
Setup (Optional) **PowerShell:** ```powershell .\scripts\setup_search.ps1 # Checks for ripgrep/fd .\scripts\search_repo.ps1 "pattern" # Search wrapper ``` **Bash:** ```bash ./scripts/setup_search.sh # Checks for ripgrep/fd ./scripts/search_repo.sh "pattern" # Search wrapper ``` > **No installation required** — falls back to built-in tools (`Select-String` / `grep`).
### Workflow 1. **Define question** — What are you looking for? 2. **Search first** — `.\scripts\search_repo.ps1 "keyword"` 3. **Evaluate results** — Which files matter? 4. **Targeted read** — Only read relevant sections --- ## 💰 Token Optimization > **Principle:** Minimize token consumption while maintaining quality. ### Skills Available | Skill | Purpose | |-------|---------| | 📊 `token-budget` | Track and manage token usage | | 🗜️ `context-compressor` | Compress context for efficiency | | 🔍 `context-fetch` | Search-first loading | | 🩺 `context-health-monitor` | Detect quality degradation | ### Budget Thresholds | Usage | Status | Action | |:-----:|:------:|--------| | 0–50% | 🟢 OK | Proceed normally | | 50–70% | 🟡 Warning | Compress, use outlines | | 70%+ | 🔴 Critical | State dump required | > See [token-optimization-guide.md](docs/token-optimization-guide.md) for complete strategies. --- ## 📁 File Structure ``` 📄 PROJECT_RULES.md # ← Canonical rules (model-agnostic) 📄 GSD-STYLE.md # Complete style guide 📂 .agent/ └── 📂 workflows/ # 27 slash commands 📂 .agents/ └── 📂 skills/ # 11 agent specializations (Agent Skills standard) 📂 .gemini/ └── 📄 GEMINI.md # Gemini integration 📂 .gsd/ ├── 📄 SPEC.md # ← START HERE (finalize first) ├── 📄 ROADMAP.md # Phases and progress ├── 📄 STATE.md # Session memory ├── 📄 ARCHITECTURE.md # System design (/map output) ├── 📄 STACK.md # Tech inventory ├── 📄 DECISIONS.md # Architecture Decision Records ├── 📄 JOURNAL.md # Session log ├── 📄 TODO.md # Quick capture ├── 📂 templates/ # Document templates └── 📂 examples/ # Usage walkthroughs 📂 adapters/ # Optional model-specific enhancements ├── 📄 CLAUDE.md ├── 📄 GEMINI.md └── 📄 GPT_OSS.md 📂 docs/ # Operational documentation ├── 📄 model-selection-playbook.md └── 📄 runbook.md 📂 scripts/ # Utility scripts ├── 📄 validate-*.ps1/.sh # Structure validators ├── 📄 setup_search.ps1/.sh # Search tool setup └── 📄 search_repo.ps1/.sh # Search wrapper 📄 model_capabilities.yaml # Optional capability registry ``` --- ## 🧪 Testing Run validation scripts to verify GSD structure:
🪟 PowerShell ```powershell .\scripts\validate-all.ps1 # Run all validators .\scripts\validate-workflows.ps1 # Workflows only .\scripts\validate-skills.ps1 # Skills only ```
🐧 Bash ```bash ./scripts/validate-all.sh # Run all validators ./scripts/validate-workflows.sh # Workflows only ./scripts/validate-skills.sh # Skills only ```
--- ## 📚 Documentation | Resource | Description | |----------|-------------| | [PROJECT_RULES.md](PROJECT_RULES.md) | Canonical model-agnostic rules | | [GSD-STYLE.md](GSD-STYLE.md) | Complete style and conventions guide | | [Model Selection Playbook](docs/model-selection-playbook.md) | Model selection guidance | | [Runbook](docs/runbook.md) | Operational procedures | | [Token Optimization Guide](docs/token-optimization-guide.md) | Token efficiency strategies | | [Examples](.gsd/examples/) | Usage walkthroughs and quick reference | | [Templates](.gsd/templates/) | Document templates for plans, verification | --- ## 🧠 Philosophy
🎯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
---
Adapted from glittercowboy/get-shit-done for Google Antigravity
[![GitHub](https://img.shields.io/badge/GitHub-toonight-181717?style=flat-square&logo=github)](https://github.com/toonight/get-shit-done-for-antigravity)
================================================ FILE: VERSION ================================================ 1.5.0 ================================================ FILE: adapters/CLAUDE.md ================================================ # Claude Adapter > **Everything in this file is optional.** > For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md). This adapter provides optional enhancements for Claude models in Antigravity. --- ## Extended Thinking Mode When available, activate extended thinking for: | Task Type | Recommended | |-----------|-------------| | Architecture planning | ✅ High effort | | Complex debugging | ✅ High effort | | Security analysis | ✅ High effort | | Simple edits | ❌ Not needed | | Quick iterations | ❌ Overhead too high | ### Effort Levels If the model supports effort/budget levels: | Level | Use Case | |-------|----------| | `low` | Simple edits, formatting, comments | | `medium` | Standard implementation (default) | | `high` | Complex logic, refactoring, debugging | | `max` | Architecture, security, critical decisions | **Default:** `medium` if not specified. --- ## Artifacts Mode When artifacts are supported: - Use for code generation that needs preview - Use for documentation with formatting - Avoid for small inline edits --- ## Context Optimization Claude-specific context tips: 1. **System prompt loading**: Core rules in system prompt, task details in user message 2. **XML structure**: Claude parses XML well — use task XML format from GSD-STYLE.md 3. **Conversation history**: Minimal history preferred; use STATE.md for continuity --- ## File Conventions Not required, but if organizing Claude-specific files: ``` .claude/ ├── CLAUDE.md # This adapter (if using) └── settings.json # IDE-specific settings ``` --- ## Anti-Patterns ❌ **Using max effort for everything** — Slow and expensive ❌ **Skipping verification** — Thinking mode doesn't guarantee correctness ❌ **Depending on artifacts** — Not all Claude interfaces support them --- *See PROJECT_RULES.md for canonical requirements.* ================================================ FILE: adapters/GEMINI.md ================================================ # Gemini Adapter > **Everything in this file is optional.** > For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md). This adapter provides optional enhancements for Gemini models in Antigravity. --- ## Model Selection ### Flash vs Pro | Model Type | Best For | |------------|----------| | **Flash** | Quick iterations, simple edits, high-volume tasks | | **Pro** | Complex planning, large refactors, deep analysis | **Default recommendation:** Start with Pro for planning, switch to Flash for implementation. --- ## Context Window Optimization Gemini models often have large context windows. Optimize usage: 1. **Load full files strategically** — Large context allows it, but still prefer search-first 2. **Batch related files** — Group related code in single context load 3. **Clear separation** — Use XML tags to separate file contents ### Context Loading Pattern ```xml {file contents} {file contents} {your task here} ``` --- ## Grounding When available, use grounding for: - Checking latest documentation - Verifying API behaviors - Validating external service states **Not for:** Code implementation (use codebase content). --- ## Code Execution If code execution sandbox is available: - Use for verification commands - Use for testing snippets - Document outputs in SUMMARY.md --- ## Integration with .gemini/ The `.gemini/GEMINI.md` file can reference this adapter: ```markdown # In .gemini/GEMINI.md For canonical rules, see PROJECT_RULES.md. For Gemini-specific tips, see adapters/GEMINI.md. ``` --- ## Anti-Patterns ❌ **Loading entire codebase** — Even with large context, quality degrades ❌ **Ignoring context thresholds** — 50% is still the quality boundary ❌ **Skipping STATE.md** — Context window size doesn't replace persistent state --- *See PROJECT_RULES.md for canonical requirements.* ================================================ FILE: adapters/GPT_OSS.md ================================================ # GPT & Open Source Models Adapter > **Everything in this file is optional.** > For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md). This adapter provides guidance for GPT models and open-source alternatives. --- ## GPT Models ### Model Selection | Model | Best For | |-------|----------| | **GPT-4o** | Balanced speed and quality, multimodal | | **GPT-4 Turbo** | Complex reasoning, large context | | **GPT-3.5** | Fast iterations, simple tasks | --- ### Function Calling When function calling is available: ```json { "name": "run_verification", "description": "Execute a verification command", "parameters": { "command": "npm test", "expected": "All tests pass" } } ``` **Use for:** - Verification commands - File operations - External service checks --- ### Context Optimization GPT models may have smaller context than some alternatives: 1. **Be selective** — Only load necessary files 2. **Use search-first** — Critical for context efficiency 3. **Summarize large files** — Extract relevant sections only --- ## Open Source Models ### General Guidance Open source models vary widely. General tips: | Consideration | Guidance | |---------------|----------| | **Context length** | Verify model's limit; adjust file loading | | **Instruction following** | Use explicit, structured prompts | | **Code quality** | May need more verification steps | | **Speed** | Varies by hardware; plan accordingly | --- ### Local Deployment For locally-running models: 1. **Resource planning** — Ensure adequate GPU/RAM 2. **Latency expectations** — Adjust iteration speed assumptions 3. **Fallback strategy** — Document when to switch to cloud models --- ### Recommended Patterns **Structured prompts work better:** ```markdown ## Task {clear task description} ## Context {relevant code snippets} ## Expected Output {what you need back} ## Constraints {any limitations or requirements} ``` --- ## Shorter Context Strategies When working with limited context: 1. **Aggressive search-first** — Never load full files blindly 2. **Incremental loading** — Add context as needed, not upfront 3. **State snapshots more frequently** — Prevent context overflow 4. **Split large tasks** — Smaller plans, more waves --- ## Anti-Patterns ❌ **Assuming GPT-4 context** — Verify actual model limits ❌ **Complex nested prompts** — Keep structure flat and clear ❌ **Ignoring model limits** — Quality crashes hard past context limit --- ## Model-Specific Files Not required, but if organizing: ``` .openai/ # For OpenAI API configuration .ollama/ # For Ollama local models .llm/ # Generic local LLM config ``` --- *See PROJECT_RULES.md for canonical requirements.* ================================================ FILE: docs/model-selection-playbook.md ================================================ # Model Selection Playbook > Guidance for choosing models by phase and task type. > > **No model is required.** These are recommendations, not requirements. --- ## Selection by Phase ### Planning & Architecture **Recommended capabilities:** - Extended reasoning / thinking mode - Large context window (analyze multiple files) - Strong at structured output (specs, plans) **Why:** Planning requires understanding full system context and making architectural decisions. **Examples:** Models with "thinking" or "reasoning" modes, larger context variants. --- ### Code Implementation **Recommended capabilities:** - Fast iteration speed - Good at code completion - Tool/function calling (for verification commands) **Why:** Implementation involves many small changes with frequent verification cycles. **Examples:** Speed-tier models, code-specialized variants. --- ### Refactoring **Recommended capabilities:** - Large context window (see before/after) - Pattern recognition - Consistent style application **Why:** Refactoring requires maintaining consistency across large code changes. **Examples:** Standard or long-context variants. --- ### Debugging **Recommended capabilities:** - Extended reasoning (hypothesis generation) - Good at reading stack traces - Context for error patterns **Why:** Debugging requires hypothesis testing and pattern matching. **Examples:** Reasoning-focused models. --- ### Code Review **Recommended capabilities:** - Large context (review full PR diff) - Security pattern knowledge - Style consistency checking **Why:** Review requires seeing both code and context together. **Examples:** Long-context variants. --- ## Capability Tiers | Tier | Characteristics | Best For | |------|-----------------|----------| | **Fast** | Quick responses, lower cost | Implementation, iteration | | **Standard** | Balanced speed/quality | Most tasks | | **Reasoning** | Extended thinking, slower | Planning, debugging, architecture | | **Long-context** | >100k tokens | Review, refactoring | --- ## Anti-Patterns ❌ **Using reasoning models for simple edits** — Overkill, slow, expensive ❌ **Using fast models for architecture** — Insufficient depth for complex decisions ❌ **Ignoring context limits** — Leads to quality degradation ❌ **Forcing a specific model** — Breaks model-agnosticism --- ## Model Switching Mid-Session **When to switch:** - Context is getting polluted (approaching 50%) - Task type changes significantly (planning → implementation) - Current model struggling with task type **How to switch:** 1. Create state snapshot 2. Update STATE.md with current position 3. Start fresh session with appropriate model 4. Load STATE.md to resume --- ## GSD Model-Agnostic Principle GSD works with any capable LLM. The methodology compensates for model differences through: 1. **Structured plans** — Reduce ambiguity 2. **Explicit verification** — Catch errors regardless of model 3. **State persistence** — Enable model switching 4. **Fresh context** — Prevent accumulation issues Choose models based on task needs, not methodology requirements. --- *See PROJECT_RULES.md for canonical rules.* *See docs/runbook.md for operational procedures.* ================================================ FILE: docs/runbook.md ================================================ # GSD Runbook > Operational procedures for debugging, validation, and recovery. --- ## Quick Commands ### Status Check **PowerShell:** ```powershell # Current git status git status # Recent commits git log --oneline -10 # Current branch git branch --show-current ``` **Bash:** ```bash # Current git status git status # Recent commits git log --oneline -10 # Current branch git branch --show-current ``` --- ## Wave Validation ### Verify Wave Completion **Before marking a wave complete:** 1. All tasks have commits: ```powershell git log --oneline -N # N = number of tasks in wave ``` 2. All verifications passed (documented in SUMMARY.md) 3. STATE.md updated with current position 4. State snapshot created ### Wave Rollback **If a wave needs to be reverted:** ```powershell # Find commit before wave started git log --oneline -20 # Reset to that commit (keeps changes staged) git reset --soft # Or hard reset (discards changes) git reset --hard ``` --- ## Debugging Procedures ### 3-Strike Rule After 3 consecutive failed debug attempts: 1. **Stop** — Don't try a 4th approach in same session 2. **Document** in STATE.md: ```markdown ## Debug Session **Problem:** {description} **Attempts:** 1. {approach 1} → {result} 2. {approach 2} → {result} 3. {approach 3} → {result} **Hypothesis:** {current theory} **Recommended next:** {suggested approach} ``` 3. **Fresh session** — Start new conversation with documented context ### Log Inspection **Find relevant logs:** ```powershell # Search for error patterns Select-String -Path "*.log" -Pattern "error|exception|failed" -CaseSensitive:$false ``` ```bash # Search for error patterns grep -ri "error\|exception\|failed" *.log ``` --- ## Verification Commands ### Build Verification ```powershell # Node.js npm run build if ($LASTEXITCODE -eq 0) { Write-Host "✅ Build passed" } # Python python -m py_compile src/**/*.py ``` ### Test Verification ```powershell # Node.js npm test # Python pytest -v # Go go test ./... ``` ### Lint Verification ```powershell # Node.js npm run lint # Python ruff check . # Go golangci-lint run ``` --- ## State Recovery ### From STATE.md When resuming work: 1. Read STATE.md for current position 2. Check "Last Action" for context 3. Follow "Next Steps" to continue 4. Verify recent commits match documented progress ### From Git History If STATE.md is outdated: ```powershell # See recent work git log --oneline -20 # Check specific commit details git show --stat # View file at specific commit git show :path/to/file ``` ### Context Pollution Recovery If quality is degrading mid-session: 1. Create state snapshot immediately 2. Update STATE.md with full context 3. Commit any pending work 4. Start fresh session 5. Run `/resume` to reload context --- ## Search Commands ### Find in Codebase **PowerShell:** ```powershell # Find pattern in files Select-String -Path "src/**/*.ts" -Pattern "TODO" -Recurse # Find files by name Get-ChildItem -Recurse -Filter "*.config.*" ``` **Bash:** ```bash # Find pattern in files (with ripgrep) rg "TODO" --type ts # Find pattern in files (with grep) grep -r "TODO" src/ # Find files by name find . -name "*.config.*" ``` ### Search-First Workflow Before reading any file: 1. Search for relevant terms: ```powershell Select-String -Path "**/*.md" -Pattern "architecture" -Recurse ``` 2. Identify candidate files from results 3. Read only relevant sections: ```powershell Get-Content file.md | Select-Object -Skip 49 -First 20 # Lines 50-70 ``` --- ## Common Issues ### "SPEC.md not FINALIZED" **Cause:** Planning lock prevents implementation **Fix:** 1. Open `.gsd/SPEC.md` 2. Complete all required sections 3. Change status to `Status: FINALIZED` 4. Retry command ### "Context degrading" **Symptoms:** Shorter responses, skipped steps, inconsistency **Fix:** 1. Create state snapshot 2. Commit current work 3. Start fresh session 4. Run `/resume` ### "Commit failed" **Causes:** Staged conflicts, hook failures **Debug:** ```powershell git status git diff --staged ``` --- ## Checklist Templates ### Pre-Execution Checklist - [ ] SPEC.md is FINALIZED - [ ] ROADMAP.md has current phase - [ ] STATE.md loaded and understood - [ ] Previous wave verified complete ### Post-Wave Checklist - [ ] All tasks committed - [ ] Verifications documented - [ ] STATE.md updated - [ ] State snapshot created - [ ] No uncommitted changes ### Session End Checklist - [ ] Current work committed - [ ] STATE.md has "Next Steps" - [ ] JOURNAL.md updated (if milestone) - [ ] No loose ends --- *See PROJECT_RULES.md for canonical rules.* *See docs/model-selection-playbook.md for model guidance.* ================================================ FILE: docs/token-optimization-guide.md ================================================ # Token Optimization Guide > Practical strategies for reducing token consumption while maintaining quality. --- ## Why Token Optimization Matters | Issue | Impact | |-------|--------| | Excessive file loading | Higher costs, slower responses | | Context accumulation | Quality degradation after 50% | | Re-reading files | Wasted tokens on understood content | | Full files when snippets suffice | 10x token usage | **Goal:** Maximize output quality per token spent. --- ## The Token Efficiency Stack ``` ┌─────────────────────────────────────┐ │ 1. Search-First (context-fetch) │ ← Find before loading ├─────────────────────────────────────┤ │ 2. Budget Tracking (token-budget) │ ← Know your limits ├─────────────────────────────────────┤ │ 3. Compression (context-compressor)│ ← Minimize footprint ├─────────────────────────────────────┤ │ 4. Health Monitoring │ ← Prevent degradation └─────────────────────────────────────┘ ``` --- ## Quick Reference: Token Costs ### By Content Type | Type | Tokens/Line | 100 Lines = | |------|-------------|-------------| | Dense code | 6 | ~600 tokens | | Standard code | 4 | ~400 tokens | | Markdown | 3 | ~300 tokens | | Sparse YAML | 2 | ~200 tokens | ### By File Size | File Lines | Strategy | |------------|----------| | <50 | Load freely | | 50-200 | Outline first | | 200-500 | Search + snippets | | 500+ | Never load fully | --- ## Optimization Patterns ### Pattern 1: Search → Outline → Target ``` Step 1: Search for "handlePayment" → Found in: payment.ts:45, checkout.ts:120 Step 2: Get outline of payment.ts → L45-80: handlePayment function Step 3: Load only L45-80 → 35 lines (~140 tokens) vs 400 lines (~1600 tokens) → Saved: ~90% ``` ### Pattern 2: Summarize After Understanding ``` After reading auth.ts: ## Summary: auth.ts - Exports: login, logout, validateToken - Pattern: Express middleware - DB: queries users table - JWT: uses jose library Next time: Reference summary, don't reload ``` ### Pattern 3: Progressive Disclosure ``` Need: Understand login flow Level 1: Outline → "login at L45, uses validateCredentials at L67" → Often sufficient Level 2: Key function → Load L45-65 only → Understand core logic Level 3: Dependencies → Load validateCredentials (L67-85) → Only if L2 insufficient Level 4: Full file → Last resort, re-compress after ``` --- ## Anti-Patterns to Avoid ### ❌ The "Context Dump" ``` BAD: "Let me read all the files in src/ to understand the project" → 50 files × 200 lines × 4 tokens = 40,000 tokens GOOD: "Let me search for 'main entry' and 'router'" → 2 targeted searches, ~500 tokens ``` ### ❌ The "Just In Case" Load ``` BAD: "Loading utils.ts in case I need it later" → Probably won't need it, wasted tokens GOOD: "Noting utils.ts exists, will load if needed" → Zero tokens until actually needed ``` ### ❌ The Re-Read ``` BAD: "Reading config.ts again to check the port" → Already read it twice = 1200 tokens GOOD: "From my earlier analysis, port is on L15" → Zero additional tokens ``` --- ## Budget Checkpoints ### Before Starting Work ```markdown □ Do I know my current budget usage? □ Have I tried searching before loading? □ Am I loading files I've already understood? ``` ### During Execution ```markdown □ Am I at >50%? Time to compress. □ Am I re-reading files? Use summaries. □ Can I use outline instead of full file? ``` ### After Each Wave ```markdown □ Have I compressed context for next wave? □ Are summaries documented in STATE.md? □ Would a fresh session be more efficient? ``` --- ## Integration with GSD | GSD Workflow | Token Optimization | |--------------|-------------------| | `/map` | Generate outline, not full read | | `/plan` | Budget estimate per task | | `/execute` | Load minimal per task | | `/verify` | Targeted evidence only | | `/pause` | Compress and dump state | --- ## Metrics Track these for improvement: | Metric | Good | Poor | |--------|------|------| | Files fully loaded | <3 per wave | 10+ | | Search:Load ratio | 3:1 | 1:3 | | Re-reads | 0 | 3+ | | Budget at wave end | <50% | >70% | --- *See also:* - *[.agents/skills/token-budget/SKILL.md](.agents/skills/token-budget/SKILL.md)* - *[.agents/skills/context-compressor/SKILL.md](.agents/skills/context-compressor/SKILL.md)* - *[PROJECT_RULES.md](PROJECT_RULES.md) — Token Efficiency Rules* ================================================ FILE: model_capabilities.yaml ================================================ # Model Capabilities Registry # # This file is OPTIONAL. GSD works without it. # If present, it provides guidance for model selection. # # Usage: Reference this file when choosing models by capability. # Do NOT make any workflow depend on this file existing. # Capability definitions capabilities: thinking_mode: description: "Extended reasoning with internal monologue" benefits: - Better for complex planning - Improved debugging hypotheses - More thorough architecture analysis long_context: description: "Context window > 100k tokens" benefits: - Can analyze multiple files at once - Better for large refactors - Full codebase reviews tools: description: "Function/tool calling support" benefits: - Execute verification commands - Interact with external systems - Structured outputs speed_tier: description: "Response latency tier" values: - fast: "< 2s average, good for iteration" - standard: "2-5s average, balanced" - reasoning: "> 5s average, deep analysis" # Example model profiles (illustrative, not exhaustive) # These show how to categorize models by capability type. profiles: # Fast iteration models fast_coder: speed_tier: fast thinking_mode: false long_context: false tools: true best_for: - Quick edits - Simple implementations - Frequent iteration cycles examples: - "Flash/Turbo variants" - "Smaller parameter models" # Standard balanced models standard: speed_tier: standard thinking_mode: false long_context: true tools: true best_for: - Most development tasks - Moderate refactoring - General coding examples: - "Pro/Standard variants" - "Mid-tier models" # Deep reasoning models reasoning: speed_tier: reasoning thinking_mode: true long_context: true tools: true best_for: - Architecture planning - Complex debugging - Security analysis examples: - "Thinking/Reasoning variants" - "Advanced reasoning models" # Phase recommendations (suggestions, not requirements) phase_recommendations: planning: preferred_profile: reasoning reason: "Complex decisions benefit from extended thinking" implementation: preferred_profile: fast_coder reason: "Frequent iteration needs speed" refactoring: preferred_profile: standard reason: "Balance of context and speed" debugging: preferred_profile: reasoning reason: "Hypothesis generation needs depth" review: preferred_profile: standard reason: "Large context for full diffs" # IMPORTANT: This file is for guidance only. # Never fail a workflow because a specific model capability is missing. ================================================ FILE: scripts/search_repo.ps1 ================================================ # search_repo.ps1 - Search codebase with best available tool # # Usage: .\scripts\search_repo.ps1 [path] [options] # # Examples: # .\scripts\search_repo.ps1 "TODO" # .\scripts\search_repo.ps1 "function.*login" -Path "src/" # .\scripts\search_repo.ps1 "error" -FileType "ts" param( [Parameter(Mandatory = $true, Position = 0)] [string]$Pattern, [Parameter(Position = 1)] [string]$Path = ".", [Parameter()] [string]$FileType, [Parameter()] [switch]$CaseSensitive ) # Try ripgrep first (fastest) $rgAvailable = Get-Command rg -ErrorAction SilentlyContinue if ($rgAvailable) { Write-Host "# Using ripgrep" -ForegroundColor Gray $rgArgs = @($Pattern, $Path, "--color=always") if ($FileType) { $rgArgs += "--type" $rgArgs += $FileType } if ($CaseSensitive) { $rgArgs += "--case-sensitive" } & rg @rgArgs exit $LASTEXITCODE } # Fall back to Select-String Write-Host "# Using Select-String (install ripgrep for better performance)" -ForegroundColor Gray $searchParams = @{ Pattern = $Pattern Path = $Path } # Build file filter if ($FileType) { $searchParams.Include = "*.$FileType" } if (-not $CaseSensitive) { $searchParams.CaseSensitive = $false } # Handle directory vs file if (Test-Path $Path -PathType Container) { $searchParams.Path = Join-Path $Path "*" $searchParams.Recurse = $true } try { $results = Get-ChildItem -Path $Path -Recurse -File -ErrorAction SilentlyContinue | Where-Object { if ($FileType) { $_.Extension -eq ".$FileType" } else { $true } } | Select-String -Pattern $Pattern -CaseSensitive:$CaseSensitive if ($results) { $results | ForEach-Object { $relativePath = $_.Path $lineNum = $_.LineNumber $line = $_.Line Write-Host "${relativePath}:${lineNum}:${line}" } } else { Write-Host "No matches found for: $Pattern" } } catch { Write-Host "Search error: $_" -ForegroundColor Red exit 1 } ================================================ FILE: scripts/search_repo.sh ================================================ #!/bin/bash # search_repo.sh - Search codebase with best available tool # # Usage: ./scripts/search_repo.sh [path] [options] # # Examples: # ./scripts/search_repo.sh "TODO" # ./scripts/search_repo.sh "function.*login" src/ # ./scripts/search_repo.sh "error" --type ts set -e PATTERN="${1:-}" SEARCH_PATH="${2:-.}" shift 2 2>/dev/null || true EXTRA_ARGS="$@" if [[ -z "$PATTERN" ]]; then echo "Usage: search_repo.sh [path] [options]" echo "" echo "Examples:" echo " ./scripts/search_repo.sh 'TODO'" echo " ./scripts/search_repo.sh 'login' src/" echo " ./scripts/search_repo.sh 'error' . --type ts" exit 1 fi # Try ripgrep first (fastest) if command -v rg &> /dev/null; then echo "# Using ripgrep" >&2 rg "$PATTERN" "$SEARCH_PATH" $EXTRA_ARGS --color=always exit $? fi # Fall back to grep echo "# Using grep (install ripgrep for better performance)" >&2 # Convert common rg options to grep options GREP_ARGS="" for arg in $EXTRA_ARGS; do case "$arg" in --type) # Next argument is the type, skip both ;; ts|js|py|go|rs|md) GREP_ARGS="$GREP_ARGS --include=*.$arg" ;; *) # Pass through other arguments GREP_ARGS="$GREP_ARGS $arg" ;; esac done grep -rn "$PATTERN" "$SEARCH_PATH" $GREP_ARGS --color=always 2>/dev/null || { echo "No matches found for: $PATTERN" exit 0 } ================================================ FILE: scripts/setup_search.ps1 ================================================ # setup_search.ps1 - Optional search tool setup for GSD # # This script checks for and provides guidance on installing search tools. # GSD works without these tools (falls back to Select-String), but they improve performance. Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host " GSD ► Search Tools Setup" -ForegroundColor Cyan Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host "" $rgInstalled = $false $fdInstalled = $false # Check for ripgrep Write-Host "Checking search tools..." -ForegroundColor White Write-Host "" try { $rgVersion = & rg --version 2>$null if ($rgVersion) { Write-Host "✅ ripgrep (rg) is installed: $($rgVersion[0])" -ForegroundColor Green $rgInstalled = $true } } catch { Write-Host "❌ ripgrep (rg) is not installed" -ForegroundColor Yellow } # Check for fd try { $fdVersion = & fd --version 2>$null if ($fdVersion) { Write-Host "✅ fd is installed: $fdVersion" -ForegroundColor Green $fdInstalled = $true } } catch { Write-Host "❌ fd is not installed" -ForegroundColor Yellow } Write-Host "" if ($rgInstalled -and $fdInstalled) { Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Green Write-Host " ✅ All search tools are ready!" -ForegroundColor Green Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Green Write-Host "" Write-Host "You can use .\scripts\search_repo.ps1 for optimized searching." } else { Write-Host "⚠️ Some tools are missing (optional)" -ForegroundColor Yellow Write-Host "" Write-Host "GSD will work fine with built-in Select-String, but ripgrep and fd" Write-Host "provide faster searching in large codebases." Write-Host "" Write-Host "───────────────────────────────────────────────────────" -ForegroundColor Gray Write-Host "📦 Installation Options" -ForegroundColor White Write-Host "───────────────────────────────────────────────────────" -ForegroundColor Gray Write-Host "" # Check for package managers $hasWinget = Get-Command winget -ErrorAction SilentlyContinue $hasChoco = Get-Command choco -ErrorAction SilentlyContinue $hasScoop = Get-Command scoop -ErrorAction SilentlyContinue if ($hasWinget) { Write-Host "Using winget:" -ForegroundColor Cyan Write-Host " winget install BurntSushi.ripgrep.MSVC" Write-Host " winget install sharkdp.fd" Write-Host "" } if ($hasChoco) { Write-Host "Using Chocolatey:" -ForegroundColor Cyan Write-Host " choco install ripgrep fd" Write-Host "" } if ($hasScoop) { Write-Host "Using Scoop:" -ForegroundColor Cyan Write-Host " scoop install ripgrep fd" Write-Host "" } if (-not ($hasWinget -or $hasChoco -or $hasScoop)) { Write-Host "Download binaries from:" -ForegroundColor Cyan Write-Host " ripgrep: https://github.com/BurntSushi/ripgrep/releases" Write-Host " fd: https://github.com/sharkdp/fd/releases" Write-Host "" } Write-Host "───────────────────────────────────────────────────────" -ForegroundColor Gray Write-Host "" Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host " GSD ► Using Select-String as fallback (works fine!)" -ForegroundColor Cyan Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan } ================================================ FILE: scripts/setup_search.sh ================================================ #!/bin/bash # setup_search.sh - Optional search tool setup for GSD # # This script checks for and optionally installs search tools. # GSD works without these tools (falls back to grep), but they improve performance. set -e echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " GSD ► Search Tools Setup" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" # Check for ripgrep check_ripgrep() { if command -v rg &> /dev/null; then echo "✅ ripgrep (rg) is installed: $(rg --version | head -n1)" return 0 else echo "❌ ripgrep (rg) is not installed" return 1 fi } # Check for fd check_fd() { if command -v fd &> /dev/null; then echo "✅ fd is installed: $(fd --version)" return 0 elif command -v fdfind &> /dev/null; then echo "✅ fd is installed (as fdfind): $(fdfind --version)" return 0 else echo "❌ fd is not installed" return 1 fi } # Installation suggestions suggest_install() { echo "" echo "───────────────────────────────────────────────────────" echo "📦 Installation Options" echo "───────────────────────────────────────────────────────" echo "" # Detect OS if [[ "$OSTYPE" == "darwin"* ]]; then echo "macOS detected. Install with Homebrew:" echo " brew install ripgrep fd" elif [[ -f /etc/debian_version ]]; then echo "Debian/Ubuntu detected. Install with apt:" echo " sudo apt install ripgrep fd-find" echo " # Note: fd is installed as 'fdfind' on Debian" elif [[ -f /etc/fedora-release ]]; then echo "Fedora detected. Install with dnf:" echo " sudo dnf install ripgrep fd-find" elif [[ -f /etc/arch-release ]]; then echo "Arch Linux detected. Install with pacman:" echo " sudo pacman -S ripgrep fd" else echo "Install from source or package manager:" echo " ripgrep: https://github.com/BurntSushi/ripgrep" echo " fd: https://github.com/sharkdp/fd" fi echo "" echo "───────────────────────────────────────────────────────" } # Main echo "Checking search tools..." echo "" RG_OK=0 FD_OK=0 check_ripgrep && RG_OK=1 check_fd && FD_OK=1 echo "" if [[ $RG_OK -eq 1 && $FD_OK -eq 1 ]]; then echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " ✅ All search tools are ready!" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" echo "You can use ./scripts/search_repo.sh for optimized searching." exit 0 else echo "⚠️ Some tools are missing (optional)" echo "" echo "GSD will work fine with built-in grep, but ripgrep and fd" echo "provide faster searching in large codebases." suggest_install echo "" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " GSD ► Using grep as fallback (works fine!)" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" exit 0 fi ================================================ FILE: scripts/validate-all.ps1 ================================================ # GSD Master Validation Script # Runs all validators and reports overall status $TotalErrors = 0 Write-Host "" Write-Host "╔═══════════════════════════════════════════════════════╗" -ForegroundColor Magenta Write-Host "║ GSD ► RUNNING ALL VALIDATORS ║" -ForegroundColor Magenta Write-Host "╚═══════════════════════════════════════════════════════╝" -ForegroundColor Magenta Write-Host "" # Run workflow validator Write-Host "▶ Running workflow validation..." -ForegroundColor Cyan & "$PSScriptRoot\validate-workflows.ps1" if ($LASTEXITCODE -ne 0) { $TotalErrors++ } Write-Host "" # Run skill validator Write-Host "▶ Running skill validation..." -ForegroundColor Cyan & "$PSScriptRoot\validate-skills.ps1" if ($LASTEXITCODE -ne 0) { $TotalErrors++ } Write-Host "" # Run template validator Write-Host "▶ Running template validation..." -ForegroundColor Cyan & "$PSScriptRoot\validate-templates.ps1" if ($LASTEXITCODE -ne 0) { $TotalErrors++ } Write-Host "" # Summary Write-Host "╔═══════════════════════════════════════════════════════╗" -ForegroundColor Magenta Write-Host "║ SUMMARY ║" -ForegroundColor Magenta Write-Host "╚═══════════════════════════════════════════════════════╝" -ForegroundColor Magenta Write-Host "" if ($TotalErrors -eq 0) { Write-Host "✅ All validators passed!" -ForegroundColor Green exit 0 } else { Write-Host "❌ $TotalErrors validator(s) failed" -ForegroundColor Red exit 1 } ================================================ FILE: scripts/validate-all.sh ================================================ #!/bin/bash # GSD Master Validation Script # Runs all validators and reports overall status total_errors=0 script_dir="$(dirname "$0")" echo "" echo "╔═══════════════════════════════════════════════════════╗" echo "║ GSD ► RUNNING ALL VALIDATORS ║" echo "╚═══════════════════════════════════════════════════════╝" echo "" # Run workflow validator echo "▶ Running workflow validation..." "$script_dir/validate-workflows.sh" if [ $? -ne 0 ]; then ((total_errors++)); fi echo "" # Run skill validator echo "▶ Running skill validation..." "$script_dir/validate-skills.sh" if [ $? -ne 0 ]; then ((total_errors++)); fi echo "" # Run template validator echo "▶ Running template validation..." "$script_dir/validate-templates.sh" if [ $? -ne 0 ]; then ((total_errors++)); fi echo "" # Summary echo "╔═══════════════════════════════════════════════════════╗" echo "║ SUMMARY ║" echo "╚═══════════════════════════════════════════════════════╝" echo "" if [ $total_errors -eq 0 ]; then echo "✅ All validators passed!" exit 0 else echo "❌ $total_errors validator(s) failed" exit 1 fi ================================================ FILE: scripts/validate-skills.ps1 ================================================ # GSD Skill Validation Script # Validates all skill directories for required structure $ErrorCount = 0 $WarningCount = 0 $SkillsChecked = 0 Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host " GSD ► VALIDATING SKILLS" -ForegroundColor Cyan Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host "" $skills = Get-ChildItem ".agents/skills" -Directory foreach ($skill in $skills) { $SkillsChecked++ $skillFile = Join-Path $skill.FullName "SKILL.md" $hasErrors = $false # Check SKILL.md exists if (-not (Test-Path $skillFile)) { Write-Host "❌ $($skill.Name): Missing SKILL.md" -ForegroundColor Red $ErrorCount++ continue } $content = Get-Content $skillFile -Raw # Check for frontmatter if ($content -notmatch "^---") { Write-Host "❌ $($skill.Name): Missing frontmatter" -ForegroundColor Red $ErrorCount++ $hasErrors = $true } # Check for name field if ($content -notmatch "name:") { Write-Host "❌ $($skill.Name): Missing name in frontmatter" -ForegroundColor Red $ErrorCount++ $hasErrors = $true } # Check for description field if ($content -notmatch "description:") { Write-Host "❌ $($skill.Name): Missing description in frontmatter" -ForegroundColor Red $ErrorCount++ $hasErrors = $true } if (-not $hasErrors) { Write-Host "✅ $($skill.Name)" -ForegroundColor Green } } Write-Host "" Write-Host "───────────────────────────────────────────────────────" -ForegroundColor Gray Write-Host "" Write-Host "Skills checked: $SkillsChecked" Write-Host "Errors: $ErrorCount" -ForegroundColor $(if ($ErrorCount -gt 0) { "Red" } else { "Green" }) Write-Host "" if ($ErrorCount -eq 0) { Write-Host "✅ All skills valid!" -ForegroundColor Green exit 0 } else { Write-Host "❌ Validation failed" -ForegroundColor Red exit 1 } ================================================ FILE: scripts/validate-skills.sh ================================================ #!/bin/bash # GSD Skill Validation Script # Validates all skill directories for required structure error_count=0 skills_checked=0 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " GSD ► VALIDATING SKILLS" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" for skill_dir in .agents/skills/*/; do ((skills_checked++)) skill_name=$(basename "$skill_dir") skill_file="$skill_dir/SKILL.md" has_errors=false # Check SKILL.md exists if [ ! -f "$skill_file" ]; then echo "❌ $skill_name: Missing SKILL.md" ((error_count++)) continue fi # Check for frontmatter if ! head -1 "$skill_file" | grep -q "^---"; then echo "❌ $skill_name: Missing frontmatter" ((error_count++)) has_errors=true fi # Check for name field if ! grep -q "name:" "$skill_file"; then echo "❌ $skill_name: Missing name in frontmatter" ((error_count++)) has_errors=true fi # Check for description field if ! grep -q "description:" "$skill_file"; then echo "❌ $skill_name: Missing description in frontmatter" ((error_count++)) has_errors=true fi if [ "$has_errors" = false ]; then echo "✅ $skill_name" fi done echo "" echo "───────────────────────────────────────────────────────" echo "" echo "Skills checked: $skills_checked" echo "Errors: $error_count" echo "" if [ $error_count -eq 0 ]; then echo "✅ All skills valid!" exit 0 else echo "❌ Validation failed" exit 1 fi ================================================ FILE: scripts/validate-templates.ps1 ================================================ # GSD Template Validation Script # Validates all template files in .gsd/templates/ $ErrorCount = 0 $WarningCount = 0 $TemplatesChecked = 0 Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host " GSD ► VALIDATING TEMPLATES" -ForegroundColor Cyan Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host "" $templates = Get-ChildItem ".gsd/templates/*.md" foreach ($file in $templates) { $TemplatesChecked++ $content = Get-Content $file.FullName -Raw $hasErrors = $false # Check for title (# heading) if ($content -notmatch "^# ") { Write-Host "❌ $($file.Name): Missing title (# heading)" -ForegroundColor Red $ErrorCount++ $hasErrors = $true } # Check for Last updated marker if ($content -notmatch "Last updated") { Write-Host "⚠️ $($file.Name): Missing 'Last updated' marker" -ForegroundColor Yellow $WarningCount++ } # Check minimum length (templates should have substance) if ($content.Length -lt 200) { Write-Host "⚠️ $($file.Name): Very short template (<200 chars)" -ForegroundColor Yellow $WarningCount++ } if (-not $hasErrors) { Write-Host "✅ $($file.Name)" -ForegroundColor Green } } Write-Host "" Write-Host "───────────────────────────────────────────────────────" -ForegroundColor Gray Write-Host "" Write-Host "Templates checked: $TemplatesChecked" Write-Host "Errors: $ErrorCount" -ForegroundColor $(if ($ErrorCount -gt 0) { "Red" } else { "Green" }) Write-Host "Warnings: $WarningCount" -ForegroundColor $(if ($WarningCount -gt 0) { "Yellow" } else { "Green" }) Write-Host "" if ($ErrorCount -eq 0) { Write-Host "✅ All templates valid!" -ForegroundColor Green exit 0 } else { Write-Host "❌ Validation failed" -ForegroundColor Red exit 1 } ================================================ FILE: scripts/validate-templates.sh ================================================ #!/bin/bash # GSD Template Validation Script # Validates all template files in .gsd/templates/ error_count=0 warning_count=0 templates_checked=0 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " GSD ► VALIDATING TEMPLATES" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" for file in .gsd/templates/*.md; do ((templates_checked++)) filename=$(basename "$file") has_errors=false # Check for title (# heading) if ! head -1 "$file" | grep -q "^# "; then echo "❌ $filename: Missing title (# heading)" ((error_count++)) has_errors=true fi # Check for Last updated marker if ! grep -q "Last updated" "$file"; then echo "⚠️ $filename: Missing 'Last updated' marker" ((warning_count++)) fi # Check minimum length file_size=$(wc -c < "$file") if [ "$file_size" -lt 200 ]; then echo "⚠️ $filename: Very short template (<200 chars)" ((warning_count++)) fi if [ "$has_errors" = false ]; then echo "✅ $filename" fi done echo "" echo "───────────────────────────────────────────────────────" echo "" echo "Templates checked: $templates_checked" echo "Errors: $error_count" echo "Warnings: $warning_count" echo "" if [ $error_count -eq 0 ]; then echo "✅ All templates valid!" exit 0 else echo "❌ Validation failed" exit 1 fi ================================================ FILE: scripts/validate-workflows.ps1 ================================================ # GSD Workflow Validation Script # Validates all workflow files for required structure $ErrorCount = 0 $WarningCount = 0 $WorkflowsChecked = 0 Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host " GSD ► VALIDATING WORKFLOWS" -ForegroundColor Cyan Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan Write-Host "" $workflows = Get-ChildItem ".agent/workflows/*.md" foreach ($file in $workflows) { $WorkflowsChecked++ $content = Get-Content $file.FullName -Raw $hasErrors = $false # Check for frontmatter if ($content -notmatch "^---") { Write-Host "❌ $($file.Name): Missing frontmatter" -ForegroundColor Red $ErrorCount++ $hasErrors = $true } # Check for description if ($content -notmatch "description:") { Write-Host "❌ $($file.Name): Missing description in frontmatter" -ForegroundColor Red $ErrorCount++ $hasErrors = $true } # Check for process tags (optional but recommended) if ($content -notmatch "") { Write-Host "⚠️ $($file.Name): Missing tag" -ForegroundColor Yellow $WarningCount++ } if (-not $hasErrors) { Write-Host "✅ $($file.Name)" -ForegroundColor Green } } Write-Host "" Write-Host "───────────────────────────────────────────────────────" -ForegroundColor Gray Write-Host "" Write-Host "Workflows checked: $WorkflowsChecked" Write-Host "Errors: $ErrorCount" -ForegroundColor $(if ($ErrorCount -gt 0) { "Red" } else { "Green" }) Write-Host "Warnings: $WarningCount" -ForegroundColor $(if ($WarningCount -gt 0) { "Yellow" } else { "Green" }) Write-Host "" if ($ErrorCount -eq 0) { Write-Host "✅ All workflows valid!" -ForegroundColor Green exit 0 } else { Write-Host "❌ Validation failed" -ForegroundColor Red exit 1 } ================================================ FILE: scripts/validate-workflows.sh ================================================ #!/bin/bash # GSD Workflow Validation Script # Validates all workflow files for required structure error_count=0 warning_count=0 workflows_checked=0 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " GSD ► VALIDATING WORKFLOWS" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" for file in .agent/workflows/*.md; do ((workflows_checked++)) filename=$(basename "$file") has_errors=false # Check for frontmatter if ! head -1 "$file" | grep -q "^---"; then echo "❌ $filename: Missing frontmatter" ((error_count++)) has_errors=true fi # Check for description if ! grep -q "description:" "$file"; then echo "❌ $filename: Missing description in frontmatter" ((error_count++)) has_errors=true fi # Check for process tags (optional but recommended) if ! grep -q "" "$file"; then echo "⚠️ $filename: Missing tag" ((warning_count++)) fi if [ "$has_errors" = false ]; then echo "✅ $filename" fi done echo "" echo "───────────────────────────────────────────────────────" echo "" echo "Workflows checked: $workflows_checked" echo "Errors: $error_count" echo "Warnings: $warning_count" echo "" if [ $error_count -eq 0 ]; then echo "✅ All workflows valid!" exit 0 else echo "❌ Validation failed" exit 1 fi