Deploy HALE API v3.1

.agent/workflows/add-phase.md

@@ -0,0 +1,96 @@
+---
+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>

.agent/workflows/add-todo.md

@@ -0,0 +1,69 @@
+---
+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>

.agent/workflows/audit-milestone.md

@@ -0,0 +1,107 @@
+---
+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>

.agent/workflows/check-todos.md

@@ -0,0 +1,80 @@
+---
+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>

.agent/workflows/complete-milestone.md

@@ -0,0 +1,192 @@
+---
+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>

.agent/workflows/debug.md

@@ -0,0 +1,235 @@
+---
+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>

.agent/workflows/discuss-phase.md

@@ -0,0 +1,123 @@
+---
+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>

.agent/workflows/execute.md

@@ -0,0 +1,323 @@
+---
+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>

.agent/workflows/help.md

@@ -0,0 +1,96 @@
+---
+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>

.agent/workflows/insert-phase.md

@@ -0,0 +1,109 @@
+---
+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>

.agent/workflows/install.md

@@ -0,0 +1,177 @@
+---
+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>

.agent/workflows/list-phase-assumptions.md

@@ -0,0 +1,82 @@
+---
+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>

.agent/workflows/map.md

@@ -0,0 +1,394 @@
+---
+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>

.agent/workflows/new-milestone.md

@@ -0,0 +1,155 @@
+---
+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>

.agent/workflows/new-project.md

@@ -0,0 +1,368 @@
+---
+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>

.agent/workflows/pause.md

@@ -0,0 +1,176 @@
+---
+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>

.agent/workflows/plan-milestone-gaps.md

@@ -0,0 +1,116 @@
+---
+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>

.agent/workflows/plan.md

@@ -0,0 +1,396 @@
+---
+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>

.agent/workflows/progress.md

@@ -0,0 +1,90 @@
+---
+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>

.agent/workflows/remove-phase.md

@@ -0,0 +1,139 @@
+---
+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>

.agent/workflows/research-phase.md

@@ -0,0 +1,160 @@
+---
+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>

.agent/workflows/resume.md

@@ -0,0 +1,131 @@
+---
+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>

.agent/workflows/sprint.md

@@ -0,0 +1,192 @@
+---
+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>

.agent/workflows/update.md

@@ -0,0 +1,201 @@
+---
+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>

.agent/workflows/verify.md

@@ -0,0 +1,263 @@
+---
+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>

.agent/workflows/web-search.md

@@ -0,0 +1,121 @@
+---
+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>

.agent/workflows/whats-new.md

@@ -0,0 +1,80 @@
+---
+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>

.agents/skills/codebase-mapper/SKILL.md

@@ -0,0 +1,226 @@
+---
+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

.agents/skills/context-compressor/SKILL.md

@@ -0,0 +1,201 @@
+---
+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.*

.agents/skills/context-fetch/SKILL.md

@@ -0,0 +1,184 @@
+---
+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.*

.agents/skills/context-health-monitor/SKILL.md

@@ -0,0 +1,105 @@
+---
+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

.agents/skills/debugger/SKILL.md

