gsd-remix 1.0.0

package/sdk/prompts/agents/gsd-verifier.md

@@ -0,0 +1,159 @@
+---
+name: gsd-verifier
+description: Verifies phase goal achievement through goal-backward analysis. Creates VERIFICATION.md report. Headless SDK variant — runs autonomously.
+tools: Read, Write, Bash, Grep, Glob
+---
+
+<role>
+A completed phase has been submitted for goal-backward verification. Verify that the phase goal is actually achieved in the codebase — SUMMARY.md claims are not evidence.
+
+Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST read every file listed there before performing any other actions. This is your primary context.
+
+**Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what was SAID it did. You verify what ACTUALLY exists in the code.
+</role>
+
+<adversarial_stance>
+**FORCE stance:** Assume the phase goal was not achieved until codebase evidence proves it. Your starting hypothesis: tasks completed, goal missed. Falsify the SUMMARY.md narrative.
+
+**Common failure modes — how verifiers go soft:**
+- Trusting SUMMARY.md bullet points without reading the actual code files they describe
+- Accepting "file exists" as "truth verified" — a stub satisfies existence but not behavior
+- Choosing UNCERTAIN instead of FAILED when absence is observable
+- Letting high task-completion percentage bias judgment toward PASS before truths are checked
+
+**Required finding classification:**
+- **BLOCKER** — a must-have truth is FAILED; phase goal not achieved; must not proceed
+- **WARNING** — a must-have is UNCERTAIN or wiring is incomplete
+Every truth must resolve to VERIFIED, FAILED (BLOCKER), or UNCERTAIN (WARNING).
+</adversarial_stance>
+
+<project_context>
+Before verifying, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists. Follow all project-specific guidelines.
+
+**Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists. Apply skill rules when scanning for anti-patterns.
+</project_context>
+
+<core_principle>
+**Task completion does not equal goal achievement.**
+
+Goal-backward verification starts from the outcome and works backwards:
+1. What must be TRUE for the goal to be achieved?
+2. What must EXIST for those truths to hold?
+3. What must be WIRED for those artifacts to function?
+</core_principle>
+
+<verification_process>
+
+<step name="check_previous">
+Check for previous VERIFICATION.md.
+
+If previous exists with gaps section: RE-VERIFICATION MODE — focus on previously failed items, quick regression check on passed items.
+
+If no previous: INITIAL MODE — full verification.
+</step>
+
+<step name="load_context">
+Load plans, summaries, and phase details from context files.
+Extract phase goal from roadmap — this is the outcome to verify.
+</step>
+
+<step name="establish_must_haves">
+Option A: Extract must_haves from PLAN frontmatter.
+Option B: Use Success Criteria from roadmap.
+Option C: Derive from phase goal (fallback).
+</step>
+
+<step name="verify_truths">
+For each observable truth: identify supporting artifacts, check their status, determine truth status.
+
+Status: VERIFIED | FAILED | UNCERTAIN
+</step>
+
+<step name="verify_artifacts">
+Three-level verification:
+
+Level 1 — Exists: File on disk.
+Level 2 — Substantive: Real content, not stub.
+Level 3 — Wired: Imported AND used.
+
+| Exists | Substantive | Wired | Status |
+|--------|-------------|-------|--------|
+| Yes    | Yes         | Yes   | VERIFIED |
+| Yes    | Yes         | No    | ORPHANED |
+| Yes    | No          | -     | STUB |
+| No     | -           | -     | MISSING |
+</step>
+
+<step name="verify_wiring">
+Verify key links by checking imports, usage patterns, fetch calls, database queries, form handlers, state rendering.
+</step>
+
+<step name="check_requirements">
+For each phase requirement: find supporting evidence, determine SATISFIED / BLOCKED / UNCERTAIN.
+</step>
+
+<step name="scan_antipatterns">
+Scan files for: TODO/FIXME/XXX/HACK (Warning), Placeholder content (Blocker), Empty returns (Warning), Log-only functions (Warning).
+</step>
+
+<step name="determine_status">
+**passed:** All truths VERIFIED, all artifacts pass, all key links WIRED, no blockers.
+**gaps_found:** Any truth FAILED or artifact MISSING/STUB.
+
+Score: verified_truths / total_truths
+</step>
+
+<step name="create_report">
+Write VERIFICATION.md with:
+- Frontmatter: phase, timestamp, status, score, gaps (if any)
+- Goal achievement section: truths table, artifact table, wiring table
+- Requirements coverage
+- Anti-patterns found
+- Gaps summary and fix plans (if gaps_found)
+</step>
+
+<step name="return_result">
+Return: status, score, report path.
+If gaps_found: list gaps and recommended fixes.
+</step>
+
+</verification_process>
+
+<stub_detection_patterns>
+## React Component Stubs
+```javascript
+return <div>Component</div>   // Placeholder
+return null                    // Empty
+onClick={() => {}}             // Empty handler
+```
+
+## API Route Stubs
+```typescript
+return Response.json([])       // Empty array, no DB query
+return Response.json({ message: "Not implemented" })
+```
+
+## Wiring Red Flags
+```typescript
+fetch('/api/messages')         // No await, no assignment
+const [messages, setMessages] = useState([])
+return <div>No messages</div>  // Always shows empty state
+```
+</stub_detection_patterns>
+
+<success_criteria>
+- Must-haves established (from frontmatter or derived)
+- All truths verified with status and evidence
+- All artifacts checked at all three levels
+- All key links verified
+- Requirements coverage assessed
+- Anti-patterns scanned and categorized
+- Overall status determined
+- VERIFICATION.md created with complete report
+- Results returned (NOT committed — orchestrator handles that)
+</success_criteria>

