gsd-ag 1.0.0

package/.agent/workflows/execute.md

@@ -0,0 +1,325 @@
+---
+description: The Engineer — Execute a specific phase with focused context
+argument-hint: "<phase-number> [--gaps-only]"
+---
+
+# /execute Workflow
+
+<role>
+You are a GSD executor orchestrator. You manage wave-based parallel execution of phase plans.
+
+**Core responsibilities:**
+- Validate phase exists and has plans
+- Discover and group plans by execution wave
+- Spawn focused execution for each plan
+- Verify phase goal after all plans complete
+- Update roadmap and state on completion
+</role>
+
+<objective>
+Execute all plans in a phase using wave-based parallel execution.
+
+Orchestrator stays lean: discover plans, analyze dependencies, group into waves, execute sequentially within waves, verify against phase goal.
+
+**Context budget:** ~15% orchestrator, fresh context per plan execution.
+</objective>
+
+<context>
+**Phase:** $ARGUMENTS (required - phase number to execute)
+
+**Flags:**
+- `--gaps-only` — Execute only gap closure plans (created by `/verify` when issues found)
+- `--auto` — Auto-advance mode (proceed directly to next logical phase or verify without stopping)
+
+**Required files:**
+- `.gsd/ROADMAP.md` — Phase definitions
+- `.gsd/STATE.md` — Current position
+- `.gsd/phases/{phase}/` — Phase directory with PLAN.md files
+</context>
+
+<process>
+
+## 1. Validate Environment
+
+**PowerShell:**
+```powershell
+Test-Path ".gsd/ROADMAP.md"
+Test-Path ".gsd/STATE.md"
+```
+
+**Bash:**
+```bash
+test -f ".gsd/ROADMAP.md"
+test -f ".gsd/STATE.md"
+```
+
+**If not found:** Error — user should run `/plan` first.
+
+---
+
+## 2. Validate Phase Exists
+
+**PowerShell:**
+```powershell
+# Check phase exists in roadmap
+Select-String -Path ".gsd/ROADMAP.md" -Pattern "Phase $PHASE:"
+```
+
+**Bash:**
+```bash
+# Check phase exists in roadmap
+grep "Phase $PHASE:" ".gsd/ROADMAP.md"
+```
+
+**If not found:** Error with available phases from ROADMAP.md.
+
+---
+
+## 3. Ensure Phase Directory Exists
+
+**PowerShell:**
+```powershell
+$PHASE_DIR = ".gsd/phases/$PHASE"
+if (-not (Test-Path $PHASE_DIR)) {
+    New-Item -ItemType Directory -Path $PHASE_DIR
+}
+```
+
+**Bash:**
+```bash
+PHASE_DIR=".gsd/phases/$PHASE"
+mkdir -p "$PHASE_DIR"
+```
+
+---
+
+## 4. Discover Plans
+
+**PowerShell:**
+```powershell
+Get-ChildItem "$PHASE_DIR/*-PLAN.md"
+```
+
+**Bash:**
+```bash
+ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+```
+
+**Check for existing summaries** (completed plans):
+
+**PowerShell:**
+```powershell
+Get-ChildItem "$PHASE_DIR/*-SUMMARY.md"
+```
+
+**Bash:**
+```bash
+ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+**Build list of incomplete plans** (PLAN without matching SUMMARY).
+
+**If `--gaps-only`:** Filter to only plans with `gap_closure: true` in frontmatter.
+
+**If no incomplete plans found:** Phase already complete, skip to step 8.
+
+---
+
+## 5. Group Plans by Wave
+
+Read `wave` field from each plan's frontmatter:
+
+```yaml
+---
+phase: 1
+plan: 2
+wave: 1
+---
+```
+
+**Group plans by wave number.** Lower waves execute first.
+
+Display wave structure:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► EXECUTING PHASE {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Wave 1: {plan-1}, {plan-2}
+Wave 2: {plan-3}
+
+{X} plans across {Y} waves
+```
+
+---
+
+## 6. Execute Waves
+
+For each wave in order:
+
+### 6a. Execute Plans in Wave
+For each plan in the current wave:
+
+1. **Load plan context** — Read only the PLAN.md file
+2. **Execute tasks** — Follow `<task>` blocks in order
+3. **Verify each task** — Run `<verify>` commands
+4. **Commit per task:**
+   ```bash
+   git add -A
+   git commit -m "feat(phase-{N}): {task-name}"
+   ```
+5. **Create SUMMARY.md** — Document what was done
+
+### 6b. Verify Wave Complete
+Check all plans in wave have SUMMARY.md files.
+
+### 6c. Proceed to Next Wave
+Only after current wave fully completes.
+
+---
+
+## 7. Verify Phase Goal
+
+After all waves complete:
+
+1. **Read phase goal** from ROADMAP.md
+2. **Check must-haves** against actual codebase (not SUMMARY claims)
+3. **Run verification commands** specified in phase
+
+**Create VERIFICATION.md:**
+```markdown
+## Phase {N} Verification
+
+### Must-Haves
+- [x] Must-have 1 — VERIFIED (evidence: ...)
+- [ ] Must-have 2 — FAILED (reason: ...)
+
+### Verdict: PASS / FAIL
+```
+
+**Route by verdict:**
+- `PASS` → Continue to step 8
+- `FAIL` → Create gap closure plans, offer `/execute {N} --gaps-only`
+
+---
+
+## 8. Update Roadmap and State
+
+**Update ROADMAP.md:**
+```markdown
+### Phase {N}: {Name}
+**Status**: ✅ Complete
+```
+
+**Update STATE.md:**
+```markdown
+## Current Position
+- **Phase**: {N} (completed)
+- **Task**: All tasks complete
+- **Status**: Verified
+
+## Last Session Summary
+Phase {N} executed successfully. {X} plans, {Y} tasks completed.
+
+## Next Steps
+1. Proceed to Phase {N+1}
+```
+
+---
+
+## 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
+
+</process>
+
+<offer_next>
+Output based on status:
+
+**Route A: Phase complete, more phases remain**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE {N} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{X} plans executed
+Goal verified ✓
+
+───────────────────────────────────────────────────────
+
+▶ Next Up
+Phase {N+1}: {Name}
+
+/plan {N+1}  — create execution plans
+/execute {N+1} — execute directly (if plans exist)
+
+───────────────────────────────────────────────────────
+```
+
+**Route B: All phases complete**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► MILESTONE COMPLETE 🎉
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+All phases completed and verified.
+
+───────────────────────────────────────────────────────
+```
+
+**Route C: Gaps found**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE {N} GAPS FOUND ⚠
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{X}/{Y} must-haves verified
+Gap closure plans created.
+
+/execute {N} --gaps-only — execute fix plans
+
+───────────────────────────────────────────────────────
+```
+
+**If `--auto` flag was set:**
+Do not show the manual output prompts above. Instead:
+- If Route A: Immediately invoke `/plan {N+1} --auto` using your tools.
+- If Route B: Stop and notify user of milestone completion.
+- If Route C: Immediately invoke `/execute {N} --gaps-only` to fix the gaps.
+</offer_next>
+
+<context_hygiene>
+**After 3 failed debugging attempts:**
+1. Stop current approach
+2. Document to `.gsd/STATE.md` what was tried
+3. Recommend `/pause` for fresh session
+</context_hygiene>
+
+<related>
+## Related
+
+### Workflows
+| Command | Relationship |
+|---------|--------------|
+| `/plan` | Creates PLAN.md files that /execute runs |
+| `/verify` | Validates work after /execute completes |
+| `/debug` | Use when tasks fail verification |
+| `/pause` | Use after 3 debugging failures |
+
+### Skills
+| Skill | Purpose |
+|-------|---------|
+| `executor` | Detailed execution protocol |
+| `context-health-monitor` | 3-strike rule enforcement |
+| `empirical-validation` | Verification requirements |
+</related>

package/.agent/workflows/health.md

@@ -0,0 +1,122 @@
+---
+description: Health Check — Validate directory and state integrity
+argument-hint: "[--repair]"
+---
+
+# /health Workflow
+
+<role>
+You are a GSD Health Check orchestrator. Your job is to validate `.gsd/` directory integrity and report actionable issues.
+</role>
+
+<objective>
+Check for missing files, invalid configurations, inconsistent state, and orphaned plans. Optionally repair auto-fixable issues.
+</objective>
+
+<context>
+**Flags:**
+- `--repair` — Auto-fix repairable issues
+
+**Required files to check:**
+- `.gsd/ROADMAP.md`
+- `.gsd/STATE.md`
+- `.gsd/PROJECT_RULES.md`
+- `.gsd/SPEC.md`
+</context>
+
+<process>
+
+## 1. Parse Arguments
+Determine if the `--repair` flag is active.
+
+## 2. Validate Core Documents
+
+Run checks:
+1. Does `.agent/workflows/` exist and contain at least 5 standard workflows?
+2. Does `.gsd/ROADMAP.md` exist?
+3. Does `.gsd/STATE.md` exist?
+4. Does `.gsd/SPEC.md` exist?
+
+If any missing, note it as an Error [E00X] and set health to **BROKEN**.
+
+## 3. Validate Phase Directories
+
+Cross-reference `.gsd/ROADMAP.md` with `.gsd/phases/` directories:
+1. Parse roadmap for Phase numbers.
+2. Ensure there's a `.gsd/phases/{N}/` directory for each phase.
+3. Check Phase naming convention (e.g. `01-setup`, `02-auth`).
+4. Look for plans `*.PLAN.md` without matching `*.SUMMARY.md` across phases.
+
+If discrepancies are found:
+- Warning [W00X] phase directory mismatch.
+- Warning [W00Y] phase on disk but not in roadmap.
+- Info [I00X] Plan without SUMMARY (may be in progress).
+
+## 4. Validate Structural Integrity Using Script
+
+Run the validation script to check structural integrity of templates, workflows, and skills:
+```bash
+bun .gsd/scripts/validate-all.ts
+```
+If errors occur, parse the output and include in the health check.
+
+## 5. Attempt Repairs (if `--repair`)
+
+For issues marked as repairable (e.g., missing `.gsd/STATE.md` but roadmap exists):
+- **STATE.md recovery**: Create fresh `STATE.md` based on roadmap structure.
+- **Phase matching**: Create missing `.gsd/phases/{N}/` directories based on roadmap.
+
+Log what repairs were performed.
+
+## 6. Report Status
+
+Output the results clearly.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Errors: N | Warnings: N | Info: N
+```
+
+**If repairs were performed:**
+```
+## Repairs Performed
+- ✓ STATE.md: Regenerated from roadmap
+- ✓ .gsd/phases/01/: Directory created
+```
+
+**If errors exist:**
+```
+## Errors
+- [E001] .gsd/ROADMAP.md not found
+  Fix: Run /plan to create
+```
+
+**If warnings exist:**
+```
+## Warnings
+- [W001] STATE.md references phase 5, but only phases 1-3 exist
+  Fix: Run /health --repair to regenerate
+```
+
+**If info exists:**
+```
+## Info
+- [I001] phases/02/02-01-PLAN.md has no SUMMARY.md
+  Note: May be in progress
+```
+
+**Footer (if repairable issues exist and --repair was NOT used):**
+```
+---
+N issues can be auto-repaired. Run: /health --repair
+```
+</process>
+
+<offer_next>
+If repairable issues exist and `--repair` was not used, prompt the user:
+"Would you like to run `/health --repair` to fix these issues automatically?"
+</offer_next>

