gsdd-cli 0.1.0

package/distilled/templates/research/features.md

@@ -0,0 +1,23 @@
+# FEATURES.md — Feature Landscape
+
+## Table Stakes
+Features users expect. Without them, your product feels broken.
+
+- [ ] [feature] — [why it's expected]
+- [ ] [feature] — [why it's expected]
+
+## Differentiators
+Features that set you apart from competitors.
+
+- [ ] [feature] — [what makes this unique]
+- [ ] [feature] — [competitive advantage]
+
+## Anti-Features
+Things to deliberately NOT build. Complexity traps.
+
+- [ ] [feature to avoid] — [why: complexity trap / scope creep / premature optimization]
+- [ ] [feature to avoid] — [why]
+
+## Sources
+- [Competitor 1] — [what they do well / poorly]
+- [Competitor 2] — [what they do well / poorly]

package/distilled/templates/research/pitfalls.md

@@ -0,0 +1,46 @@
+# Pitfalls Research Template
+
+Use when researching common mistakes and gotchas for a domain or technology.
+
+Write to: `.planning/research/PITFALLS.md`
+
+---
+
+```markdown
+# Pitfalls
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Pitfall 1: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+## Pitfall 2: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+## Pitfall 3: [Name]
+
+**What goes wrong**: [description]
+**Why it happens**: [root cause]
+**How to avoid**: [prevention strategy]
+**Warning signs**: [how to detect early]
+
+---
+*These pitfalls should inform verification criteria in the roadmap.*
+```
+
+## Guidelines
+
+- **Be specific to the domain** — not generic advice like "write tests"
+- **Warning signs** are crucial — they let you catch problems early
+- **Prevention strategies** should be actionable, not vague
+- 3-5 pitfalls is the sweet spot — more than 5 and none get remembered
+- **Link to phases**: note which roadmap phase should address each pitfall

package/distilled/templates/research/stack.md

@@ -0,0 +1,45 @@
+# Stack Research Template
+
+Use when researching the technology stack for a project or phase.
+
+Write to: `.planning/research/STACK.md`
+
+---
+
+```markdown
+# Stack Research
+
+**Domain**: [what we're building]
+**Researched**: [date]
+
+## Recommended Stack
+
+| Library/Tool | Version | Purpose | Why This One |
+|-------------|---------|---------|--------------|
+| [name] | [ver] | [what it does] | [why it's the right choice] |
+| [name] | [ver] | [what it does] | [why it's the right choice] |
+
+## Alternatives Considered
+
+| Recommended | Alternative | Why Not |
+|-------------|------------|---------|
+| [choice] | [option] | [tradeoff] |
+
+## Don't Hand-Roll
+
+Problems that look simple but have battle-tested solutions:
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|------------|-------------|-----|
+| [problem] | [custom solution] | [library] | [edge cases you'd miss] |
+
+---
+*Confidence: [HIGH/MEDIUM/LOW]*
+```
+
+## Guidelines
+
+- **Specific versions** — not "latest", give actual numbers
+- **"Why This One"** matters more than "What It Does"
+- **Don't Hand-Roll** is the highest-value section — prevents wasted effort on solved problems
+- Keep to ~30-40 lines when filled out

package/distilled/templates/research/summary.md

@@ -0,0 +1,67 @@
+# Research Summary
+
+**Date:** [YYYY-MM-DD]
+**Topic:** [Domain/feature area]
+**Milestone context:** [greenfield | subsequent]
+
+## Executive Summary (5-10 bullets)
+- [What we learned, in actionable terms — one concrete insight per bullet]
+
+## Confidence Assessment
+
+| Area | Confidence | Rationale |
+|------|-----------|-----------|
+| Stack choices | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Feature set | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Architecture pattern | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+| Key pitfalls | ✅ verified / ⚠️ likely / ❓ uncertain | [why] |
+
+## Recommendations (Prescriptive)
+
+For each recommendation, include confidence and the evidence.
+
+1. Recommendation: [Use X / Avoid Y]
+   - Confidence: [verified | likely | uncertain]
+   - Why: [short rationale]
+   - Evidence: [URL(s)]
+   - Counterpoints / tradeoffs: [what would change the decision]
+
+## Non-Goals / Anti-Features
+- [What we explicitly will not do in v1, and why — grounded in research findings]
+
+## Pitfalls To Avoid
+- [Concrete mistakes teams make in this domain — phase-mapped where possible]
+
+## Open Questions (Blockers)
+- [What must be decided before planning can proceed]
+
+## Implications for Roadmap
+
+This section is the critical handoff from research to ROADMAP.md. The roadmapper reads this.
+
+### Suggested Phase Structure
+Derived from architecture build order + pitfall avoidance priorities:
+
+| Phase | Focus | Rationale |
+|-------|-------|-----------|
+| Phase 1 | [Foundation: e.g., data model + auth] | [why this must come first — dependency or risk] |
+| Phase 2 | [Core: e.g., primary user workflow] | [what unblocks after Phase 1] |
+| Phase 3 | [Integration: e.g., external services] | [why deferred — complexity or dependency] |
+| Phase N | [Polish / edge cases] | [why last] |
+
+### Research Flags (Phase-Level)
+These are signals for the planner — which phases need deeper domain research vs standard patterns:
+
+| Phase | Flag | Reason |
+|-------|------|--------|
+| Phase 1 | ⚠️ Needs deeper research | [e.g., "auth pattern depends on regulatory context"] |
+| Phase 2 | ✅ Standard pattern | [e.g., "CRUD with established library — no surprises"] |
+| Phase N | ❓ Uncertain | [e.g., "real-time sync has multiple viable approaches"] |
+
+## Sources
+
+| Claim | URL | Accessed |
+|-------|-----|---------|
+| [Stack recommendation] | [URL] | [YYYY-MM-DD] |
+| [Architecture pattern] | [URL] | [YYYY-MM-DD] |
+| [Pitfall] | [URL] | [YYYY-MM-DD] |

package/distilled/templates/roadmap.md

@@ -0,0 +1,62 @@
+# ROADMAP.md Template
+
+Use this template when creating `.planning/ROADMAP.md` (phase breakdown + progress tracker).
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph: what v1 delivers and why.]
+
+## Phases (Status Legend: [ ] not started, [-] in progress, [x] complete)
+
+- [ ] **Phase 1: [Name]** - [One-line goal]
+- [ ] **Phase 2: [Name]** - [One-line goal]
+- [ ] **Phase 3: [Name]** - [One-line goal]
+
+## Phase Details
+
+### Phase 1: [Name]
+
+**Goal**: [What this phase delivers]
+**Status**: [ ] / [-] / [x]
+**Requirements**: [REQ-IDs from `.planning/SPEC.md`]
+**Success Criteria** (must be TRUE when done):
+1. [Observable behavior]
+2. [Observable behavior]
+
+### Phase 2: [Name]
+
+**Goal**: [What this phase delivers]
+**Status**: [ ] / [-] / [x]
+**Depends on**: Phase 1
+**Requirements**: [REQ-IDs]
+**Success Criteria**:
+1. [Observable behavior]
+2. [Observable behavior]
+
+---
+*Created: [YYYY-MM-DD]*
+```
+
+## Guidelines
+
+- Prefer 3-8 phases for most projects.
+- Every v1 requirement in `.planning/SPEC.md` must map to exactly one phase (no orphans).
+- Success criteria are 2-5 observable behaviors per phase.
+- No time estimates: focus on verifiable outcomes.
+- These status markers are the portable source of truth. Workflow files and summaries should use `[ ]`, `[-]`, and `[x]` consistently.
+
+## Coverage Verification
+
+After creating the roadmap, verify:
+```
+For each v1 requirement in .planning/SPEC.md:
+  [ ] Requirement appears in exactly one phase's "Requirements" list
+  [ ] The phase's success criteria would prove the requirement is met
+```
+
+If a requirement doesn't map to any phase: add a phase or expand an existing one.
+If a requirement maps to multiple phases: clarify which phase owns it.
+

package/distilled/templates/spec.md

@@ -0,0 +1,110 @@
+# SPEC.md Template
+
+Use this template when creating `.planning/SPEC.md` - the project's single source of truth.
+
+> **Agentic PRD Constraint:** Do not write narrative prose or fluff. Use strict checklists, dense tables, and typed schemas. There is no artificial line limit, but every single line must be highly deterministic and actionable for a downstream Subagent.
+
+---
+
+```markdown
+# [Project Name]
+
+## What We're Building
+
+[2-3 sentences. What does this product/feature do and who is it for? Use the developer's own language.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.]
+
+## Core Principles
+
+[SOTA: 3-5 governing rules for the project (e.g., Code Quality, UI Consistency, Testing)]
+
+## Typed Data Schemas
+
+```typescript
+// SOTA: Define the core shared data models here early to prevent agent hallucination during handoffs
+// type User = { id: string; role: 'admin' | 'user' };
+```
+
+## Capability & Security Gates
+
+// SOTA [OpenFang]: Define what autonomous agents are explicitly NOT allowed to do without human `/approve`.
+- **Destructive DB actions:** Require human review
+- **External Purchases:** Mandatory approval gate
+
+## Requirements
+
+### Must Have (v1)
+
+- [ ] **[CAT-01]**: [User-centric, testable requirement] [Done-When: observable verification criteria]
+- [ ] **[CAT-02]**: [User-centric, testable requirement] [Done-When: observable verification criteria]
+- [ ] **[CAT-03]**: [User-centric, testable requirement] [Done-When: observable verification criteria]
+
+### Nice to Have (v2)
+
+- **[CAT-04]**: [Deferred requirement]
+- **[CAT-05]**: [Deferred requirement]
+
+### Out of Scope
+
+- [Feature] - [why excluded]
+- [Feature] - [why excluded]
+
+## Constraints
+
+- **[Type]**: [What] - [Why]
+- **[Type]**: [What] - [Why]
+
+## Key Decisions
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| [Choice] | [Why] | [When] |
+
+## Current State
+
+- **Active Phase:** Phase [X] - [Name] ([ ]/[-]/[x])
+- **Last Completed:** [What was last done]
+- **In Progress:** [What is currently being worked on]
+- **Decisions:** [Any recent decisions]
+- **Blockers:** [None / description]
+
+---
+*Last updated: [date] after [trigger]*
+```
+
+---
+
+## Guidelines
+
+- **Requirements** must be specific, testable, and user-centric ("User can X", not "System does Y")
+- **Requirement IDs** use `[CATEGORY]-[NUMBER]` format (AUTH-01, DATA-02, UI-03)
+- **v1 requirements** have checkboxes - check them off when verified as complete
+- **Every v1 requirement** must include a `[Done-When: ...]` clause with observable verification criteria
+- **Out of Scope** always includes reasoning (prevents scope creep discussions later)
+- **Key Decisions** are appended throughout the project as they're made
+- **Current State** is updated after each significant milestone - this is how agents resume work across sessions
+- **No Narrative Fluff** - this is an executable Agentic PRD, not a novel. Details live in plans, but core Typed Schemas MUST reside here.
+
+## When Codebase Already Exists (Brownfield)
+
+If auditing an existing codebase during `init`:
+- Add a **Validated** section under Requirements:
+  ```markdown
+  ### Validated (existing capabilities)
+  - [x] **[CAT-01]**: User can log in - existing auth system
+  - [x] **[CAT-02]**: Data persists across sessions - PostgreSQL database
+  ```
+- New requirements go under "Must Have (v1)"
+- Document existing tech stack and patterns in Constraints
+- Document any tech debt discovered in a separate concern note (not in SPEC.md)
+
+## Archive Guidance
+
+When a major milestone completes:
+1. The SPEC.md "Current State" section reflects the new state
+2. Completed phases have summaries in `.planning/phases/{N}-SUMMARY.md`
+3. SPEC.md itself stays lean - don't accumulate history here
+

package/distilled/workflows/audit-milestone.md

@@ -0,0 +1,220 @@
+<role>
+You are the MILESTONE AUDITOR. Your job is to verify that a completed milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage.
+
+Core mindset: individual phases can pass while the milestone fails. Integration and requirements coverage are what matter at this level.
+</role>
+
+<load_context>
+Before starting, read these files:
+1. `.planning/ROADMAP.md` - milestone phases, definitions of done, requirement assignments
+2. `.planning/SPEC.md` - requirement IDs, descriptions, and checkbox status
+3. All phase VERIFICATION.md files (from `.planning/phases/`)
+4. All phase SUMMARY.md files (from `.planning/phases/`)
+5. `.planning/AUTH_MATRIX.md` (if it exists) — authorization matrix for matrix-driven auth verification
+</load_context>
+
+<process>
+
+## 1. Determine Milestone Scope
+
+Parse `.planning/ROADMAP.md` for:
+- All phases in the current milestone (sorted numerically)
+- Milestone definition of done
+- Phase-to-requirement mappings (the Requirements field in each phase detail)
+
+Parse `.planning/SPEC.md` for:
+- All requirement IDs with descriptions
+- Current checkbox status (`[x]` vs `[ ]`)
+
+## 2. Read All Phase Verifications
+
+For each phase directory in `.planning/phases/`, read the VERIFICATION.md.
+
+From each VERIFICATION.md, extract:
+- **Status:** passed | gaps_found | human_needed
+- **Critical gaps:** (if any - these are blockers)
+- **Non-critical gaps:** tech debt, deferred items, warnings
+- **Anti-patterns found:** TODOs, stubs, placeholders
+- **Requirements coverage:** which requirements satisfied/blocked
+
+If a phase has no VERIFICATION.md, flag it as an unverified phase - this is a blocker.
+
+## 3. Spawn Integration Checker
+
+With phase context collected, delegate cross-phase integration checking:
+
+<delegate>
+**Identity:** Integration Checker
+**Instruction:** Read `.planning/templates/roles/integration-checker.md`, then check cross-phase integration.
+
+**Context to provide:**
+- Phase directories in milestone scope
+- Key exports from each phase (extracted from SUMMARYs)
+- API routes and endpoints created
+- Milestone requirement IDs with descriptions and assigned phases
+- `.planning/AUTH_MATRIX.md` path (if it exists)
+
+**Task:** Verify cross-phase wiring, API coverage, auth protection, and E2E user flows. Return structured integration report with wiring summary, API coverage, auth protection, E2E flow status, and Requirements Integration Map.
+
+**Return:** Structured integration report (wiring, APIs, auth protection, flows, requirements map).
+</delegate>
+
+If the runtime supports spawning a subagent: spawn the integration checker as a separate read-only context for independent verification.
+
+If the runtime does not support subagent spawn: run the integration check inline within this workflow. Note `reduced_assurance: true` in the audit report - the integration check ran in the same context as the auditor rather than in fresh independent context.
+
+Either way, the integration check happens. The quality level is documented.
+
+## 4. Collect Results
+
+Combine:
+- Phase-level gaps and tech debt (from step 2)
+- Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
+
+## 5. 3-Source Cross-Reference
+
+Cross-reference three independent sources for each requirement to determine satisfaction status.
+
+### 5a. Parse SPEC.md Requirements
+
+Extract all requirement IDs from `.planning/SPEC.md`:
+- Requirement ID, description, checkbox status (`[x]` vs `[ ]`)
+
+### 5b. Parse ROADMAP.md Phase-to-Requirement Mapping
+
+For each phase in `.planning/ROADMAP.md`, extract the Requirements field:
+- Which requirements are assigned to which phase
+
+### 5c. Parse Phase VERIFICATION.md Requirements Tables
+
+For each phase's VERIFICATION.md, extract the requirements coverage section:
+- Which requirements were verified, with what status and evidence
+
+### 5d. Extract SUMMARY.md Frontmatter
+
+For each phase's SUMMARY.md, extract `requirements-completed` from frontmatter when present:
+- Which requirements the executor claims were completed
+- Treat this as corroborating evidence, not as a hard prerequisite for a satisfied requirement
+
+### 5e. Status Determination Matrix
+
+For each requirement, determine status using all available sources:
+
+| VERIFICATION Status | SUMMARY Frontmatter | SPEC.md Checkbox | Final Status |
+|---------------------|---------------------|------------------|--------------|
+| passed              | listed              | `[x]`            | **satisfied** |
+| passed              | listed              | `[ ]`            | **satisfied** (update spec) |
+| passed              | missing             | any              | **satisfied** (lower confidence; note missing SUMMARY corroboration) |
+| gaps_found          | any                 | any              | **unsatisfied** |
+| missing             | listed              | any              | **partial** (verification gap) |
+| missing             | missing             | any              | **unsatisfied** |
+
+### 5f. FAIL Gate and Orphan Detection
+
+**FAIL gate:** Any `unsatisfied` requirement forces `gaps_found` status on the milestone audit. No exceptions.
+
+**Orphan detection:** Requirements in `.planning/SPEC.md` that are mapped to phases in `.planning/ROADMAP.md` but absent from ALL phase VERIFICATION.md files are orphaned. Orphaned requirements are treated as `unsatisfied` - they were assigned but never verified by any phase.
+
+## 6. Write Milestone Audit Report
+
+Create `.planning/v{version}-MILESTONE-AUDIT.md` with structured frontmatter:
+
+```yaml
+---
+milestone: v{version}
+audited: {ISO-8601 timestamp}
+status: passed | gaps_found | tech_debt
+reduced_assurance: false
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  auth: N/M
+  flows: N/M
+gaps:
+  requirements:
+    - id: "REQ-ID"
+      status: "unsatisfied | partial | orphaned"
+      phase: "assigned phase"
+      claimed_by_plans: ["plan files that reference this requirement"]
+      completed_by_plans: ["plan files whose SUMMARY marks it complete"]
+      verification_status: "passed | gaps_found | missing | orphaned"
+      evidence: "specific evidence or lack thereof"
+  integration: [...]
+  auth:
+    - surface: "admin metrics page"
+      status: "unprotected"
+      evidence: "Sensitive data renders without auth or role gate"
+  flows: [...]
+tech_debt:
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+---
+```
+
+Plus full markdown report body with tables for requirements, phases, integration findings, auth findings, and tech debt.
+
+**Status values:**
+- `passed` - all requirements met, no critical gaps, integration and auth protection verified
+- `gaps_found` - critical blockers exist (unsatisfied requirements, unprotected sensitive flows, broken flows, or missing verifications)
+- `tech_debt` - no blockers but accumulated deferred items need review
+
+## 7. Present Results
+
+Route by audit status:
+
+### If passed:
+- Report: all requirements covered, cross-phase integration verified, auth protection verified, E2E flows complete
+- Next step: complete the milestone (archive and tag)
+
+### If gaps_found:
+- Report: list unsatisfied requirements, auth or cross-phase issues, broken flows
+- Next step: plan gap closure phases to complete the milestone
+
+### If tech_debt:
+- Report: all requirements met, list accumulated tech debt by phase
+- Next step: either complete the milestone (accept debt) or plan a cleanup phase
+
+</process>
+
+<success_criteria>
+Audit is complete when all of these are true:
+
+- [ ] Milestone scope identified from ROADMAP.md
+- [ ] All phase VERIFICATION.md files read (missing ones flagged as blockers)
+- [ ] SUMMARY.md `requirements-completed` frontmatter extracted when present
+- [ ] SPEC.md requirement checkboxes parsed
+- [ ] ROADMAP.md phase-to-requirement mappings extracted
+- [ ] Integration checker ran (subagent or inline with reduced_assurance noted)
+- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + SPEC.md)
+- [ ] Orphaned requirements detected (mapped in ROADMAP but absent from all VERIFICATIONs)
+- [ ] Auth-protection findings aggregated for sensitive milestone surfaces
+- [ ] FAIL gate enforced - any unsatisfied requirement forces gaps_found status
+- [ ] Tech debt and deferred gaps aggregated by phase
+- [ ] MILESTONE-AUDIT.md created with structured requirement gap objects
+- [ ] Results presented with actionable next steps based on status
+</success_criteria>
+
+<completion>
+Report the audit result to the user, then present the next step:
+
+---
+**Completed:** Milestone audit — created `.planning/v{version}-MILESTONE-AUDIT.md`.
+
+If status is `passed`:
+**Next step:** `/gsdd:complete-milestone` — archive the milestone and prepare for the next
+
+If status is `gaps_found`:
+**Next step:** `/gsdd:plan` — plan gap-closure phases for the unsatisfied requirements
+
+If status is `tech_debt`:
+**Next step:** Either `/gsdd:complete-milestone` (accept debt) or `/gsdd:plan` (cleanup phase)
+
+Also available:
+- `/gsdd:verify` — re-verify a specific phase before re-auditing
+- `/gsdd:progress` — check overall project status
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>