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