gsd-opencode 1.5.2 → 1.6.0

package/get-shit-done/templates/research-project/PITFALLS.md

@@ -0,0 +1,200 @@
+# Pitfalls Research Template
+
+Template for `.planning/research/PITFALLS.md` — common mistakes to avoid in the project domain.
+
+<template>
+
+```markdown
+# Pitfalls Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Critical Pitfalls
+
+### Pitfall 1: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+### Pitfall 2: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+### Pitfall 3: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+[Continue for all critical pitfalls...]
+
+## Technical Debt Patterns
+
+Shortcuts that seem reasonable but create long-term problems.
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+
+## Integration Gotchas
+
+Common mistakes when connecting to external services.
+
+| Integration | Common Mistake | Correct Approach |
+|-------------|----------------|------------------|
+| [service] | [what people do wrong] | [what to do instead] |
+| [service] | [what people do wrong] | [what to do instead] |
+| [service] | [what people do wrong] | [what to do instead] |
+
+## Performance Traps
+
+Patterns that work at small scale but fail as usage grows.
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+
+## Security Mistakes
+
+Domain-specific security issues beyond general web security.
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| [mistake] | [what could happen] | [how to avoid] |
+| [mistake] | [what could happen] | [how to avoid] |
+| [mistake] | [what could happen] | [how to avoid] |
+
+## UX Pitfalls
+
+Common user experience mistakes in this domain.
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| [pitfall] | [how users suffer] | [what to do instead] |
+| [pitfall] | [how users suffer] | [what to do instead] |
+| [pitfall] | [how users suffer] | [what to do instead] |
+
+## "Looks Done But Isn't" Checklist
+
+Things that appear complete but are missing critical pieces.
+
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+
+## Recovery Strategies
+
+When pitfalls occur despite prevention, how to recover.
+
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+
+## Pitfall-to-Phase Mapping
+
+How roadmap phases should address these pitfalls.
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+
+## Sources
+
+- [Post-mortems referenced]
+- [Community discussions]
+- [Official "gotchas" documentation]
+- [Personal experience / known issues]
+
+---
+*Pitfalls research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Critical Pitfalls:**
+- Focus on domain-specific issues, not generic mistakes
+- Include warning signs — early detection prevents disasters
+- Link to specific phases — makes pitfalls actionable
+
+**Technical Debt:**
+- Be realistic — some shortcuts are acceptable
+- Note when shortcuts are "never acceptable" vs. "only in MVP"
+- Include the long-term cost to inform tradeoff decisions
+
+**Performance Traps:**
+- Include scale thresholds ("breaks at 10k users")
+- Focus on what's relevant for this project's expected scale
+- Don't over-engineer for hypothetical scale
+
+**Security Mistakes:**
+- Beyond OWASP basics — domain-specific issues
+- Example: Community platforms have different security concerns than e-commerce
+- Include risk level to prioritize
+
+**"Looks Done But Isn't":**
+- Checklist format for verification during execution
+- Common in demos vs. production
+- Prevents "it works on my machine" issues
+
+**Pitfall-to-Phase Mapping:**
+- Critical for roadmap creation
+- Each pitfall should map to a phase that prevents it
+- Informs phase ordering and success criteria
+
+</guidelines>

package/get-shit-done/templates/research-project/STACK.md

@@ -0,0 +1,120 @@
+# Stack Research Template
+
+Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
+
+<template>
+
+```markdown
+# Stack Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+
+### Development Tools
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| [name] | [what it does] | [configuration tips] |
+| [name] | [what it does] | [configuration tips] |
+
+## Installation
+
+```bash
+# Core
+npm install [packages]
+
+# Supporting
+npm install [packages]
+
+# Dev dependencies
+npm install -D [packages]
+```
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| [our choice] | [other option] | [conditions where alternative is better] |
+| [our choice] | [other option] | [conditions where alternative is better] |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| [technology] | [specific problem] | [recommended alternative] |
+| [technology] | [specific problem] | [recommended alternative] |
+
+## Stack Patterns by Variant
+
+**If [condition]:**
+- Use [variation]
+- Because [reason]
+
+**If [condition]:**
+- Use [variation]
+- Because [reason]
+
+## Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| [package@version] | [package@version] | [compatibility notes] |
+
+## Sources
+
+- [Context7 library ID] — [topics fetched]
+- [Official docs URL] — [what was verified]
+- [Other source] — [confidence level]
+
+---
+*Stack research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Core Technologies:**
+- Include specific version numbers
+- Explain why this is the standard choice, not just what it does
+- Focus on technologies that affect architecture decisions
+
+**Supporting Libraries:**
+- Include libraries commonly needed for this domain
+- Note when each is needed (not all projects need all libraries)
+
+**Alternatives:**
+- Don't just dismiss alternatives
+- Explain when alternatives make sense
+- Helps user make informed decisions if they disagree
+
+**What NOT to Use:**
+- Actively warn against outdated or problematic choices
+- Explain the specific problem, not just "it's old"
+- Provide the recommended alternative
+
+**Version Compatibility:**
+- Note any known compatibility issues
+- Critical for avoiding debugging time later
+
+</guidelines>