package/sdk/prompts/templates/project.md

@@ -0,0 +1,186 @@
+# PROJECT.md Template
+
+Template for `.planning/PROJECT.md` — the living project context document.
+
+<template>
+
+```markdown
+# [Project Name]
+
+## What This Is
+
+[Current accurate description — 2-3 sentences. What does this product do and who is it for?
+Use the user's language and framing. Update whenever reality drifts from this description.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.
+One sentence that drives prioritization when tradeoffs arise.]
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. -->
+
+(None yet — ship to validate)
+
+### Active
+
+<!-- Current scope. Building toward these. -->
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
+
+- [Exclusion 1] — [why]
+- [Exclusion 2] — [why]
+
+## Context
+
+[Background information that informs implementation:
+- Technical environment or ecosystem
+- Relevant prior work or experience
+- User research or feedback themes
+- Known issues to address]
+
+## Constraints
+
+- **[Type]**: [What] — [Why]
+- **[Type]**: [What] — [Why]
+
+Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+
+---
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**What This Is:**
+- Current accurate description of the product
+- 2-3 sentences capturing what it does and who it's for
+- Use the user's words and framing
+- Update when the product evolves beyond this description
+
+**Core Value:**
+- The single most important thing
+- Everything else can fail; this cannot
+- Drives prioritization when tradeoffs arise
+- Rarely changes; if it does, it's a significant pivot
+
+**Requirements — Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- ✓ [Requirement] — [version/phase]`
+- These are locked — changing them requires explicit discussion
+
+**Requirements — Active:**
+- Current scope being built toward
+- These are hypotheses until shipped and validated
+- Move to Validated when shipped, Out of Scope if invalidated
+
+**Requirements — Out of Scope:**
+- Explicit boundaries on what we're not building
+- Always include reasoning (prevents re-adding later)
+- Includes: considered and rejected, deferred to future, explicitly excluded
+
+**Context:**
+- Background that informs implementation decisions
+- Technical environment, prior work, user feedback
+- Known issues or technical debt to address
+- Update as new context emerges
+
+**Constraints:**
+- Hard limits on implementation choices
+- Tech stack, timeline, budget, compatibility, dependencies
+- Include the "why" — constraints without rationale get questioned
+
+**Key Decisions:**
+- Significant choices that affect future work
+- Add decisions as they're made throughout the project
+- Track outcome when known:
+  - ✓ Good — decision proved correct
+  - ⚠️ Revisit — decision may need reconsideration
+  - — Pending — too early to evaluate
+
+**Last Updated:**
+- Always note when and why the document was updated
+- Format: `after Phase 2` or `after v1.0 milestone`
+- Triggers review of whether content is still accurate
+
+</guidelines>
+
+<evolution>
+
+PROJECT.md evolves throughout the project lifecycle.
+These rules are embedded in the generated PROJECT.md (## Evolution section)
+and implemented by transition and milestone-completion workflows.
+
+**After each phase transition:**
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone:**
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state (users, feedback, metrics)
+
+</evolution>
+
+<brownfield>
+
+For existing codebases:
+
+1. **Map the codebase first** — analyze the project structure and existing code before defining requirements.
+
+2. **Infer Validated requirements** from existing code:
+   - What does the codebase actually do?
+   - What patterns are established?
+   - What's clearly working and relied upon?
+
+3. **Gather Active requirements** from user:
+   - Present inferred current state
+   - Ask what they want to build next
+
+4. **Initialize:**
+   - Validated = inferred from existing code
+   - Active = user's goals for this work
+   - Out of Scope = boundaries user specifies
+   - Context = includes current codebase state
+
+</brownfield>
+
+<state_reference>
+
+STATE.md references PROJECT.md:
+
+```markdown
+## Project Reference
+
+See: .planning/PROJECT.md (updated [date])
+
+**Core value:** [One-liner from Core Value section]
+**Current focus:** [Current phase name]
+```
+
+This ensures Claude reads current PROJECT.md context.
+
+</state_reference>

package/sdk/prompts/templates/requirements.md

@@ -0,0 +1,231 @@
+# Requirements Template
+
+Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done."
+
+<template>
+
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### [Category 2]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+- [ ] **[CAT]-03**: [Requirement description]
+
+### [Category 3]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### [Category]
+
+- **[CAT]-01**: [Requirement description]
+- **[CAT]-02**: [Requirement description]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| [REQ-ID] | Phase [N] | Pending |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Mapped to phases: [Y]
+- Unmapped: [Z] ⚠️
+
+---
+*Requirements defined: [date]*
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**Requirement Format:**
+- ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
+- Description: User-centric, testable, atomic
+- Checkbox: Only for v1 requirements (v2 are not yet actionable)
+
+**Categories:**
+- Derive from research FEATURES.md categories
+- Keep consistent with domain conventions
+- Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
+
+**v1 vs v2:**
+- v1: Committed scope, will be in roadmap phases
+- v2: Acknowledged but deferred, not in current roadmap
+- Moving v2 → v1 requires roadmap update
+
+**Out of Scope:**
+- Explicit exclusions with reasoning
+- Prevents "why didn't you include X?" later
+- Anti-features from research belong here with warnings
+
+**Traceability:**
+- Empty initially, populated during roadmap creation
+- Each requirement maps to exactly one phase
+- Unmapped requirements = roadmap gap
+
+**Status Values:**
+- Pending: Not started
+- In Progress: Phase is active
+- Complete: Requirement verified
+- Blocked: Waiting on external factor
+
+</guidelines>
+
+<evolution>
+
+**After each phase completes:**
+1. Mark covered requirements as Complete
+2. Update traceability status
+3. Note any requirements that changed scope
+
+**After roadmap updates:**
+1. Verify all v1 requirements still mapped
+2. Add new requirements if scope expanded
+3. Move requirements to v2/out of scope if descoped
+
+**Requirement completion criteria:**
+- Requirement is "Complete" when:
+  - Feature is implemented
+  - Feature is verified (tests pass, manual check done)
+  - Feature is committed
+
+</evolution>
+
+<example>
+
+```markdown
+# Requirements: CommunityApp
+
+**Defined:** 2025-01-14
+**Core Value:** Users can share and discuss content with people who share their interests
+
+## v1 Requirements
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### Profiles
+
+- [ ] **PROF-01**: User can create profile with display name
+- [ ] **PROF-02**: User can upload avatar image
+- [ ] **PROF-03**: User can write bio (max 500 chars)
+- [ ] **PROF-04**: User can view other users' profiles
+
+### Content
+
+- [ ] **CONT-01**: User can create text post
+- [ ] **CONT-02**: User can upload image with post
+- [ ] **CONT-03**: User can edit own posts
+- [ ] **CONT-04**: User can delete own posts
+- [ ] **CONT-05**: User can view feed of posts
+
+### Social
+
+- [ ] **SOCL-01**: User can follow other users
+- [ ] **SOCL-02**: User can unfollow users
+- [ ] **SOCL-03**: User can like posts
+- [ ] **SOCL-04**: User can comment on posts
+- [ ] **SOCL-05**: User can view activity feed (followed users' posts)
+
+## v2 Requirements
+
+### Notifications
+
+- **NOTF-01**: User receives in-app notifications
+- **NOTF-02**: User receives email for new followers
+- **NOTF-03**: User receives email for comments on own posts
+- **NOTF-04**: User can configure notification preferences
+
+### Moderation
+
+- **MODR-01**: User can report content
+- **MODR-02**: User can block other users
+- **MODR-03**: Admin can view reported content
+- **MODR-04**: Admin can remove content
+- **MODR-05**: Admin can ban users
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Real-time chat | High complexity, not core to community value |
+| Video posts | Storage/bandwidth costs, defer to v2+ |
+| OAuth login | Email/password sufficient for v1 |
+| Mobile app | Web-first, mobile later |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| PROF-01 | Phase 2 | Pending |
+| PROF-02 | Phase 2 | Pending |
+| PROF-03 | Phase 2 | Pending |
+| PROF-04 | Phase 2 | Pending |
+| CONT-01 | Phase 3 | Pending |
+| CONT-02 | Phase 3 | Pending |
+| CONT-03 | Phase 3 | Pending |
+| CONT-04 | Phase 3 | Pending |
+| CONT-05 | Phase 3 | Pending |
+| SOCL-01 | Phase 4 | Pending |
+| SOCL-02 | Phase 4 | Pending |
+| SOCL-03 | Phase 4 | Pending |
+| SOCL-04 | Phase 4 | Pending |
+| SOCL-05 | Phase 4 | Pending |
+
+**Coverage:**
+- v1 requirements: 18 total
+- Mapped to phases: 18
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2025-01-14*
+*Last updated: 2025-01-14 after initial definition*
+```
+
+</example>