gsd-ag 1.0.0

package/.gsd/examples/workflow-example.md

@@ -0,0 +1,139 @@
+# GSD Workflow Example
+
+> A complete walkthrough of using GSD from start to finish.
+
+## Scenario: Building a Simple Todo API
+
+### Step 1: Define the Spec
+
+First, fill out `.gsd/SPEC.md`:
+
+```markdown
+# SPEC.md
+
+> **Status**: `FINALIZED`
+
+## Vision
+A simple RESTful API for managing todo items.
+
+## Goals
+1. CRUD operations for todos
+2. Persistence to SQLite
+3. Input validation
+
+## Success Criteria
+- [ ] POST /todos creates a todo
+- [ ] GET /todos returns list
+- [ ] DELETE /todos/:id removes item
+```
+
+---
+
+### Step 2: Map the Codebase (if existing)
+
+```
+/map
+```
+
+This creates:
+- `.gsd/ARCHITECTURE.md` — Current structure
+- `.gsd/STACK.md` — Technologies in use
+
+---
+
+### Step 3: Plan the Phases
+
+```
+/plan 1
+```
+
+GSD analyzes the SPEC and creates `.gsd/phases/1/` with PLAN.md files:
+
+```markdown
+# Plan 1.1: Database Setup
+
+## Objective
+Create SQLite database with todos table.
+
+## Tasks
+
+<task type="auto">
+  <name>Initialize SQLite database</name>
+  <files>src/db.ts</files>
+  <action>
+    Create SQLite connection using better-sqlite3.
+    Create todos table with: id, title, completed, created_at.
+  </action>
+  <verify>node -e "require('./src/db')" exits without error</verify>
+  <done>Database file exists, table created</done>
+</task>
+```
+
+---
+
+### Step 4: Execute the Phase
+
+```
+/execute 1
+```
+
+GSD:
+1. Loads Plan 1.1
+2. Executes tasks in order
+3. Runs verify commands
+4. Creates atomic commits
+5. Creates SUMMARY.md
+6. Proceeds to Plan 1.2
+7. Verifies phase goal
+
+---
+
+### Step 5: Verify the Work
+
+```
+/verify 1
+```
+
+GSD:
+1. Extracts must-haves from phase
+2. Runs verification commands
+3. Captures evidence
+4. Creates VERIFICATION.md
+5. Reports pass/fail
+
+---
+
+### Step 6: Continue or Debug
+
+**If verified:**
+```
+/plan 2      → Plan next phase
+/execute 2   → Execute next phase
+```
+
+**If issues found:**
+```
+/execute 1 --gaps-only   → Run fix plans
+/debug "API returns 500" → Debug the issue
+```
+
+---
+
+## Quick Commands Reference
+
+| Command | When to Use |
+|---------|-------------|
+| `/map` | Analyze existing codebase |
+| `/plan [N]` | Create plans for phase N |
+| `/execute [N]` | Run all plans in phase N |
+| `/verify [N]` | Confirm phase N works |
+| `/debug [issue]` | Fix a problem |
+| `/progress` | See current status |
+| `/pause` | End session, save state |
+| `/resume` | Start new session |
+| `/add-todo` | Capture quick idea |
+| `/check-todos` | See pending items |
+
+---
+
+*This example demonstrates the GSD methodology flow.*

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

package/.gsd/templates/DEBUG.md

