gsd-ag 1.0.0

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

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

package/.gsd/templates/architecture.md

@@ -0,0 +1,67 @@
+# Architecture
+
+> Auto-generated by /map on <!-- date -->
+
+## 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: <!-- date -->*

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

package/.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
+
+<!-- Add new decisions below -->
+
+---
+
+*Last updated: <!-- date -->*

package/.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]
+---
+
+<discovery_objective>
+Discover [topic] to inform [phase name] implementation.
+
+Purpose: [What decision/implementation this enables]
+Scope: [Boundaries]
+Output: DISCOVERY.md with recommendation
+</discovery_objective>
+
+<discovery_scope>
+<include>
+- [Question to answer]
+- [Area to investigate]
+- [Specific comparison if needed]
+</include>
+
+<exclude>
+- [Out of scope for this discovery]
+- [Defer to implementation phase]
+</exclude>
+</discovery_scope>
+
+<discovery_protocol>
+
+**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
+
+</discovery_protocol>
+```
+
+---
+
+## 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
+
+<confidence level="high|medium|low">
+[Why this confidence level]
+</confidence>
+
+<sources>
+- [Primary sources used]
+</sources>
+
+<open_questions>
+[What needs validation during implementation]
+</open_questions>
+```
+
+---
+
+## 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

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

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