package/get-shit-done/templates/research-project/SUMMARY.md

@@ -0,0 +1,170 @@
+# Research Summary Template
+
+Template for `.planning/research/SUMMARY.md` — executive summary of project research with roadmap implications.
+
+<template>
+
+```markdown
+# Project Research Summary
+
+**Project:** [name from PROJECT.md]
+**Domain:** [inferred domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Executive Summary
+
+[2-3 paragraph overview of research findings]
+
+- What type of product this is and how experts build it
+- The recommended approach based on research
+- Key risks and how to mitigate them
+
+## Key Findings
+
+### Recommended Stack
+
+[Summary from STACK.md — 1-2 paragraphs]
+
+**Core technologies:**
+- [Technology]: [purpose] — [why recommended]
+- [Technology]: [purpose] — [why recommended]
+- [Technology]: [purpose] — [why recommended]
+
+### Expected Features
+
+[Summary from FEATURES.md]
+
+**Must have (table stakes):**
+- [Feature] — users expect this
+- [Feature] — users expect this
+
+**Should have (competitive):**
+- [Feature] — differentiator
+- [Feature] — differentiator
+
+**Defer (v2+):**
+- [Feature] — not essential for launch
+
+### Architecture Approach
+
+[Summary from ARCHITECTURE.md — 1 paragraph]
+
+**Major components:**
+1. [Component] — [responsibility]
+2. [Component] — [responsibility]
+3. [Component] — [responsibility]
+
+### Critical Pitfalls
+
+[Top 3-5 from PITFALLS.md]
+
+1. **[Pitfall]** — [how to avoid]
+2. **[Pitfall]** — [how to avoid]
+3. **[Pitfall]** — [how to avoid]
+
+## Implications for Roadmap
+
+Based on research, suggested phase structure:
+
+### Phase 1: [Name]
+**Rationale:** [why this comes first based on research]
+**Delivers:** [what this phase produces]
+**Addresses:** [features from FEATURES.md]
+**Avoids:** [pitfall from PITFALLS.md]
+
+### Phase 2: [Name]
+**Rationale:** [why this order]
+**Delivers:** [what this phase produces]
+**Uses:** [stack elements from STACK.md]
+**Implements:** [architecture component]
+
+### Phase 3: [Name]
+**Rationale:** [why this order]
+**Delivers:** [what this phase produces]
+
+[Continue for suggested phases...]
+
+### Phase Ordering Rationale
+
+- [Why this order based on dependencies discovered]
+- [Why this grouping based on architecture patterns]
+- [How this avoids pitfalls from research]
+
+### Research Flags
+
+Phases likely needing deeper research during planning:
+- **Phase [X]:** [reason — e.g., "complex integration, needs API research"]
+- **Phase [Y]:** [reason — e.g., "niche domain, sparse documentation"]
+
+Phases with standard patterns (skip research-phase):
+- **Phase [X]:** [reason — e.g., "well-documented, established patterns"]
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | [HIGH/MEDIUM/LOW] | [reason] |
+| Features | [HIGH/MEDIUM/LOW] | [reason] |
+| Architecture | [HIGH/MEDIUM/LOW] | [reason] |
+| Pitfalls | [HIGH/MEDIUM/LOW] | [reason] |
+
+**Overall confidence:** [HIGH/MEDIUM/LOW]
+
+### Gaps to Address
+
+[Any areas where research was inconclusive or needs validation during implementation]
+
+- [Gap]: [how to handle during planning/execution]
+- [Gap]: [how to handle during planning/execution]
+
+## Sources
+
+### Primary (HIGH confidence)
+- [Context7 library ID] — [topics]
+- [Official docs URL] — [what was checked]
+
+### Secondary (MEDIUM confidence)
+- [Source] — [finding]
+
+### Tertiary (LOW confidence)
+- [Source] — [finding, needs validation]
+
+---
+*Research completed: [date]*
+*Ready for roadmap: yes*
+```
+
+</template>
+
+<guidelines>
+
+**Executive Summary:**
+- write for someone who will only read this section
+- Include the key recommendation and main risk
+- 2-3 paragraphs maximum
+
+**Key Findings:**
+- Summarize, don't duplicate full documents
+- Link to detailed docs (STACK.md, FEATURES.md, etc.)
+- Focus on what matters for roadmap decisions
+
+**Implications for Roadmap:**
+- This is the most important section
+- Directly informs roadmap creation
+- Be explicit about phase suggestions and rationale
+- Include research flags for each suggested phase
+
+**Confidence Assessment:**
+- Be honest about uncertainty
+- Note gaps that need resolution during planning
+- HIGH = verified with official sources
+- MEDIUM = community consensus, multiple sources agree
+- LOW = single source or inference
+
+**Integration with roadmap creation:**
+- This file is loaded as context during roadmap creation
+- Phase suggestions here become starting point for roadmap
+- Research flags inform phase planning
+
+</guidelines>