@@ -0,0 +1,123 @@
+# Debug Template
+
+Template for `.gsd/debug/[slug].md` — active debug session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | resolved
+trigger: "[verbatim user input]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - always reflects NOW -->
+
+hypothesis: [current theory being tested]
+test: [how testing it]
+expecting: [what result means if true/false]
+next_action: [immediate next step]
+
+## Symptoms
+<!-- Written during gathering, then immutable -->
+
+expected: [what should happen]
+actual: [what actually happens]
+errors: [error messages if any]
+reproduction: [how to trigger]
+started: [when it broke / always broken]
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating after context reset -->
+
+- hypothesis: [theory that was wrong]
+  evidence: [what disproved it]
+  timestamp: [when eliminated]
+
+## Evidence
+<!-- APPEND only - facts discovered during investigation -->
+
+- timestamp: [when found]
+  checked: [what was examined]
+  found: [what was observed]
+  implication: [what this means]
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: [empty until found]
+fix: [empty until applied]
+verification: [empty until verified]
+files_changed: []
+```
+
+---
+
+## Section Rules
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: OVERWRITE - reflects current phase
+- `trigger`: IMMUTABLE - verbatim user input, never changes
+- `created`: IMMUTABLE - set once
+- `updated`: OVERWRITE - update on every change
+
+**Current Focus:**
+- OVERWRITE entirely on each update
+- Always reflects what AI is doing RIGHT NOW
+- If AI reads this after session reset, it knows exactly where to resume
+- Fields: hypothesis, test, expecting, next_action
+
+**Symptoms:**
+- Written during initial gathering phase
+- IMMUTABLE after gathering complete
+- Reference point for what we're trying to fix
+
+**Eliminated:**
+- APPEND only - never remove entries
+- Prevents re-investigating dead ends after context reset
+- Critical for efficiency across session boundaries
+
+**Evidence:**
+- APPEND only - never remove entries
+- Facts discovered during investigation
+- Builds the case for root cause
+
+**Resolution:**
+- OVERWRITE as understanding evolves
+- Final state shows confirmed root cause and verified fix
+
+---
+
+## Lifecycle
+
+**Creation:** When /debug is called
+- Create file with trigger from user input
+- Set status to "gathering"
+- next_action = "gather symptoms"
+
+**During investigation:**
+- OVERWRITE Current Focus with each hypothesis
+- APPEND to Evidence with each finding
+- APPEND to Eliminated when hypothesis disproved
+
+**On resolution:**
+- status → "resolved"
+- Move file to .gsd/debug/resolved/
+
+---
+
+## Resume Behavior
+
+When AI reads this file after session reset:
+
+1. Parse frontmatter → know status
+2. Read Current Focus → know exactly what was happening
+3. Read Eliminated → know what NOT to retry
+4. Read Evidence → know what's been learned
+5. Continue from next_action
+
+The file IS the debugging brain.

package/.gsd/templates/PLAN.md

@@ -0,0 +1,90 @@
+# PLAN.md Template
+
+> Copy this template when creating execution plans.
+
+```markdown
+---
+phase: {N}
+plan: {M}
+wave: {W}
+gap_closure: false
+---
+
+# Plan {N}.{M}: {Descriptive Name}
+
+## Objective
+{One paragraph explaining what this plan delivers and why it matters}
+
+## Context
+Load these files for context:
+- .gsd/SPEC.md
+- .gsd/ARCHITECTURE.md
+- {relevant source files}
+
+## Tasks
+
+<task type="auto">
+  <name>{Clear, specific task name}</name>
+  <files>
+    {exact/file/path1.ext}
+    {exact/file/path2.ext}
+  </files>
+  <action>
+    {Specific implementation instructions}
+    
+    Steps:
+    1. {Step 1}
+    2. {Step 2}
+    3. {Step 3}
+    
+    AVOID: {common mistake} because {reason}
+    USE: {preferred approach} because {reason}
+  </action>
+  <verify>
+    {Executable command or check}
+    Example: npm test -- --testNamePattern="auth"
+    Example: curl -X POST localhost:3000/api/login
+  </verify>
+  <done>
+    {Measurable acceptance criteria}
+    Example: Valid credentials → 200 + Set-Cookie, invalid → 401
+  </done>
+</task>
+
+<task type="auto">
+  <name>{Task 2 name}</name>
+  <files>{files}</files>
+  <action>{instructions}</action>
+  <verify>{command}</verify>
+  <done>{criteria}</done>
+</task>
+
+## Must-Haves
+After all tasks complete, verify:
+- [ ] {Must-have 1 — derived from phase goal}
+- [ ] {Must-have 2}
+
+## Success Criteria
+- [ ] All tasks verified passing
+- [ ] Must-haves confirmed
+- [ ] No regressions in tests
+```
+
+## Task Types
+
+| Type | Use For | Behavior |
+|------|---------|----------|
+| `auto` | Everything Claude can do independently | Fully autonomous |
+| `checkpoint:human-verify` | Visual/functional verification | Pauses for user |
+| `checkpoint:decision` | Implementation choices | Pauses for user |
+
+## Wave Assignment
+
+| Wave | Use For |
+|------|---------|
+| 1 | Foundation (types, schemas, utilities) |
+| 2 | Core implementations |
+| 3 | Integration and validation |
+
+Plans in the same wave can run in parallel.
+Later waves depend on earlier waves.

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

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