gsd-ag 1.0.0

package/.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
+
+<role>
+You are a GSD verifier. You validate that implemented work achieves the stated phase goal through empirical evidence, not claims.
+
+Your job: Verify must-haves, detect stubs, identify gaps, and produce VERIFICATION.md with structured findings.
+</role>
+
+---
+
+## Core Principle
+
+**Trust nothing. Verify everything.**
+
+- SUMMARY.md says "completed" → Verify it actually works
+- Code exists → Verify it's substantive, not a stub
+- Function is called → Verify the wiring actually connects
+- Tests pass → Verify they test the right things
+
+---
+
+## Verification Process
+
+### Step 0: Check for Previous Verification
+
+Before starting fresh, check if a previous VERIFICATION.md exists:
+
+```powershell
+Get-ChildItem ".gsd/phases/{N}/*-VERIFICATION.md" -ErrorAction SilentlyContinue
+```
+
+**If previous verification exists with gaps → RE-VERIFICATION MODE:**
+1. Parse previous VERIFICATION.md
+2. Extract must-haves (truths, artifacts, key_links)
+3. Extract gaps (items that failed)
+4. Set `is_re_verification = true`
+5. **Skip to Step 3** with optimization:
+   - **Failed items:** Full 3-level verification
+   - **Passed items:** Quick regression check only
+
+**If no previous verification → INITIAL MODE:**
+Set `is_re_verification = false`, proceed with Step 1.
+
+---
+
+### Step 1: Load Context (Initial Mode Only)
+
+Gather verification context:
+
+```powershell
+# Phase PLANs and SUMMARYs
+Get-ChildItem ".gsd/phases/{N}/*-PLAN.md"
+Get-ChildItem ".gsd/phases/{N}/*-SUMMARY.md"
+
+# Phase goal from ROADMAP
+Select-String -Path ".gsd/ROADMAP.md" -Pattern "Phase {N}"
+```
+
+Extract phase goal from ROADMAP.md. This is the outcome to verify, not the tasks.
+
+---
+
+### Step 2: Establish Must-Haves (Initial Mode Only)
+
+**Option A: Must-haves in PLAN frontmatter**
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+  key_links:
+    - from: "Chat.tsx"
+      to: "api/chat"
+      via: "fetch in useEffect"
+```
+
+**Option B: Derive from phase goal**
+
+1. **State the goal:** Take phase goal from ROADMAP.md
+2. **Derive truths:** "What must be TRUE for this goal?"
+   - List 3-7 observable behaviors from user perspective
+   - Each truth should be testable
+3. **Derive artifacts:** "What must EXIST?"
+   - Map truths to concrete files
+   - Be specific: `src/components/Chat.tsx`, not "chat component"
+4. **Derive key links:** "What must be CONNECTED?"
+   - Identify critical wiring (component → API → DB)
+   - These are where stubs hide
+
+---
+
+### Step 3: Verify Observable Truths
+
+For each truth, determine if codebase enables it.
+
+**Verification status:**
+- ✓ VERIFIED: All supporting artifacts pass all checks
+- ✗ FAILED: Artifacts missing, stub, or unwired
+- ? UNCERTAIN: Can't verify programmatically (needs human)
+
+For each truth:
+1. Identify supporting artifacts
+2. Check artifact status (Step 4)
+3. Check wiring status (Step 5)
+4. Determine truth status
+
+---
+
+### Step 4: Verify Artifacts (Three Levels)
+
+For each required artifact, verify three levels:
+
+#### Level 1: Existence
+```powershell
+Test-Path "src/components/Chat.tsx"
+```
+- File exists at expected path
+- **If missing:** FAILED at Level 1
+
+#### Level 2: Substantive
+```powershell
+Get-Content "src/components/Chat.tsx" | Select-String -Pattern "TODO|placeholder|stub"
+```
+- File contains real implementation
+- Not a stub, placeholder, or minimal scaffold
+- **If stub detected:** FAILED at Level 2
+
+#### Level 3: Wired
+- Imports are used, not just present
+- Exports are consumed by other files
+- Functions are called with correct arguments
+- **If unwired:** FAILED at Level 3
+
+---
+
+### Step 5: Verify Key Links (Wiring)
+
+For each key link, verify the connection exists:
+
+**Pattern: Component → API**
+```powershell
+# Check Chat.tsx calls /api/chat
+Select-String -Path "src/components/Chat.tsx" -Pattern "fetch.*api/chat"
+```
+
+**Pattern: API → Database**
+```powershell
+# Check route calls prisma
+Select-String -Path "src/app/api/chat/route.ts" -Pattern "prisma\."
+```
+
+**Pattern: Form → Handler**
+```powershell
+# Check onSubmit has implementation
+Select-String -Path "src/components/Form.tsx" -Pattern "onSubmit" -Context 0,5
+```
+
+**Pattern: State → Render**
+```powershell
+# Check state is used in JSX
+Select-String -Path "src/components/Chat.tsx" -Pattern "messages\.map"
+```
+
+---
+
+### Step 6: Check Requirements Coverage
+
+If REQUIREMENTS.md exists:
+
+```powershell
+Select-String -Path ".gsd/REQUIREMENTS.md" -Pattern "Phase {N}"
+```
+
+For each requirement:
+1. Identify which truths/artifacts support it
+2. Determine status based on supporting infrastructure
+
+**Requirement status:**
+- ✓ SATISFIED: All supporting truths verified
+- ✗ BLOCKED: Supporting truths failed
+- ? NEEDS HUMAN: Can't verify programmatically
+
+---
+
+### Step 7: Scan for Anti-Patterns
+
+Run anti-pattern detection on modified files:
+
+```powershell
+# TODO/FIXME comments
+Select-String -Path "src/**/*.ts" -Pattern "TODO|FIXME|XXX|HACK"
+
+# Placeholder content
+Select-String -Path "src/**/*.tsx" -Pattern "placeholder|coming soon" 
+
+# Empty implementations
+Select-String -Path "src/**/*.ts" -Pattern "return null|return \{\}|return \[\]"
+
+# Console.log only
+Select-String -Path "src/**/*.ts" -Pattern "console\.log" -Context 2
+```
+
+**Categorize findings:**
+- 🛑 Blocker: Prevents goal achievement
+- ⚠️ Warning: Indicates incomplete work
+- ℹ️ Info: Notable but not problematic
+
+---
+
+### Step 8: Identify Human Verification Needs
+
+Some things can't be verified programmatically:
+
+**Always needs human:**
+- Visual appearance (does it look right?)
+- User flow completion
+- Real-time behavior (WebSocket, SSE)
+- External service integration
+- Performance feel
+- Error message clarity
+
+**Format:**
+```markdown
+### 1. {Test Name}
+**Test:** {What to do}
+**Expected:** {What should happen}
+**Why human:** {Why can't verify programmatically}
+```
+
+---
+
+### Step 9: Determine Overall Status
+
+**Status: passed**
+- All truths VERIFIED
+- All artifacts pass levels 1-3
+- All key links WIRED
+- No blocker anti-patterns
+
+**Status: gaps_found**
+- One or more truths FAILED
+- OR artifacts MISSING/STUB
+- OR key links NOT_WIRED
+- OR blocker anti-patterns found
+
+**Status: human_needed**
+- All automated checks pass
+- BUT items flagged for human verification
+
+**Calculate score:**
+```
+score = verified_truths / total_truths
+```
+
+---
+
+### Step 10: Structure Gap Output
+
+When gaps found, structure for `/plan --gaps`:
+
+```yaml
+---
+phase: {N}
+verified: {timestamp}
+status: gaps_found
+score: {N}/{M} must-haves verified
+gaps:
+  - truth: "User can see existing messages"
+    status: failed
+    reason: "Chat.tsx doesn't fetch from API"
+    artifacts:
+      - path: "src/components/Chat.tsx"
+        issue: "No useEffect with fetch call"
+    missing:
+      - "API call in useEffect to /api/chat"
+      - "State for storing fetched messages"
+      - "Render messages array in JSX"
+---
+```
+
+---
+
+## Stub Detection Patterns
+
+### Universal Stub Patterns
+```powershell
+# Comment-based stubs
+Select-String -Pattern "TODO|FIXME|XXX|HACK|PLACEHOLDER"
+
+# Placeholder text
+Select-String -Pattern "placeholder|lorem ipsum|coming soon" 
+
+# Empty implementations
+Select-String -Pattern "return null|return undefined|return \{\}|return \[\]"
+```
+
+### React Component Stubs
+```javascript
+// RED FLAGS:
+return <div>Component</div>
+return <div>Placeholder</div>
+return <div>{/* TODO */}</div>
+return null
+return <></>
+
+// Empty handlers:
+onClick={() => {}}
+onChange={() => console.log('clicked')}
+onSubmit={(e) => e.preventDefault()}  // Only prevents default
+```
+
+### API Route Stubs
+```typescript
+// RED FLAGS:
+export async function POST() {
+  return Response.json({ message: "Not implemented" });
+}
+
+export async function GET() {
+  return Response.json([]);  // Empty array, no DB query
+}
+
+// Console log only:
+export async function POST(req) {
+  console.log(await req.json());
+  return Response.json({ ok: true });
+}
+```
+
+### Wiring Red Flags
+```typescript
+// Fetch exists but response ignored:
+fetch('/api/messages')  // No await, no .then
+
+// Query exists but result not returned:
+await prisma.message.findMany()
+return Response.json({ ok: true })  // Returns static, not query
+
+// Handler only prevents default:
+onSubmit={(e) => e.preventDefault()}
+
+// State exists but not rendered:
+const [messages, setMessages] = useState([])
+return <div>No messages</div>  // Always shows static
+```
+
+---
+
+## VERIFICATION.md Format
+
+```markdown
+---
+phase: {N}
+verified: {timestamp}
+status: {passed | gaps_found | human_needed}
+score: {N}/{M} must-haves verified
+is_re_verification: {true | false}
+gaps: [...]  # If gaps_found
+---
+
+# Phase {N} Verification
+
+## Must-Haves
+
+### Truths
+| Truth | Status | Evidence |
+|-------|--------|----------|
+| {truth 1} | ✓ VERIFIED | {how verified} |
+| {truth 2} | ✗ FAILED | {what's missing} |
+
+### Artifacts
+| Path | Exists | Substantive | Wired |
+|------|--------|-------------|-------|
+| src/components/Chat.tsx | ✓ | ✓ | ✗ |
+
+### Key Links
+| From | To | Via | Status |
+|------|-----|-----|--------|
+| Chat.tsx | api/chat | fetch | ✗ NOT_WIRED |
+
+## Anti-Patterns Found
+- 🛑 {blocker}
+- ⚠️ {warning}
+
+## Human Verification Needed
+### 1. Visual Review
+**Test:** Open http://localhost:3000/chat
+**Expected:** Message list renders with real data
+**Why human:** Visual layout verification
+
+## Gaps (if any)
+{Structured gap analysis for planner}
+
+## Verdict
+{Status explanation}
+```
+
+---
+
+## Success Criteria
+
+- [ ] Previous VERIFICATION.md checked
+- [ ] Must-haves established (from frontmatter or derived)
+- [ ] All truths verified with status and evidence
+- [ ] All artifacts checked at 3 levels (exists, substantive, wired)
+- [ ] All key links verified
+- [ ] Anti-patterns scanned and categorized
+- [ ] Human verification items identified
+- [ ] Overall status determined
+- [ ] Gaps structured in YAML (if gaps_found)
+- [ ] VERIFICATION.md created
+- [ ] Results returned to orchestrator

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

@@ -0,0 +1,96 @@
+---
+description: Add a new phase to the end of the roadmap
+argument-hint: "<phase-name>"
+---
+
+# /add-phase Workflow
+
+<objective>
+Add a new phase to the end of the current roadmap.
+</objective>
+
+<process>
+
+## 1. Validate Roadmap Exists
+
+```powershell
+if (-not (Test-Path ".gsd/ROADMAP.md")) {
+    Write-Error "ROADMAP.md required. Run /new-milestone first."
+}
+```
+
+---
+
+## 2. Determine Next Phase Number
+
+```powershell
+# Count existing phases
+$phases = Select-String -Path ".gsd/ROADMAP.md" -Pattern "### Phase \d+"
+$nextPhase = $phases.Count + 1
+```
+
+---
+
+## 3. Gather Phase Information
+
+Ask for:
+- **Name** — Phase title
+- **Objective** — What this phase achieves
+- **Depends on** — Previous phases (usually N-1)
+
+---
+
+## 4. Add to ROADMAP.md
+
+Append:
+```markdown
+---
+
+### Phase {N}: {name}
+**Status**: ⬜ Not Started
+**Objective**: {objective}
+**Depends on**: Phase {N-1}
+
+**Tasks**:
+- [ ] TBD (run /plan {N} to create)
+
+**Verification**:
+- TBD
+```
+
+---
+
+## 5. Update STATE.md
+
+Note phase added.
+
+---
+
+## 6. Commit
+
+```powershell
+git add .gsd/ROADMAP.md .gsd/STATE.md
+git commit -m "docs: add phase {N} - {name}"
+```
+
+---
+
+## 7. Offer Next Steps
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE ADDED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {N}: {name}
+
+───────────────────────────────────────────────────────
+
+▶ NEXT
+
+/plan {N} — Create execution plans for this phase
+
+───────────────────────────────────────────────────────
+```
+
+</process>

package/.agent/workflows/add-todo.md

@@ -0,0 +1,69 @@
+---
+description: Capture a todo item for later
+argument-hint: "<description> [--priority high|medium|low]"
+---
+
+# /add-todo Workflow
+
+<objective>
+Quickly capture an idea, task, or issue without interrupting current work flow.
+</objective>
+
+<context>
+**Item:** $ARGUMENTS (the todo description)
+
+**Flags:**
+- `--priority high|medium|low` — Set priority (default: medium)
+
+**Output:**
+- `.gsd/TODO.md` — Accumulated todo items
+</context>
+
+<process>
+
+## 1. Parse Arguments
+
+Extract:
+- Todo description
+- Priority (default: medium)
+
+---
+
+## 2. Ensure TODO.md Exists
+
+```powershell
+if (-not (Test-Path ".gsd/TODO.md")) {
+    # Create with header
+}
+```
+
+---
+
+## 3. Add Todo Item
+
+Append to `.gsd/TODO.md`:
+
+```markdown
+- [ ] {description} `{priority}` — {date}
+```
+
+---
+
+## 4. Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► TODO ADDED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{description}
+Priority: {priority}
+
+───────────────────────────────────────────────────────
+
+/check-todos — see all pending items
+
+───────────────────────────────────────────────────────
+```
+
+</process>

package/.agent/workflows/audit-milestone.md

@@ -0,0 +1,107 @@
+---
+description: Audit a milestone for quality and completeness
+argument-hint: "[milestone-name]"
+---
+
+# /audit-milestone Workflow
+
+<objective>
+Review a completed (or in-progress) milestone for quality, completeness, and lessons learned.
+</objective>
+
+<process>
+
+## 1. Load Milestone Context
+
+If milestone name provided, load from archive:
+```powershell
+Get-Content ".gsd/milestones/{name}-SUMMARY.md"
+```
+
+If no name, audit current milestone from ROADMAP.md.
+
+---
+
+## 2. Check Must-Haves Verification
+
+For each must-have in the milestone:
+- Was it verified with empirical evidence?
+- Is the evidence still valid?
+- Any regressions since completion?
+
+---
+
+## 3. Review Technical Debt
+
+Check TODO.md and DECISIONS.md for:
+- Deferred items during this milestone
+- Technical debt acknowledged
+- Items that should be addressed
+
+---
+
+## 4. Analyze Phase Quality
+
+For each phase:
+- Review VERIFICATION.md
+- Check for gap closures (were there many?)
+- Note recurring issues
+
+---
+
+## 5. Generate Audit Report
+
+```markdown
+# Milestone Audit: {name}
+
+**Audited:** {date}
+
+## Summary
+| Metric | Value |
+|--------|-------|
+| Phases | {N} |
+| Gap closures | {M} |
+| Technical debt items | {K} |
+
+## Must-Haves Status
+| Requirement | Verified | Evidence |
+|-------------|----------|----------|
+| {req 1} | ✅ | {link} |
+| {req 2} | ✅ | {link} |
+
+## Concerns
+- {concern 1}
+- {concern 2}
+
+## Recommendations
+1. {recommendation 1}
+2. {recommendation 2}
+
+## Technical Debt to Address
+- [ ] {item 1}
+- [ ] {item 2}
+```
+
+---
+
+## 6. Offer Actions
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AUDIT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone: {name}
+Health: {GOOD | CONCERNS | NEEDS ATTENTION}
+
+───────────────────────────────────────────────────────
+
+▶ ACTIONS
+
+/plan-milestone-gaps — Create plans to address gaps
+/add-todo — Capture debt items for later
+
+───────────────────────────────────────────────────────
+```
+
+</process>