@@ -0,0 +1,273 @@
+---
+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}
+```

.agents/skills/empirical-validation/SKILL.md

@@ -0,0 +1,97 @@
+---
+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

.agents/skills/executor/SKILL.md

@@ -0,0 +1,465 @@
+---
+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.

.agents/skills/plan-checker/SKILL.md

@@ -0,0 +1,283 @@
+---
+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.

.agents/skills/planner/SKILL.md

@@ -0,0 +1,485 @@
+---
+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

.agents/skills/token-budget/SKILL.md

@@ -0,0 +1,166 @@
+---
+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.*

.agents/skills/verifier/SKILL.md

@@ -0,0 +1,421 @@
+---
+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

.gemini/GEMINI.md

@@ -0,0 +1,67 @@
+# 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*
+

.gsd/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# ARCHITECTURE.md — System Overview
+
+> Generated: 2026-06-21 | Status: Current
+
+## System Overview
+
+**HALE** (Adaptive Learning Engine) is a FastAPI-based backend serving an AI-powered personal learning coach. It uses a Contextual Multi-Armed Bandit RL engine (`rl_engine.py`) to recommend daily learning intensities, a Gemini-powered planner to generate daily task sequences, and a PostgreSQL database (SQLite in dev) to persist user state and progress.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| API Framework | FastAPI 0.115+ |
+| ASGI Server | Uvicorn (2 workers in prod) |
+| Database | PostgreSQL 16 (prod) / SQLite (dev) |
+| ORM | SQLAlchemy 2.0 |
+| Migrations | Alembic |
+| Auth | python-jose JWT + bcrypt |
+| AI/LLM | Google Gemini (multi-key failover) |
+| Caching / State | Redis 7 (optional in dev) |
+| Rate Limiting | slowapi |
+| Scheduling | APScheduler (cron at 2 AM IST) |
+| Observability | Sentry SDK (optional) |
+| Containerization | Docker + docker-compose |
+
+## Directory Structure
+
+```
+app/
+├── main.py              # App factory, middleware, scheduler, health endpoints
+├── core/
+│   ├── config.py        # Pydantic Settings (env-based)
+│   ├── database.py      # SQLAlchemy engine, SessionLocal, Base, init_db
+│   ├── security.py      # JWT creation/validation, bcrypt, blacklist, versioning
+│   ├── exceptions.py    # Global exception handlers
+│   └── redis_client.py  # [PLANNED] Redis connection pool with fallback
+├── api/
+│   ├── auth.py          # /register, /login, /refresh, /logout, /profile
+│   ├── goals.py         # /api/goals CRUD
+│   ├── plans.py         # /api/plan, /api/complete, /api/skip, /api/stats
+│   └── schedule.py      # /api/schedule, /api/timetable
+├── models/
+│   ├── user.py          # User model (RL state, bandit params, streaks, XP)
+│   ├── goal.py          # Goal model (plan JSON, completion %)
+│   ├── progress.py      # Progress model (daily tasks, mood, RL signals)
+│   └── session.py       # UserSession model (refresh token selector-verifier)
+├── schemas/
+│   ├── auth.py          # RegisterRequest, LoginRequest, TokenResponse, etc.
+│   └── goals.py         # SetGoalRequest, DailyPlanResponse, etc.
+└── services/
+    ├── rl_engine.py     # Contextual Bandit (Thompson Sampling), behavior signals
+    ├── planner.py       # Daily plan generation, timetable, spaced repetition, XP
+    ├── llm_service.py   # Gemini API calls, plan generation, lesson content
+    ├── day_closer.py    # Auto-close daily tasks, RL reward dispatch
+    └── notifications.py # Streak risk, level-up, re-engagement signals
+
+alembic/                 # Database migration scripts
+tests/                   # pytest test suite
+```
+
+## Key Data Flows
+
+### Daily Plan Request (GET /api/plan)
+1. JWT auth → load User
+2. `rl_engine.get_stable_signal()` → cached RL decision (or fresh compute)
+3. `planner.generate_unified_daily_plan()` → queries Progress, builds tasks
+4. Coach message via Gemini (`generate_coach_message`)
+5. Notifications appended, response returned
+
+### Task Completion (POST /api/complete)
+1. JWT auth → load User + Progress row
+2. Mark `completed=True`, store actual duration, satisfaction
+3. `rl_engine.update_reward()` → update bandit alpha/beta
+4. `planner.award_xp()` + `update_streak()` → update User
+5. `reset_daily_state()` → clear cached RL decision
+
+## Current Limitations (to be fixed)
+
+| Issue | Location | Impact |
+|-------|----------|--------|
+| In-memory token blacklist | `security.py` `_blacklist` | Logout doesn't propagate across workers |
+| In-memory user versions | `security.py` `_user_versions` | Session invalidation broken in multi-worker |
+| In-memory coach cache | `planner.py` `_coach_cache` | Cache doesn't share between workers; can grow unbounded |
+| No lesson cache | `llm_service.py` | Every lesson call hits Gemini API |
+| No distributed lock on scheduler | `main.py` | Auto-close runs N times with N workers |
+| Rate limiter per-worker | `main.py` | Rate limits multiplied by worker count |

.gsd/DECISIONS.md

@@ -0,0 +1,51 @@
+# DECISIONS.md — Architecture Decision Records
+
+## ADR-001: Redis Fallback Strategy
+
+**Date:** 2026-06-21
+**Status:** Accepted
+
+**Context:** The system must support both local development (no Redis) and production (Redis required).
+
+**Decision:** The `redis_client.py` module will expose a wrapper that falls back to in-memory Python structures when `REDIS_URL` is not configured. This is implemented via a simple flag check so that no code in the callers needs to change.
+
+**Consequences:** Development experience is preserved. Security warning: running production without Redis silently degrades to in-memory state — we will log a WARNING if `APP_ENV=production` and `REDIS_URL` is unset.
+
+---
+
+## ADR-002: Distributed Scheduler Lock via Redis SET NX
+
+**Date:** 2026-06-21
+**Status:** Accepted
+
+**Context:** APScheduler runs inside the Uvicorn process. With `--workers 2`, both worker processes will independently trigger the 2 AM cron job, causing double XP/reward updates and double-closing of tasks.
+
+**Decision:** Use a Redis `SET NX EX` (set-if-not-exists with expiry) lock before running the job body. Only the worker that acquires the lock proceeds; the other silently skips. Lock TTL is set to 300 seconds (5 minutes) to ensure auto-release in case of a crash.
+
+**Alternatives Rejected:** Celery Beat in a separate container — too much infrastructure overhead for this milestone.
+
+---
+
+## ADR-003: slowapi Redis Storage Backend
+
+**Date:** 2026-06-21
+**Status:** Accepted
+
+**Context:** `slowapi` defaults to in-memory storage. With multiple workers, each maintains its own counter — a user can effectively multiply their allowed request count by the number of workers.
+
+**Decision:** Configure `slowapi.Limiter` with `storage_uri=settings.REDIS_URL` when Redis is available. This unifies the rate limit counters globally.
+
+**Consequences:** Rate limiting is now consistent and accurate. If Redis is unavailable, the limiter falls back to in-memory (same as current behavior) and logs a WARNING.
+
+---
+
+## ADR-004: Token Blacklist TTL = ACCESS_TOKEN_EXPIRE_MINUTES
+
+**Date:** 2026-06-21
+**Status:** Accepted
+
+**Context:** JWTs are blacklisted on logout. Storing them forever in Redis is wasteful.
+
+**Decision:** Set the Redis key TTL for each blacklisted `jti` to exactly `ACCESS_TOKEN_EXPIRE_MINUTES * 60` seconds. After that, the token would have expired anyway, so the blacklist entry is no longer needed.
+
+**Consequences:** Redis memory usage is bounded and proportional to `ACCESS_TOKEN_EXPIRE_MINUTES` × active logout rate.

.gsd/ROADMAP.md

@@ -0,0 +1,100 @@
+---
+milestone: Production Backend Hardening
+version: 1.0.0
+updated: 2026-06-21T10:43:00Z
+---
+
+# Roadmap
+
+> **Current Phase:** 1 - Foundation (Redis Client & Config)
+> **Status:** planning
+
+## Must-Haves (from SPEC)
+
+- [ ] Multi-worker safe token blacklist and session invalidation via Redis
+- [ ] APScheduler day-close job runs exactly once per cron tick, even with multiple workers
+- [ ] Distributed rate limits apply globally across all FastAPI workers
+- [ ] PostgreSQL connection pooling correctly tuned for production
+- [ ] SECRET_KEY validation raises on production startup if default is used
+
+---
+
+## Phases
+
+### Phase 1: Foundation — Redis Client & Config Hardening
+**Status:** ⬜ Not Started
+**Objective:** Introduce a centralized Redis connection helper and harden the config/database layers for production.
+**Files:**
+- `app/core/config.py` — Add production SECRET_KEY guard
+- `app/core/database.py` — Apply PG connection pooling
+- `app/core/redis_client.py` — [NEW] Singleton Redis client with graceful memory fallback
+
+**Plans:**
+- [ ] Plan 1.1: Create `redis_client.py` with connection pool and in-memory fallback
+- [ ] Plan 1.2: Harden `config.py` with production SECRET_KEY validation
+- [ ] Plan 1.3: Configure PostgreSQL pool size in `database.py`
+
+---
+
+### Phase 2: Distributed Security — Token Blacklist & Session Invalidation
+**Status:** ⬜ Not Started
+**Objective:** Replace in-memory `_blacklist` (set) and `_user_versions` (dict) in `security.py` with Redis-backed storage.
+**Depends on:** Phase 1
+**Files:**
+- `app/core/security.py` — Refactor blacklist and user version lookups
+
+**Plans:**
+- [ ] Plan 2.1: Migrate `_blacklist` to Redis with TTL matching access token expiry
+- [ ] Plan 2.2: Migrate `_user_versions` to Redis hash with `HSET/HGET`
+
+---
+
+### Phase 3: Distributed Rate Limiting & Caches
+**Status:** ⬜ Not Started
+**Objective:** Move the `slowapi` rate limiter and in-memory coach message cache to Redis.
+**Depends on:** Phase 1
+**Files:**
+- `app/core/limiter.py` — [NEW] Centralized limiter with Redis storage backend
+- `app/api/auth.py` — Update limiter import
+- `app/main.py` — Update limiter import and add TrustedHostMiddleware
+- `app/services/planner.py` — Replace `_coach_cache` dict with Redis
+
+**Plans:**
+- [ ] Plan 3.1: Create `limiter.py` with Redis storage, update auth.py and main.py imports
+- [ ] Plan 3.2: Replace `_coach_cache` in `planner.py` with Redis calls (TTL = 24h)
+
+---
+
+### Phase 4: Lesson Cache & Scheduler Lock
+**Status:** ⬜ Not Started
+**Objective:** Cache LLM-generated lesson content and prevent duplicate APScheduler job execution across workers.
+**Depends on:** Phase 1
+**Files:**
+- `app/services/llm_service.py` — Add Redis lesson cache
+- `app/main.py` — Add Redis-based distributed lock to APScheduler job
+
+**Plans:**
+- [ ] Plan 4.1: Cache `generate_lesson_text` results in Redis (TTL = 7 days)
+- [ ] Plan 4.2: Wrap APScheduler `_auto_close_job` with Redis `SET NX` distributed lock
+
+---
+
+## Progress Summary
+
+| Phase | Status | Plans | Complete |
+|-------|--------|-------|----------|
+| 1 | ⬜ | 0/3 | — |
+| 2 | ⬜ | 0/2 | — |
+| 3 | ⬜ | 0/2 | — |
+| 4 | ⬜ | 0/2 | — |
+
+---
+
+## Timeline
+
+| Phase | Started | Completed | Duration |
+|-------|---------|-----------|----------|
+| 1 | — | — | — |
+| 2 | — | — | — |
+| 3 | — | — | — |
+| 4 | — | — | — |

.gsd/SPEC.md

@@ -0,0 +1,42 @@
+# SPEC.md — Project Specification
+
+> **Status**: `FINALIZED`
+>
+> ⚠️ **Planning Lock**: No code may be written until this spec is marked `FINALIZED`.
+
+## Vision
+This project aims to refactor the HALE backend from a single-worker, in-memory state system into a robust, multi-node, production-ready backend. The primary driver is leveraging Redis for global state (caches, sessions, scheduler locks, rate limits) to safely allow horizontal scaling across multiple FastAPI workers and containers.
+
+## Goals
+1. **Shared Redis State** — Migrate `_coach_cache`, `_user_versions`, and `_blacklist` to Redis to prevent memory leaks and synchronize state across workers.
+2. **Distributed Job Locks** — Prevent the `apscheduler` daily cron job from running multiple times concurrently when `--workers 2` is used.
+3. **Distributed Rate Limiting** — Connect the `slowapi` limiter to Redis so that API rate limits apply globally instead of per worker.
+4. **Production Configuration** — Enforce PostgreSQL connection pooling and validate `SECRET_KEY` in production environments.
+5. **Lesson Caching** — Cache generated lesson content from Gemini to save tokens, speed up responses, and reduce API load.
+
+## Non-Goals (Out of Scope)
+- Complete rewrite of the frontend or AI logic.
+- Migration away from FastAPI or SQLAlchemy.
+- Removing SQLite entirely (it must remain supported for local development).
+
+## Constraints
+- Must remain compatible with the existing `docker-compose.yml` which defines a `redis` and `db` service.
+- The transition to Redis must degrade gracefully to memory in development if `REDIS_URL` is not set.
+
+## Success Criteria
+- [ ] Multiple FastAPI workers can boot and share the revoked token blacklist.
+- [ ] The `day_closer` auto-close job executes exactly once per scheduled time, regardless of worker count.
+- [ ] Rate limits successfully trigger based on aggregate requests across all workers.
+- [ ] Repeated calls for the same lesson topic load instantly from cache.
+
+## Technical Requirements (Optional)
+
+| Requirement | Priority | Notes |
+|-------------|----------|-------|
+| Redis integration | Must-have | The core of the production refactor |
+| Connection Pooling | Must-have | For PostgreSQL reliability |
+| Trusted Hosts | Should-have | Security best practice |
+
+---
+
+*Last updated: 2026-06-21*

.gsd/STATE.md

@@ -0,0 +1,49 @@
+---
+updated: 2026-06-21T10:51:00Z
+---
+
+# Project State
+
+## Current Position
+
+**Milestone:** Production Backend Hardening
+**Phase:** ALL PHASES COMPLETE
+**Status:** verifying
+**Plan:** —
+
+## Last Action
+
+Executed all 4 phases of the production hardening plan:
+- Phase 1: Created `redis_client.py`, hardened `config.py`, tuned DB pool
+- Phase 2: Centralized Redis import in `security.py`
+- Phase 3: Created `limiter.py`, updated `main.py` + `auth.py`, coach cache → Redis
+- Phase 4: Lesson cache in `llm_service.py` (7d TTL), scheduler distributed lock in `main.py`
+
+## Next Steps
+
+1. Run `pytest` to verify no regressions
+2. Spin up `docker-compose up --build` to verify multi-worker boot
+3. Run `/verify` to audit work against SPEC must-haves
+
+## Active Decisions
+
+| Decision | Choice | Made | Affects |
+|----------|--------|------|---------|
+| Redis fallback | Use in-memory fallback in dev when `REDIS_URL` not set | 2026-06-21 | All phases |
+| Scheduler strategy | Redis `SET NX` lock (keep single container) | 2026-06-21 | Phase 4 |
+| Lesson cache TTL | 7 days | 2026-06-21 | Phase 4 |
+| Coach message TTL | 24 hours | 2026-06-21 | Phase 3 |
+| Blacklist TTL | Match `ACCESS_TOKEN_EXPIRE_MINUTES` | 2026-06-21 | Phase 2 |
+
+## Blockers
+
+None
+
+## Concerns
+
+- APScheduler runs inside the Uvicorn process; a fully separate Celery worker would be cleaner but is out of scope for this milestone.
+- `secrets.token_hex` SECRET_KEY validation must not block startup in local dev.
+
+## Session Context
+
+Full backend audit completed. All in-memory state identified: `_blacklist` (set in security.py), `_user_versions` (dict in security.py), `_coach_cache` (dict in planner.py), and lesson text (not cached at all). Redis client will be the foundation (Phase 1) that unblocks all subsequent phases.

.gsd/examples/cross-platform.md

@@ -0,0 +1,99 @@
+# 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*

.gsd/examples/multi-wave-workflow.md

@@ -0,0 +1,256 @@
+# 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.*

.gsd/examples/quick-reference.md

@@ -0,0 +1,73 @@
+# 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!*

.gsd/examples/workflow-example.md

@@ -0,0 +1,139 @@
+# 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.*

.gsd/templates/DEBUG.md

@@ -0,0 +1,123 @@
+# 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.

.gsd/templates/PLAN.md

@@ -0,0 +1,90 @@
+# 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.