package/get-shit-done/templates/research.md

@@ -189,10 +189,10 @@ Things that couldn't be fully resolved:
 - [Official docs URL] - [what was checked]
 
 ### Secondary (MEDIUM confidence)
-- [WebSearch verified with official source] - [finding + verification]
+- [webfetch verified with official source] - [finding + verification]
 
 ### Tertiary (LOW confidence - needs validation)
-- [WebSearch only] - [finding, marked for validation during implementation]
+- [webfetch only] - [finding, marked for validation during implementation]
 </sources>
 
 <metadata>

package/get-shit-done/templates/roadmap.md

@@ -11,15 +11,6 @@ Template for `.planning/ROADMAP.md`.
 
 [One paragraph describing the journey from start to finish]
 
-## Domain Expertise
-
-[Paths to domain skills that inform planning. These SKILL.md files serve as indexes - during phase planning, read them to find relevant references for each phase type.]
-
-- ~/.config/opencode/skills/expertise/[domain]/SKILL.md
-[Add additional domains if project spans multiple (e.g., ISF shaders + macOS app)]
-
-Or: None
-
 ## Phases
 
 **Phase Numbering:**
@@ -38,7 +29,11 @@ Decimal phases appear between their surrounding integers in numeric order.
 ### Phase 1: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Nothing (first phase)
-**Research**: Unlikely (established patterns)
+**Requirements**: [REQ-01, REQ-02, REQ-03]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
 **Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
 
 Plans:
@@ -49,8 +44,10 @@ Plans:
 ### Phase 2: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 1
-**Research**: Likely (new integration)
-**Research topics**: [What needs investigating]
+**Requirements**: [REQ-04, REQ-05]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
 **Plans**: [Number of plans]
 
 Plans:
@@ -60,6 +57,8 @@ Plans:
 ### Phase 2.1: Critical Fix (INSERTED)
 **Goal**: [Urgent work inserted between phases]
 **Depends on**: Phase 2
