gsd-ag 1.0.0

package/.gsd/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*

package/.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*

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

@@ -0,0 +1,256 @@
+# Multi-Wave Workflow Example
+
+This example demonstrates a complete GSD workflow with:
+- Short spec
+- Plan breakdown
+- 2-wave execution
+- Verification with commands
+- State snapshots
+
+---
+
+## Example: Add User Authentication
+
+### 1. SPEC.md (Finalized)
+
+```markdown
+---
+status: FINALIZED
+updated: 2026-02-07
+---
+
+# User Authentication Feature
+
+## Overview
+Add login/logout functionality with JWT tokens.
+
+## Requirements
+1. POST /api/auth/login endpoint
+2. POST /api/auth/logout endpoint
+3. JWT stored in httpOnly cookie
+4. Protected route middleware
+
+## Success Criteria
+- User can login with email/password
+- Invalid credentials return 401
+- Protected routes require valid JWT
+- Logout clears the cookie
+```
+
+---
+
+### 2. ROADMAP.md (Phase Entry)
+
+```markdown
+## Phase 1: User Authentication
+
+- [ ] Plan 1.1: Auth endpoints (Wave 1)
+- [ ] Plan 1.2: Protected middleware (Wave 2)
+```
+
+---
+
+### 3. PLAN 1.1 (Wave 1)
+
+```xml
+---
+phase: 1
+plan: 1
+type: implementation
+wave: 1
+---
+
+<objective>
+Create login and logout endpoints with JWT handling.
+</objective>
+
+<context>
+Files to read: src/app/api/ structure, existing auth if any
+</context>
+
+<tasks>
+<task type="auto" effort="medium">
+  <name>Create login endpoint</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>
+    Create POST handler accepting {email, password}.
+    Query users table, compare password with bcrypt.
+    On success: generate JWT, set httpOnly cookie, return 200.
+    On failure: return 401 with generic error.
+  </action>
+  <verify>curl -X POST localhost:3000/api/auth/login -d '{"email":"test@example.com","password":"test123"}'</verify>
+  <done>Valid credentials return 200 + Set-Cookie header</done>
+</task>
+
+<task type="auto" effort="low">
+  <name>Create logout endpoint</name>
+  <files>src/app/api/auth/logout/route.ts</files>
+  <action>
+    Create POST handler that clears the auth cookie.
+    Return 200 on success.
+  </action>
+  <verify>curl -X POST localhost:3000/api/auth/logout --cookie "token=..."</verify>
+  <done>Cookie is cleared, response is 200</done>
+</task>
+</tasks>
+```
+
+---
+
+### 4. Wave 1 Execution
+
+**Task 1 Commit:**
+```
+git commit -m "feat(phase-1): create login endpoint"
+```
+
+**Task 2 Commit:**
+```
+git commit -m "feat(phase-1): create logout endpoint"
+```
+
+---
+
+### 5. Wave 1 State Snapshot
+
+```markdown
+---
+wave: 1
+phase: 1
+created: 2026-02-07T10:30:00
+status: complete
+---
+
+# Wave 1 State Snapshot
+
+## Objective
+Create authentication endpoints.
+
+## Changes Realized
+- Created login endpoint with JWT generation
+- Created logout endpoint with cookie clearing
+- Added bcrypt password comparison
+
+## Files Touched
+| File | Change Type | Description |
+|------|-------------|-------------|
+| src/app/api/auth/login/route.ts | created | Login handler |
+| src/app/api/auth/logout/route.ts | created | Logout handler |
+
+## Verification Results
+| Check | Command | Result |
+|-------|---------|--------|
+| Login works | `curl -X POST .../login` | ✅ 200 + cookie |
+| Logout works | `curl -X POST .../logout` | ✅ 200 + cleared |
+
+## Commits in This Wave
+| Hash | Message |
+|------|---------|
+| abc123 | feat(phase-1): create login endpoint |
+| def456 | feat(phase-1): create logout endpoint |
+
+## TODO for Next Wave
+1. Create auth middleware
+2. Apply to protected routes
+```
+
+---
+
+### 6. PLAN 1.2 (Wave 2)
+
+```xml
+---
+phase: 1
+plan: 2
+type: implementation
+wave: 2
+depends_on: [1]
+---
+
+<objective>
+Create middleware to protect routes requiring authentication.
+</objective>
+
+<context>
+Wave 1 complete: login/logout endpoints exist.
+JWT is stored in httpOnly cookie named "token".
+</context>
+
+<tasks>
+<task type="auto" effort="high">
+  <name>Create auth middleware</name>
+  <files>src/middleware/auth.ts</files>
+  <action>
+    Create middleware that:
+    1. Reads JWT from cookie
+    2. Verifies signature with jose
+    3. Attaches user to request
+    4. Returns 401 if invalid/missing
+  </action>
+  <verify>Import and call middleware with mock request</verify>
+  <done>Valid JWT passes, invalid/missing returns 401</done>
+</task>
+
+<task type="auto" effort="medium">
+  <name>Apply middleware to protected route</name>
+  <files>src/app/api/user/profile/route.ts</files>
+  <action>
+    Create example protected route.
+    Apply auth middleware.
+    Return user data if authenticated.
+  </action>
+  <verify>curl localhost:3000/api/user/profile with and without cookie</verify>
+  <done>With cookie: 200 + data. Without: 401</done>
+</task>
+</tasks>
+```
+
+---
+
+### 7. Wave 2 Execution & Snapshot
+
+**Commits:**
+```
+git commit -m "feat(phase-1): create auth middleware"
+git commit -m "feat(phase-1): apply middleware to profile route"
+```
+
+**State Snapshot:** (similar format to Wave 1)
+
+---
+
+### 8. Verification
+
+```bash
+# Full verification sequence
+curl -X POST localhost:3000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"secret"}' \
+  -c cookies.txt
+
+# Expected: 200 + Set-Cookie: token=...
+
+curl localhost:3000/api/user/profile -b cookies.txt
+# Expected: 200 + user data
+
+curl localhost:3000/api/user/profile
+# Expected: 401
+
+curl -X POST localhost:3000/api/auth/logout -b cookies.txt
+# Expected: 200 + cookie cleared
+```
+
+---
+
+## Key Takeaways
+
+1. **Waves group dependent work** — Wave 2 waited for Wave 1
+2. **State snapshots preserve context** — Each wave ends with documented state
+3. **Atomic commits per task** — Easy to trace and revert
+4. **Verification built into plan** — No "trust me, it works"
+5. **Effort hints model selection** — `high` effort = use reasoning model
+
+---
+
+*See PROJECT_RULES.md for wave execution rules.*
+*See templates/state_snapshot.md for snapshot format.*