package/.agent/workflows/help.md

@@ -0,0 +1,96 @@
+---
+description: Show all available GSD commands
+---
+
+# /help Workflow
+
+<objective>
+Display all available GSD commands with descriptions and usage hints.
+</objective>
+
+<process>
+
+**First, read and display the version:**
+
+**PowerShell:**
+```powershell
+$version = Get-Content "VERSION" -ErrorAction SilentlyContinue
+if (-not $version) { $version = "unknown" }
+```
+
+**Bash:**
+```bash
+version=$(cat VERSION 2>/dev/null || echo "unknown")
+```
+
+**Then display help with version in header:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► HELP (v{version})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CORE WORKFLOW
+─────────────
+/map              Analyze codebase → ARCHITECTURE.md
+/plan [N]         Create PLAN.md files for phase N
+/execute [N]      Wave-based execution with atomic commits
+/verify [N]       Must-haves validation with proof
+/debug [desc]     Systematic debugging (3-strike rule)
+
+PROJECT SETUP
+─────────────
+/new-project      Deep questioning → SPEC.md
+/new-milestone    Create milestone with phases
+/complete-milestone   Archive completed milestone
+/audit-milestone  Review milestone quality
+
+PHASE MANAGEMENT
+────────────────
+/add-phase        Add phase to end of roadmap
+/insert-phase     Insert phase (renumbers subsequent)
+/remove-phase     Remove phase (with safety checks)
+/discuss-phase    Clarify scope before planning
+/research-phase   Deep technical research
+/list-phase-assumptions   Surface planning assumptions
+/plan-milestone-gaps      Create gap closure plans
+
+NAVIGATION & STATE
+──────────────────
+/progress         Show current position in roadmap
+/pause            Save state for session handoff
+/resume           Restore from last session
+/add-todo         Quick capture idea
+/check-todos      List pending items
+
+UTILITIES
+─────────
+/help             Show this help
+
+───────────────────────────────────────────────────────
+
+QUICK START
+───────────
+1. /new-project      → Initialize with deep questioning
+2. /plan 1           → Create Phase 1 plans
+3. /execute 1        → Implement Phase 1
+4. /verify 1         → Confirm it works
+5. Repeat
+
+───────────────────────────────────────────────────────
+
+CORE RULES
+──────────
+🔒 Planning Lock     No code until SPEC.md is FINALIZED
+💾 State Persistence Update STATE.md after every task
+🧹 Context Hygiene   3 failures → state dump → fresh session
+✅ Empirical Valid.  Proof required, no "it should work"
+
+───────────────────────────────────────────────────────
+
+📚 Docs: .gsd/GSD-STYLE.md, .gsd/examples/
+
+───────────────────────────────────────────────────────
+```
+
+</process>

package/.agent/workflows/insert-phase.md

@@ -0,0 +1,109 @@
+---
+description: Insert a phase between existing phases (renumbers subsequent)
+argument-hint: "<position> <phase-name>"
+---
+
+# /insert-phase Workflow
+
+<objective>
+Insert a new phase at a specific position, renumbering all subsequent phases.
+</objective>
+
+<process>
+
+## 1. Parse Arguments
+
+Extract:
+- **Position** — Where to insert (e.g., 2 inserts before current Phase 2)
+- **Name** — Phase title
+
+---
+
+## 2. Validate Position
+
+**PowerShell:**
+```powershell
+$totalPhases = (Select-String -Path ".gsd/ROADMAP.md" -Pattern "### Phase \d+").Count
+if ($position -lt 1 -or $position -gt $totalPhases + 1) {
+    Write-Error "Invalid position. Valid: 1-$($totalPhases + 1)"
+}
+```
+
+**Bash:**
+```bash
+total_phases=$(grep -c "### Phase [0-9]" ".gsd/ROADMAP.md")
+if [ "$position" -lt 1 ] || [ "$position" -gt $((total_phases + 1)) ]; then
+    echo "Error: Invalid position. Valid: 1-$((total_phases + 1))" >&2
+fi
+```
+
+---
+
+## 3. Gather Phase Information
+
+Ask for:
+- **Objective** — What this phase achieves
+- **Dependencies** — What it needs from earlier phases
+
+---
+
+## 4. Renumber Existing Phases
+
+For phases >= position, increment phase number by 1.
+
+**Also update:**
+- Phase directory names (`.gsd/phases/{N}/`)
+- References in PLAN.md files
+- Dependencies in ROADMAP.md
+
+---
+
+## 5. Insert New Phase
+
+Add at position with correct numbering.
+
+---
+
+## 6. Update STATE.md
+
+If currently in a phase >= position, update position reference.
+
+---
+
+## 7. Commit
+
+```bash
+git add -A
+git commit -m "docs: insert phase {N} - {name} (renumbered {M} phases)"
+```
+
+---
+
+## 8. Display Result
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE INSERTED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Inserted: Phase {N}: {name}
+Renumbered: Phases {N+1} through {M}
+
+───────────────────────────────────────────────────────
+
+▶ NEXT
+
+/plan {N} — Create plans for new phase
+/progress — See updated roadmap
+
+───────────────────────────────────────────────────────
+```
+
+</process>
+
+<warning>
+Phase insertion can be disruptive. Consider:
+- In-progress phases may have commits referencing old numbers
+- Existing plans reference phase numbers
+- Use sparingly and early in milestone lifecycle
+</warning>