+**Success Criteria** (what must be TRUE):
+  1. [What the fix achieves]
 **Plans**: 1 plan
 
 Plans:
@@ -68,8 +67,11 @@ Plans:
 ### Phase 3: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 2
-**Research**: Likely (external API)
-**Research topics**: [What needs investigating]
+**Requirements**: [REQ-06, REQ-07, REQ-08]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
 **Plans**: [Number of plans]
 
 Plans:
@@ -79,7 +81,10 @@ Plans:
 ### Phase 4: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 3
-**Research**: Unlikely (internal patterns)
+**Requirements**: [REQ-09, REQ-10]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
 **Plans**: [Number of plans]
 
 Plans:
@@ -108,11 +113,12 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning
 
-**Research flags:**
-- `Research: Likely` - External APIs, new libraries, architectural decisions
-- `Research: Unlikely` - Internal patterns, CRUD operations, established conventions
-- Include `Research topics:` when Likely
-- Flags are hints, not mandates - validate at planning time
+**Success criteria:**
+- 2-5 observable behaviors per phase (from user's perspective)
+- Cross-checked against requirements during roadmap creation
+- Flow downstream to `must_haves` in plan-phase
+- Verified by verify-phase after execution
+- Format: "User can [action]" or "[Thing] works/exists"
 
 **After milestones ship:**
 - Collapse completed milestones in `<details>` tags

package/get-shit-done/templates/state.md

@@ -54,12 +54,6 @@ Recent decisions affecting current work:
 - [Phase X]: [Decision summary]
 - [Phase Y]: [Decision summary]
 
-### Deferred Issues
-
-[From ISSUES.md — list open items with phase of origin]
-
-None yet.
-
 ### Pending Todos
 
 [From .planning/todos/pending/ — ideas captured during sessions]
@@ -86,7 +80,7 @@ STATE.md is the project's short-term memory spanning all phases and sessions.
 **Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
 
 **Solution:** A single, small file that's:
-- Read first in every workflow
+- read first in every workflow
 - Updated after every significant action
 - Contains digest of accumulated context
 - Enables instant session restoration
@@ -110,7 +104,6 @@ STATE.md is the project's short-term memory spanning all phases and sessions.
 - execute: After SUMMARY.md created
   - Update position (phase, plan, status)
   - Note new decisions (detail in PROJECT.md)
-  - Update deferred issues list
   - Add blockers/concerns
 - transition: After phase marked complete
   - Update progress bar
@@ -152,12 +145,6 @@ Updated after each plan completion.
 
 **Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
 
-**Deferred Issues:** Open items from ISSUES.md
-- Brief description with ISS-XXX number
-- Phase where discovered
-- Effort estimate if known
-- Helps phase planning identify what to address
-
 **Pending Todos:** Ideas captured via /gsd-add-todo
 - Count of pending todos
 - Reference to .planning/todos/pending/
@@ -182,7 +169,6 @@ Keep STATE.md under 100 lines.
 
 It's a DIGEST, not an archive. If accumulated context grows too large:
 - Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
-- Reference ISSUES.md instead of listing all: "12 open issues — see ISSUES.md"
 - Keep only active blockers, remove resolved ones
 
 The goal is "read once, know where we are" — if it's too long, that fails.
@@ -208,14 +194,13 @@ The goal is "read once, know where we are" — if it's too long, that fails.
 **Size management:**
 - Keep under 100 lines total
 - Recent decisions only in STATE.md (full log in PROJECT.md)
-- Reference ISSUES.md instead of listing all issues
 - Keep only active blockers
 
 **Sections:**
 - Project Reference: Pointer to PROJECT.md with core value
 - Current Position: Where we are now (phase, plan, status)
 - Performance Metrics: Velocity tracking
-- Accumulated Context: Recent decisions, deferred issues, blockers
+- Accumulated Context: Recent decisions, pending todos, blockers
 - Session Continuity: Resume information
 
 </guidelines>