Showing preview only (345K chars total). Download the full file or copy to clipboard to get everything.
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: "<phase-name>"
---
# /add-phase Workflow
<objective>
Add a new phase to the end of the current roadmap.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/add-todo.md
================================================
---
description: Capture a todo item for later
argument-hint: "<description> [--priority high|medium|low]"
---
# /add-todo Workflow
<objective>
Quickly capture an idea, task, or issue without interrupting current work flow.
</objective>
<context>
**Item:** $ARGUMENTS (the todo description)
**Flags:**
- `--priority high|medium|low` — Set priority (default: medium)
**Output:**
- `.gsd/TODO.md` — Accumulated todo items
</context>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/audit-milestone.md
================================================
---
description: Audit a milestone for quality and completeness
argument-hint: "[milestone-name]"
---
# /audit-milestone Workflow
<objective>
Review a completed (or in-progress) milestone for quality, completeness, and lessons learned.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/check-todos.md
================================================
---
description: List all pending todo items
argument-hint: "[--all] [--priority high|medium|low]"
---
# /check-todos Workflow
<objective>
Display pending todo items, optionally filtered by priority or status.
</objective>
<context>
**Flags:**
- `--all` — Show completed items too
- `--priority high|medium|low` — Filter by priority
**Input:**
- `.gsd/TODO.md` — Todo items
</context>
<process>
## 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 <item> — add new item
───────────────────────────────────────────────────────
```
</process>
<priority_indicators>
| Priority | Indicator |
|----------|-----------|
| high | 🔴 |
| medium | 🟡 |
| low | 🟢 |
| done | ✅ |
</priority_indicators>
================================================
FILE: .agent/workflows/complete-milestone.md
================================================
---
description: Mark current milestone as complete and archive
---
# /complete-milestone Workflow
<objective>
Finalize the current milestone, archive documentation, and prepare for next milestone.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/debug.md
================================================
---
description: Systematic debugging with persistent state
argument-hint: "[description of issue]"
---
# /debug Workflow
<role>
You are a GSD debugger orchestrator. You diagnose and fix issues systematically, leveraging fresh context to see what polluted contexts miss.
</role>
<objective>
Systematically diagnose an issue using hypothesis-driven debugging, with persistent state to prevent circular attempts.
</objective>
<context>
**Issue:** $ARGUMENTS (description of the problem to debug)
**Skill reference:** `.agents/skills/debugger/SKILL.md`
</context>
<process>
## 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.
</process>
<offer_next>
**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
───────────────────────────────────────────────────────
```
</offer_next>
<related>
## 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 |
</related>
================================================
FILE: .agent/workflows/discuss-phase.md
================================================
---
description: Discuss a phase before planning (clarify scope and approach)
argument-hint: "<phase-number>"
---
# /discuss-phase Workflow
<objective>
Interactive discussion about a phase to clarify scope, approach, and concerns before creating plans.
</objective>
<context>
Run BEFORE `/plan` when:
- Phase scope is unclear
- Multiple implementation approaches exist
- Trade-offs need user input
- Dependencies are complex
</context>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/execute.md
================================================
---
description: The Engineer — Execute a specific phase with focused context
argument-hint: "<phase-number> [--gaps-only]"
---
# /execute Workflow
<role>
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
</role>
<objective>
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.
</objective>
<context>
**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
</context>
<process>
## 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 `<task>` blocks in order
3. **Verify each task** — Run `<verify>` 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
</process>
<offer_next>
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
───────────────────────────────────────────────────────
```
</offer_next>
<context_hygiene>
**After 3 failed debugging attempts:**
1. Stop current approach
2. Document to `.gsd/STATE.md` what was tried
3. Recommend `/pause` for fresh session
</context_hygiene>
<related>
## 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 |
</related>
================================================
FILE: .agent/workflows/help.md
================================================
---
description: Show all available GSD commands
---
# /help Workflow
<objective>
Display all available GSD commands with descriptions and usage hints.
</objective>
<process>
**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/
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/insert-phase.md
================================================
---
description: Insert a phase between existing phases (renumbers subsequent)
argument-hint: "<position> <phase-name>"
---
# /insert-phase Workflow
<objective>
Insert a new phase at a specific position, renumbering all subsequent phases.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
<warning>
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
</warning>
================================================
FILE: .agent/workflows/install.md
================================================
---
description: Install GSD into the current project from GitHub
---
# /install Workflow
<objective>
Install GSD for Antigravity into the current project from GitHub.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
<notes>
- 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
</notes>
================================================
FILE: .agent/workflows/list-phase-assumptions.md
================================================
---
description: List assumptions made during phase planning
argument-hint: "<phase-number>"
---
# /list-phase-assumptions Workflow
<objective>
Surface and document assumptions made during phase planning that should be validated.
</objective>
<process>
## 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
</process>
================================================
FILE: .agent/workflows/map.md
================================================
---
description: The Architect — Analyze codebase and update ARCHITECTURE.md and STACK.md
---
# /map Workflow
<role>
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
</role>
<objective>
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.
</objective>
<context>
**No arguments required.** Operates on current project directory.
**Outputs:**
- `.gsd/ARCHITECTURE.md` — System design documentation
- `.gsd/STACK.md` — Technology inventory
</context>
<process>
## 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
</process>
<offer_next>
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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
───────────────────────────────────────────────────────
```
</offer_next>
<related>
## Related
### Workflows
| Command | Relationship |
|---------|--------------|
| `/plan` | Use ARCHITECTURE.md from /map for planning context |
### Skills
| Skill | Purpose |
|-------|---------|
| `codebase-mapper` | Detailed mapping methodology |
</related>
================================================
FILE: .agent/workflows/new-milestone.md
================================================
---
description: Create a new milestone with phases
argument-hint: "<milestone-name>"
---
# /new-milestone Workflow
<objective>
Define a new milestone with goal, phases, and success criteria.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/new-project.md
================================================
---
description: Initialize a new project with deep context gathering
---
# /new-project Workflow
<objective>
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.
</objective>
<process>
## 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.
───────────────────────────────────────────────────────
```
</process>
<questioning_philosophy>
## 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
</questioning_philosophy>
================================================
FILE: .agent/workflows/pause.md
================================================
---
description: Context hygiene — dump state for clean session handoff
---
# /pause Workflow
<objective>
Safely pause work with complete state preservation for session handoff.
</objective>
<when_to_use>
- 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)
</when_to_use>
<process>
## 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.
───────────────────────────────────────────────────────
```
</process>
<context_hygiene>
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.
</context_hygiene>
<proactive_state_save>
## 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`.
</proactive_state_save>
================================================
FILE: .agent/workflows/plan-milestone-gaps.md
================================================
---
description: Create plans to address gaps found in milestone audit
---
# /plan-milestone-gaps Workflow
<objective>
Create targeted plans to address gaps, technical debt, and issues identified during milestone audit.
</objective>
<process>
## 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
<task type="auto">
<name>Fix {issue}</name>
<files>{files}</files>
<action>{fix instructions}</action>
<verify>{original verification that failed}</verify>
<done>{criteria}</done>
</task>
```
---
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
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
<role>
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)
</role>
<objective>
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.
</objective>
<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
</context>
<philosophy>
## 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.
</philosophy>
<discovery_levels>
## 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
</discovery_levels>
<process>
## 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 `<discovery_levels>`).
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 type="auto">
<name>{Task name}</name>
<files>{exact file paths}</files>
<action>
{Specific implementation instructions}
- What to do
- What to avoid and WHY
</action>
<verify>{Command to prove task complete}</verify>
<done>{Measurable acceptance criteria}</done>
</task>
<task type="auto">
...
</task>
## 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 `<verify>` 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
</process>
<offer_next>
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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
───────────────────────────────────────────────────────
```
</offer_next>
<task_types>
| 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.
</task_types>
<related>
## 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 |
</related>
================================================
FILE: .agent/workflows/progress.md
================================================
---
description: Show current position in roadmap and next steps
---
# /progress Workflow
<objective>
Quick status check — where are we and what's next?
</objective>
<process>
## 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 |
</process>
================================================
FILE: .agent/workflows/remove-phase.md
================================================
---
description: Remove a phase from the roadmap (with safety checks)
argument-hint: "<phase-number>"
---
# /remove-phase Workflow
<objective>
Remove a phase from the roadmap, with safety checks for in-progress or completed work.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/research-phase.md
================================================
---
description: Deep technical research for a phase
argument-hint: "<phase-number> [--level 1|2|3]"
---
# /research-phase Workflow
<objective>
Conduct technical research to inform planning decisions for a phase.
</objective>
<discovery_levels>
## 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.
</discovery_levels>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
================================================
FILE: .agent/workflows/resume.md
================================================
---
description: Restore context from previous session
---
# /resume Workflow
<objective>
Start a new session with full context from where we left off.
</objective>
<process>
## 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.
───────────────────────────────────────────────────────
```
</process>
<fresh_context_advantage>
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.
</fresh_context_advantage>
================================================
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
<objective>
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.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
<related>
## 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 |
</related>
================================================
FILE: .agent/workflows/update.md
================================================
---
description: Update GSD to the latest version from GitHub
---
# /update Workflow
<objective>
Update GSD for Antigravity to the latest version from GitHub.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
<preserved_files>
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
</preserved_files>
================================================
FILE: .agent/workflows/verify.md
================================================
---
description: The Auditor — Validate work against spec with empirical evidence
argument-hint: "<phase-number>"
---
# /verify Workflow
<role>
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
</role>
<objective>
Confirm that implemented work meets spec requirements with documented proof.
The verifier checks the CODEBASE, not SUMMARY claims.
</objective>
<context>
**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
</context>
<process>
## 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
<task type="auto">
<name>Fix {issue}</name>
<files>{files to modify}</files>
<action>{specific fix instructions}</action>
<verify>{how to verify the fix}</verify>
<done>{acceptance criteria}</done>
</task>
```
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"
```
</process>
<evidence_requirements>
## 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 |
</evidence_requirements>
<related>
## 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 |
</related>
================================================
FILE: .agent/workflows/web-search.md
================================================
---
description: Search the web for information to inform decisions
argument-hint: "<query> [--domain <site>]"
---
# /web-search Workflow
<objective>
Search the web to gather information for technical decisions, API documentation, library comparisons, or any research need.
</objective>
<when_to_use>
- 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
</when_to_use>
<process>
## 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
</process>
<integration>
## 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.
</integration>
<related>
## Related
### Workflows
| Command | Relationship |
|---------|--------------|
| `/research-phase` | Uses web-search for phase research |
| `/plan` | May trigger web-search for discovery |
| `/debug` | Search for error solutions |
</related>
================================================
FILE: .agent/workflows/whats-new.md
================================================
---
description: Show recent GSD changes and new features
---
# /whats-new Workflow
<objective>
Display recent changes, new features, and improvements to GSD for Antigravity.
</objective>
<process>
## 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
───────────────────────────────────────────────────────
```
</process>
<related>
## Related
### Workflows
| Command | Relationship |
|---------|--------------|
| `/update` | Update GSD to latest version |
| `/help` | List all commands |
</related>
================================================
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
<role>
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
</role>
## 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
<role>
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.
</role>
---
## 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
<role>
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.
</role>
---
## 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
<role>
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.
</role>
---
## 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
<role>
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.
</role>
---
## 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 `<context>` section
- Files in task `<files>`
**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
<role>
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.
</role>
---
## 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 `<verify>` — can't confirm completion
- Missing `<done>` — no acceptance criteria
- Vague `<action>` — "implement auth" instead of specific steps
- Empty `<files>` — what gets created?
**Example issue:**
```yaml
issue:
dimension: task_completeness
severity: blocker
description: "Task 2 missing <verify> 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
<role>
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
</role>
---
## 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:
### `<files>`
Exact file paths created or modified.
- ✅ Good: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma`
- ❌ Bad: "the auth files", "relevant components"
### `<action>`
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"
### `<verify>`
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"
### `<done>`
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}
<objective>
{What this plan accomplishes}
Purpose: {Why this matters}
Output: {What artifacts will be created}
</objective>
<context>
Load for context:
- .gsd/SPEC.md
- .gsd/ARCHITECTURE.md (if exists)
- {relevant source files}
</context>
<tasks>
<task type="auto">
<name>{Clear task name}</name>
<files>{exact/file/paths.ext}</files>
<action>
{Specific instructions}
AVOID: {common mistake} because {reason}
</action>
<verify>{command or check}</verify>
<done>{measurable criteria}</done>
</task>
</tasks>
<verification>
After all tasks, verify:
- [ ] {Must-have 1}
- [ ] {Must-have 2}
</verification>
<success_criteria>
- [ ] All tasks verified
- [ ] Must-haves confirmed
</success_criteria>
```
### 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
<task type="auto">
<name>Write failing tests</name>
<files>tests/{feature}.test.ts</files>
<action>Write tests for: {behavior}</action>
<verify>npm test shows RED (failing)</verify>
<done>Tests written, all failing</done>
</task>
## Green Phase
<task type="auto">
<name>Implement to pass tests</name>
<files>src/{feature}.ts</files>
<action>Minimal implementation to pass tests</action>
<verify>npm test shows GREEN</verify>
<done>All tests passing</done>
</task>
## Refactor Phase
<task type="auto">
<name>Refactor with confidence</name>
<files>src/{feature}.ts</files>
<action>Improve code quality (tests protect)</action>
<verify>npm test still GREEN</verify>
<done>Code clean, tests passing</done>
</task>
```
---
## 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
<task type="auto">
<name>Add authentication</name>
<action>Implement auth</action>
<verify>???</verify>
</task>
```
### ✅ Specific Tasks
```xml
<task type="auto">
<name>Create login endpoint with JWT</name>
<files>src/app/api/auth/login/route.ts</files>
<action>
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.
</action>
<verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
<done>Valid creds → 200 + cookie. Invalid → 401.</done>
</task>
```
### ❌ 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
<role>
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.
</role>
---
## 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
<role>
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.
</role>
---
## 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 <div>Component</div>
return <div>Placeholder</div>
return <div>{/* TODO */}</div>
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 <div>No messages</div> // 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
---
<objective>
Create login and logout endpoints with JWT handling.
</objective>
<context>
Files to read: src/app/api/ structure, existing auth if any
</context>
<tasks>
<task type="auto" effort="medium">
<name>Create login endpoint</name>
<files>src/app/api/auth/login/route.ts</files>
<action>
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.
</action>
<verify>curl -X POST localhost:3000/api/auth/login -d '{"email":"test@example.com","password":"test123"}'</verify>
<done>Valid credentials return 200 + Set-Cookie header</done>
</task>
<task type="auto" effort="low">
<name>Create logout endpoint</name>
<files>src/app/api/auth/logout/route.ts</files>
<action>
Create POST handler that clears the auth cookie.
Return 200 on success.
</action>
<verify>curl -X POST localhost:3000/api/auth/logout --cookie "token=..."</verify>
<done>Cookie is cleared, response is 200</done>
</task>
</tasks>
```
---
### 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]
---
<objective>
Create middleware to protect routes requiring authentication.
</objective>
<context>
Wave 1 complete: login/logout endpoints exist.
JWT is stored in httpOnly cookie named "token".
</context>
<tasks>
<task type="auto" effort="high">
<name>Create auth middleware</name>
<files>src/middleware/auth.ts</files>
<action>
Create middleware that:
1. Reads JWT from cookie
2. Verifies signature with jose
3. Attaches user to request
4. Returns 401 if invalid/missing
</action>
<verify>Import and call middleware with mock request</verify>
<done>Valid JWT passes, invalid/missing returns 401</done>
</task>
<task type="auto" effort="medium">
<name>Apply middleware to protected route</name>
<files>src/app/api/user/profile/route.ts</files>
<action>
Create example protected route.
Apply auth middleware.
Return user data if authenticated.
</action>
<verify>curl localhost:3000/api/user/profile with and without cookie</verify>
<done>With cookie: 200 + data. Without: 401</done>
</task>
</tasks>
```
---
### 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
<task type="auto">
<name>Clear name</name>
<files>exact/path.ts</files>
<action>Specific instructions</action>
<verify>Executable command</verify>
<done>Measurable criteria</done>
</task>
```
## 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
<task type="auto">
<name>Initialize SQLite database</name>
<files>src/db.ts</files>
<action>
Create SQLite connection using better-sqlite3.
Create todos table with: id, title, completed, created_at.
</action>
<verify>node -e "require('./src/db')" exits without error</verify>
<done>Database file exists, table created</done>
</task>
```
---
### 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
<!-- OVERWRITE on each update - always reflects NOW -->
hypothesis: [current theory being tested]
test: [how testing it]
expecting: [what result means if true/false]
next_action: [immediate next step]
## Symptoms
<!-- Written during gathering, then immutable -->
expected: [what should happen]
actual: [what actually happens]
errors: [error messages if any]
reproduction: [how to trigger]
started: [when it broke / always broken]
## Eliminated
<!-- APPEND only - prevents re-investigating after context reset -->
- hypothesis: [theory that was wrong]
evidence: [what disproved it]
timestamp: [when eliminated]
## Evidence
<!-- APPEND only - facts discovered during investigation -->
- timestamp: [when found]
checked: [what was examined]
found: [what was observed]
implication: [what this means]
## Resolution
<!-- OVERWRITE as understanding evolves -->
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
<task type="auto">
<name>{Clear, specific task name}</name>
<files>
{exact/file/path1.ext}
{exact/file/path2.ext}
</files>
<action>
{Specific implementation instructions}
Steps:
1. {Step 1}
2. {Step 2}
3. {Step 3}
AVOID: {common mistake} because {reason}
USE: {preferred approach} because {reason}
</action>
<verify>
{Executable command or check}
Example: npm test -- --testNamePattern="auth"
Example: curl -X POST localhost:3000/api/login
</verify>
<done>
{Measurable acceptance criteria}
Example: Valid credentials → 200 + Set-Cookie, invalid → 401
</done>
</task>
<task type="auto">
<name>{Task 2 name}</name>
<files>{files}</files>
<action>{instructions}</action>
<verify>{command}</verify>
<done>{criteria}</done>
</task>
## 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 <!-- date -->
## 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}`
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
Condensed preview — 93 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (349K chars).
[
{
"path": ".agent/workflows/add-phase.md",
"chars": 1489,
"preview": "---\ndescription: Add a new phase to the end of the roadmap\nargument-hint: \"<phase-name>\"\n---\n\n# /add-phase Workflow\n\n<ob"
},
{
"path": ".agent/workflows/add-todo.md",
"chars": 1116,
"preview": "---\ndescription: Capture a todo item for later\nargument-hint: \"<description> [--priority high|medium|low]\"\n---\n\n# /add-t"
},
{
"path": ".agent/workflows/audit-milestone.md",
"chars": 1958,
"preview": "---\ndescription: Audit a milestone for quality and completeness\nargument-hint: \"[milestone-name]\"\n---\n\n# /audit-mileston"
},
{
"path": ".agent/workflows/check-todos.md",
"chars": 1363,
"preview": "---\ndescription: List all pending todo items\nargument-hint: \"[--all] [--priority high|medium|low]\"\n---\n\n# /check-todos W"
},
{
"path": ".agent/workflows/complete-milestone.md",
"chars": 4301,
"preview": "---\ndescription: Mark current milestone as complete and archive\n---\n\n# /complete-milestone Workflow\n\n<objective>\nFinaliz"
},
{
"path": ".agent/workflows/debug.md",
"chars": 4269,
"preview": "---\ndescription: Systematic debugging with persistent state\nargument-hint: \"[description of issue]\"\n---\n\n# /debug Workfl"
},
{
"path": ".agent/workflows/discuss-phase.md",
"chars": 2106,
"preview": "---\ndescription: Discuss a phase before planning (clarify scope and approach)\nargument-hint: \"<phase-number>\"\n---\n\n# /di"
},
{
"path": ".agent/workflows/execute.md",
"chars": 6780,
"preview": "---\ndescription: The Engineer — Execute a specific phase with focused context\nargument-hint: \"<phase-number> [--gaps-onl"
},
{
"path": ".agent/workflows/help.md",
"chars": 2574,
"preview": "---\ndescription: Show all available GSD commands\n---\n\n# /help Workflow\n\n<objective>\nDisplay all available GSD commands w"
},
{
"path": ".agent/workflows/insert-phase.md",
"chars": 2201,
"preview": "---\ndescription: Insert a phase between existing phases (renumbers subsequent)\nargument-hint: \"<position> <phase-name>\"\n"
},
{
"path": ".agent/workflows/install.md",
"chars": 4088,
"preview": "---\ndescription: Install GSD into the current project from GitHub\n---\n\n# /install Workflow\n\n<objective>\nInstall GSD for "
},
{
"path": ".agent/workflows/list-phase-assumptions.md",
"chars": 1619,
"preview": "---\ndescription: List assumptions made during phase planning\nargument-hint: \"<phase-number>\"\n---\n\n# /list-phase-assumpti"
},
{
"path": ".agent/workflows/map.md",
"chars": 7529,
"preview": "---\ndescription: The Architect — Analyze codebase and update ARCHITECTURE.md and STACK.md\n---\n\n# /map Workflow\n\n<role>\nY"
},
{
"path": ".agent/workflows/new-milestone.md",
"chars": 3067,
"preview": "---\ndescription: Create a new milestone with phases\nargument-hint: \"<milestone-name>\"\n---\n\n# /new-milestone Workflow\n\n<o"
},
{
"path": ".agent/workflows/new-project.md",
"chars": 8478,
"preview": "---\ndescription: Initialize a new project with deep context gathering\n---\n\n# /new-project Workflow\n\n<objective>\nInitiali"
},
{
"path": ".agent/workflows/pause.md",
"chars": 3897,
"preview": "---\ndescription: Context hygiene — dump state for clean session handoff\n---\n\n# /pause Workflow\n\n<objective>\nSafely pause"
},
{
"path": ".agent/workflows/plan-milestone-gaps.md",
"chars": 1908,
"preview": "---\ndescription: Create plans to address gaps found in milestone audit\n---\n\n# /plan-milestone-gaps Workflow\n\n<objective>"
},
{
"path": ".agent/workflows/plan.md",
"chars": 9693,
"preview": "---\ndescription: The Strategist — Decompose requirements into executable phases in ROADMAP.md\nargument-hint: \"[phase] [-"
},
{
"path": ".agent/workflows/progress.md",
"chars": 1656,
"preview": "---\ndescription: Show current position in roadmap and next steps\n---\n\n# /progress Workflow\n\n<objective>\nQuick status che"
},
{
"path": ".agent/workflows/remove-phase.md",
"chars": 2401,
"preview": "---\ndescription: Remove a phase from the roadmap (with safety checks)\nargument-hint: \"<phase-number>\"\n---\n\n# /remove-pha"
},
{
"path": ".agent/workflows/research-phase.md",
"chars": 2658,
"preview": "---\ndescription: Deep technical research for a phase\nargument-hint: \"<phase-number> [--level 1|2|3]\"\n---\n\n# /research-ph"
},
{
"path": ".agent/workflows/resume.md",
"chars": 2544,
"preview": "---\ndescription: Restore context from previous session\n---\n\n# /resume Workflow\n\n<objective>\nStart a new session with ful"
},
{
"path": ".agent/workflows/sprint.md",
"chars": 3647,
"preview": "---\ndescription: Create and manage a time-boxed sprint for quick focused work\nargument-hint: \"[new|status|close] [sprint"
},
{
"path": ".agent/workflows/update.md",
"chars": 4300,
"preview": "---\ndescription: Update GSD to the latest version from GitHub\n---\n\n# /update Workflow\n\n<objective>\nUpdate GSD for Antigr"
},
{
"path": ".agent/workflows/verify.md",
"chars": 5344,
"preview": "---\ndescription: The Auditor — Validate work against spec with empirical evidence\nargument-hint: \"<phase-number>\"\n---\n\n#"
},
{
"path": ".agent/workflows/web-search.md",
"chars": 2573,
"preview": "---\ndescription: Search the web for information to inform decisions\nargument-hint: \"<query> [--domain <site>]\"\n---\n\n# /w"
},
{
"path": ".agent/workflows/whats-new.md",
"chars": 1691,
"preview": "---\ndescription: Show recent GSD changes and new features\n---\n\n# /whats-new Workflow\n\n<objective>\nDisplay recent changes"
},
{
"path": ".agents/skills/codebase-mapper/SKILL.md",
"chars": 4574,
"preview": "---\nname: codebase-mapper\ndescription: Analyzes existing codebases to understand structure, patterns, and technical debt"
},
{
"path": ".agents/skills/context-compressor/SKILL.md",
"chars": 4396,
"preview": "---\nname: context-compressor\ndescription: Strategies for compressing context to maximize token efficiency\n---\n\n# Context"
},
{
"path": ".agents/skills/context-fetch/SKILL.md",
"chars": 4002,
"preview": "---\nname: context-fetch\ndescription: Search-first skill to reduce unnecessary file reads by searching before loading\n---"
},
{
"path": ".agents/skills/context-health-monitor/SKILL.md",
"chars": 3041,
"preview": "---\nname: context-health-monitor\ndescription: Monitors context complexity and triggers state dumps before quality degrad"
},
{
"path": ".agents/skills/debugger/SKILL.md",
"chars": 7224,
"preview": "---\nname: debugger\ndescription: Systematic debugging with persistent state and fresh context advantages\n---\n\n# GSD Debug"
},
{
"path": ".agents/skills/empirical-validation/SKILL.md",
"chars": 2584,
"preview": "---\nname: empirical-validation\ndescription: Requires proof before marking work complete — no \"trust me, it works\"\n---\n\n#"
},
{
"path": ".agents/skills/executor/SKILL.md",
"chars": 11035,
"preview": "---\nname: executor\ndescription: Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and st"
},
{
"path": ".agents/skills/plan-checker/SKILL.md",
"chars": 6331,
"preview": "---\nname: plan-checker\ndescription: Validates plans before execution to catch issues early\n---\n\n# GSD Plan Checker Agent"
},
{
"path": ".agents/skills/planner/SKILL.md",
"chars": 12735,
"preview": "---\nname: planner\ndescription: Creates executable phase plans with task breakdown, dependency analysis, and goal-backwar"
},
{
"path": ".agents/skills/token-budget/SKILL.md",
"chars": 3588,
"preview": "---\nname: token-budget\ndescription: Manages token budget estimation and tracking to prevent context overflow\n---\n\n# Toke"
},
{
"path": ".agents/skills/verifier/SKILL.md",
"chars": 10054,
"preview": "---\nname: verifier\ndescription: Validates implemented work against spec requirements with empirical evidence\n---\n\n# GSD "
},
{
"path": ".gemini/GEMINI.md",
"chars": 1825,
"preview": "# GSD Methodology — Mission Control Rules\n\n> **Get Shit Done**: A spec-driven, context-engineered development methodolog"
},
{
"path": ".gitignore",
"chars": 179,
"preview": "# GSD State Files\n.gsd/ARCHITECTURE.md\n.gsd/DECISIONS.md\n.gsd/JOURNAL.md\n.gsd/ROADMAP.md\n.gsd/SPEC.md\n.gsd/STACK.md\n.gsd"
},
{
"path": ".gsd/examples/cross-platform.md",
"chars": 2120,
"preview": "# Cross-Platform Commands Reference\n\n> PowerShell ↔ Bash equivalents for GSD workflows\n\n## Common Operations\n\n| Operatio"
},
{
"path": ".gsd/examples/multi-wave-workflow.md",
"chars": 5642,
"preview": "# Multi-Wave Workflow Example\n\nThis example demonstrates a complete GSD workflow with:\n- Short spec\n- Plan breakdown\n- 2"
},
{
"path": ".gsd/examples/quick-reference.md",
"chars": 2103,
"preview": "# GSD Quick Reference Card\n\n## Workflow Lifecycle\n\n```\n┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐\n│ /map"
},
{
"path": ".gsd/examples/workflow-example.md",
"chars": 2451,
"preview": "# GSD Workflow Example\n\n> A complete walkthrough of using GSD from start to finish.\n\n## Scenario: Building a Simple Todo"
},
{
"path": ".gsd/templates/DEBUG.md",
"chars": 3030,
"preview": "# Debug Template\n\nTemplate for `.gsd/debug/[slug].md` — active debug session tracking.\n\n---\n\n## File Template\n\n```markdo"
},
{
"path": ".gsd/templates/PLAN.md",
"chars": 1981,
"preview": "# PLAN.md Template\n\n> Copy this template when creating execution plans.\n\n```markdown\n---\nphase: {N}\nplan: {M}\nwave: {W}\n"
},
{
"path": ".gsd/templates/RESEARCH.md",
"chars": 1507,
"preview": "# RESEARCH.md Template\n\n> Copy this template when documenting phase research.\n\n```markdown\n---\nphase: {N}\nresearched_at:"
},
{
"path": ".gsd/templates/SUMMARY.md",
"chars": 1825,
"preview": "# Summary Template\n\nTemplate for `.gsd/phases/{N}/{plan}-SUMMARY.md` — execution summary after plan completion.\n\n---\n\n##"
},
{
"path": ".gsd/templates/UAT.md",
"chars": 2802,
"preview": "# UAT Template\n\nTemplate for `.gsd/phases/{N}/UAT.md` — User Acceptance Testing checklist.\n\n**Purpose:** Structured manu"
},
{
"path": ".gsd/templates/VERIFICATION.md",
"chars": 1462,
"preview": "# VERIFICATION.md Template\n\n> Copy this template when creating phase verification reports.\n\n```markdown\n---\nphase: {N}\nv"
},
{
"path": ".gsd/templates/architecture.md",
"chars": 1701,
"preview": "# Architecture\n\n> Auto-generated by /map on <!-- date -->\n\n## Overview\n\n{Brief description of the system and its purpose"
},
{
"path": ".gsd/templates/context.md",
"chars": 1408,
"preview": "# Context Template\n\nTemplate for `.gsd/phases/{N}/CONTEXT.md` — user's vision for a phase.\n\n---\n\n## File Template\n\n```ma"
},
{
"path": ".gsd/templates/decisions.md",
"chars": 583,
"preview": "# DECISIONS.md — Architecture Decision Records\n\n> **Purpose**: Log significant technical decisions and their rationale.\n"
},
{
"path": ".gsd/templates/discovery.md",
"chars": 2536,
"preview": "# Discovery Template\n\nTemplate for `.gsd/phases/{N}/DISCOVERY.md` — shallow research for library/option decisions.\n\n**Pu"
},
{
"path": ".gsd/templates/journal.md",
"chars": 793,
"preview": "# JOURNAL.md — Session Log\n\n> **Purpose**: Chronicle of work sessions for context continuity.\n\n---\n\n## Sessions\n\n## Sess"
},
{
"path": ".gsd/templates/milestone.md",
"chars": 1745,
"preview": "# Milestone Template\n\nTemplate for `.gsd/milestones/{name}/MILESTONE.md` — milestone definition and tracking.\n\n---\n\n## F"
},
{
"path": ".gsd/templates/phase-summary.md",
"chars": 1049,
"preview": "# Phase {N} Summary\n\n> **Status**: Complete\n> **Completed**: YYYY-MM-DD\n\n## Objective\n{What this phase set out to accomp"
},
{
"path": ".gsd/templates/project.md",
"chars": 1926,
"preview": "# Project Template\n\nTemplate for `.gsd/SPEC.md` (or PROJECT.md) — project specification.\n\n---\n\n## File Template\n\n```mark"
},
{
"path": ".gsd/templates/requirements.md",
"chars": 2093,
"preview": "# Requirements Template\n\nTemplate for `.gsd/REQUIREMENTS.md` — formal requirements tracking with traceability.\n\n---\n\n## "
},
{
"path": ".gsd/templates/roadmap.md",
"chars": 1658,
"preview": "# Roadmap Template\n\nTemplate for `.gsd/ROADMAP.md` — phase structure and progress tracking.\n\n---\n\n## File Template\n\n```m"
},
{
"path": ".gsd/templates/spec.md",
"chars": 1169,
"preview": "# SPEC.md — Project Specification\n\n> **Status**: `DRAFT` | `FINALIZED`\n>\n> ⚠️ **Planning Lock**: No code may be written "
},
{
"path": ".gsd/templates/sprint.md",
"chars": 1072,
"preview": "# Sprint {N} — {Sprint Name}\n\n> **Duration**: YYYY-MM-DD to YYYY-MM-DD\n> **Status**: In Progress | Complete\n\n## Goal\n{On"
},
{
"path": ".gsd/templates/stack.md",
"chars": 1369,
"preview": "# Technology Stack\n\n> Auto-generated by /map on <!-- date -->\n\n## Runtime\n\n| Technology | Version | Purpose |\n|---------"
},
{
"path": ".gsd/templates/state.md",
"chars": 1473,
"preview": "# State Template\n\nTemplate for `.gsd/STATE.md` — project memory across sessions.\n\n---\n\n## File Template\n\n```markdown\n---"
},
{
"path": ".gsd/templates/state_snapshot.md",
"chars": 2462,
"preview": "# State Snapshot Template\n\nTemplate for wave summaries and session state captures.\n\n---\n\n## When to Use\n\nCreate a state "
},
{
"path": ".gsd/templates/todo.md",
"chars": 577,
"preview": "# TODO.md — Pending Items\n\n> Quick capture of ideas, tasks, and issues.\n>\n> Use `/add-todo` to add items, `/check-todos`"
},
{
"path": ".gsd/templates/token_report.md",
"chars": 1310,
"preview": "# Token Report Template\n\nTemplate for documenting token usage per wave or session.\n\n---\n\n## Template\n\n```markdown\n---\nwa"
},
{
"path": ".gsd/templates/user-setup.md",
"chars": 1871,
"preview": "# User Setup Template\n\nTemplate for user setup instructions when external services are needed.\n\n---\n\n## File Template\n\n`"
},
{
"path": "CHANGELOG.md",
"chars": 5604,
"preview": "# Changelog\n\nAll notable changes to GSD for Antigravity.\n\n## [1.5.0] - 2026-04-01\n\n### Breaking Changes\n- **Skills moved"
},
{
"path": "GSD-STYLE.md",
"chars": 6037,
"preview": "# GSD-STYLE.md\n\n> **Comprehensive reference.** Core rules auto-load from `.gemini/GEMINI.md`. This document provides dee"
},
{
"path": "LICENSE",
"chars": 1065,
"preview": "MIT License\n\nCopyright (c) 2026 toonight\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\no"
},
{
"path": "PROJECT_RULES.md",
"chars": 6603,
"preview": "# PROJECT_RULES.md — GSD Canonical Rules\n\n> **Single Source of Truth** for the Get Shit Done methodology.\n> \n> Model-agn"
},
{
"path": "README.md",
"chars": 17025,
"preview": "<div align=\"center\">\n\n<picture>\n <img src=\"assets/banner.svg\" alt=\"Get Shit Done for Antigravity\" width=\"100%\"/>\n</pict"
},
{
"path": "VERSION",
"chars": 6,
"preview": "1.5.0\n"
},
{
"path": "adapters/CLAUDE.md",
"chars": 1852,
"preview": "# Claude Adapter\n\n> **Everything in this file is optional.**\n> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RU"
},
{
"path": "adapters/GEMINI.md",
"chars": 1945,
"preview": "# Gemini Adapter\n\n> **Everything in this file is optional.**\n> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RU"
},
{
"path": "adapters/GPT_OSS.md",
"chars": 2740,
"preview": "# GPT & Open Source Models Adapter\n\n> **Everything in this file is optional.**\n> For canonical rules, see [PROJECT_RULES"
},
{
"path": "docs/model-selection-playbook.md",
"chars": 3217,
"preview": "# Model Selection Playbook\n\n> Guidance for choosing models by phase and task type.\n> \n> **No model is required.** These "
},
{
"path": "docs/runbook.md",
"chars": 4820,
"preview": "# GSD Runbook\n\n> Operational procedures for debugging, validation, and recovery.\n\n---\n\n## Quick Commands\n\n### Status Che"
},
{
"path": "docs/token-optimization-guide.md",
"chars": 4370,
"preview": "# Token Optimization Guide\n\n> Practical strategies for reducing token consumption while maintaining quality.\n\n---\n\n## Wh"
},
{
"path": "model_capabilities.yaml",
"chars": 2835,
"preview": "# Model Capabilities Registry\n#\n# This file is OPTIONAL. GSD works without it.\n# If present, it provides guidance for mo"
},
{
"path": "scripts/search_repo.ps1",
"chars": 2158,
"preview": "# search_repo.ps1 - Search codebase with best available tool\n#\n# Usage: .\\scripts\\search_repo.ps1 <pattern> [path] [opti"
},
{
"path": "scripts/search_repo.sh",
"chars": 1463,
"preview": "#!/bin/bash\n# search_repo.sh - Search codebase with best available tool\n#\n# Usage: ./scripts/search_repo.sh <pattern> [p"
},
{
"path": "scripts/setup_search.ps1",
"chars": 3596,
"preview": "# setup_search.ps1 - Optional search tool setup for GSD\n#\n# This script checks for and provides guidance on installing s"
},
{
"path": "scripts/setup_search.sh",
"chars": 3009,
"preview": "#!/bin/bash\n# setup_search.sh - Optional search tool setup for GSD\n#\n# This script checks for and optionally installs se"
},
{
"path": "scripts/validate-all.ps1",
"chars": 1496,
"preview": "# GSD Master Validation Script\n# Runs all validators and reports overall status\n\n$TotalErrors = 0\n\nWrite-Host \"\"\nWrite-H"
},
{
"path": "scripts/validate-all.sh",
"chars": 1166,
"preview": "#!/bin/bash\n# GSD Master Validation Script\n# Runs all validators and reports overall status\n\ntotal_errors=0\nscript_dir=\""
},
{
"path": "scripts/validate-skills.ps1",
"chars": 2030,
"preview": "# GSD Skill Validation Script\n# Validates all skill directories for required structure\n\n$ErrorCount = 0\n$WarningCount = "
},
{
"path": "scripts/validate-skills.sh",
"chars": 1587,
"preview": "#!/bin/bash\n# GSD Skill Validation Script\n# Validates all skill directories for required structure\n\nerror_count=0\nskills"
},
{
"path": "scripts/validate-templates.ps1",
"chars": 1906,
"preview": "# GSD Template Validation Script\n# Validates all template files in .gsd/templates/\n\n$ErrorCount = 0\n$WarningCount = 0\n$T"
},
{
"path": "scripts/validate-templates.sh",
"chars": 1415,
"preview": "#!/bin/bash\n# GSD Template Validation Script\n# Validates all template files in .gsd/templates/\n\nerror_count=0\nwarning_co"
},
{
"path": "scripts/validate-workflows.ps1",
"chars": 1909,
"preview": "# GSD Workflow Validation Script\n# Validates all workflow files for required structure\n\n$ErrorCount = 0\n$WarningCount = "
},
{
"path": "scripts/validate-workflows.sh",
"chars": 1417,
"preview": "#!/bin/bash\n# GSD Workflow Validation Script\n# Validates all workflow files for required structure\n\nerror_count=0\nwarnin"
}
]
About this extraction
This page contains the full source code of the toonight/get-shit-done-for-antigravity GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 93 files (292.8 KB), approximately 79.5k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.