package/.gsd/examples/quick-reference.md

@@ -0,0 +1,73 @@
+# GSD Quick Reference Card
+
+## Workflow Lifecycle
+
+```
+┌─────────┐    ┌─────────┐    ┌──────────┐    ┌─────────┐
+│  /map   │ →  │  /plan  │ →  │ /execute │ →  │ /verify │
+│         │    │         │    │          │    │         │
+│ Analyze │    │ Create  │    │   Run    │    │  Check  │
+│codebase │    │ phases  │    │  tasks   │    │  work   │
+└─────────┘    └─────────┘    └──────────┘    └─────────┘
+                                   ↑              │
+                                   └──────────────┘
+                                   (if gaps found)
+```
+
+## All Commands
+
+| Command | Args | Purpose |
+|---------|------|---------|
+| `/map` | - | Analyze codebase → ARCHITECTURE.md |
+| `/plan` | `[phase]` | Create PLAN.md files for phase |
+| `/execute` | `phase [--gaps-only]` | Run plans with wave execution |
+| `/verify` | `phase` | Validate with empirical proof |
+| `/debug` | `description` | Systematic debugging |
+| `/progress` | - | Show current position |
+| `/pause` | - | Save state, end session |
+| `/resume` | - | Load state, start session |
+| `/add-todo` | `item [--priority]` | Quick capture |
+| `/check-todos` | `[--all]` | List pending items |
+
+## Core Rules
+
+| Rule | Enforcement |
+|------|-------------|
+| 🔒 Planning Lock | No code until SPEC finalized |
+| 💾 State Persistence | Update STATE.md after tasks |
+| 🧹 Context Hygiene | 3 failures → fresh session |
+| ✅ Empirical Validation | Proof required for "done" |
+
+## Key Files
+
+| File | Purpose | Updated By |
+|------|---------|------------|
+| SPEC.md | Vision (finalize first!) | User |
+| ROADMAP.md | Phase definitions | /plan |
+| STATE.md | Session memory | All |
+| ARCHITECTURE.md | System design | /map |
+| TODO.md | Quick capture | /add-todo |
+
+## XML Task Structure
+
+```xml
+<task type="auto">
+  <name>Clear name</name>
+  <files>exact/path.ts</files>
+  <action>Specific instructions</action>
+  <verify>Executable command</verify>
+  <done>Measurable criteria</done>
+</task>
+```
+
+## Priority Indicators
+
+| Priority | Icon |
+|----------|------|
+| High | 🔴 |
+| Medium | 🟡 |
+| Low | 🟢 |
+
+---
+
+*Print this for quick reference!*