gsd-opencode 1.5.2 → 1.6.0

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

@@ -1,8 +1,14 @@
 # Phase Context Template
 
-Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's vision for a phase.
+Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementation decisions for a phase.
 
-**Purpose:** Document how the user imagines the phase working. This is vision context, not technical analysis. Technical details come from research.
+**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
+
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `gsd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
+- `gsd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
 
 ---
 
@@ -12,43 +18,50 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's
 # Phase [X]: [Name] - Context
 
 **Gathered:** [date]
-**Status:** [Ready for research / Ready for planning]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
 
-<vision>
-## How This Should Work
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
 
-[User's description of how they imagine this phase working. What happens when someone uses it? What does it look/feel like? This is the "pitch" version, not the technical spec.]
+</domain>
 
-</vision>
+<decisions>
+## Implementation Decisions
 
-<essential>
-## What Must Be Nailed
+### [Area 1 that was discussed]
+- [Specific decision made]
+- [Another decision if applicable]
 
-[The core of this phase. If we only get one thing right, what is it? What's the non-negotiable that makes this phase successful?]
+### [Area 2 that was discussed]
+- [Specific decision made]
 
-- [Essential thing 1]
-- [Essential thing 2]
-- [Essential thing 3 if applicable]
+### [Area 3 that was discussed]
+- [Specific decision made]
 
-</essential>
+### OpenCode's Discretion
+[Areas where user explicitly said "you decide" — OpenCode has flexibility here during planning/implementation]
+
+</decisions>
 
 <specifics>
 ## Specific Ideas
 
-[Any particular things the user has in mind. References to existing products/features they like. Specific behaviors or interactions. "I want it to work like X" or "When you click Y, it should Z."]
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
 
-[If none: "No specific requirements - open to standard approaches"]
+[If none: "No specific requirements — open to standard approaches"]
 
 </specifics>
 
-<notes>
-## Additional Context
+<deferred>
+## Deferred Ideas
 
-[Anything else captured during the discussion that doesn't fit above. User's priorities, concerns mentioned, relevant background.]
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
 
-[If none: "No additional notes"]
+[If none: "None — discussion stayed within phase scope"]
 
-</notes>
+</deferred>
 
 ---
 
@@ -57,84 +70,222 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures the user's
 ```
 
 <good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
 ```markdown
-# Phase 3: User Dashboard - Context
+# Phase 3: Post Feed - Context
 
 **Gathered:** 2025-01-20
-**Status:** Ready for research
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
 
-<vision>
-## How This Should Work
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
 
-When users log in, they land on a dashboard that shows them everything important at a glance. I imagine it feeling calm and organized - not overwhelming like Jira or cluttered like Notion.
+</domain>
 
-The main thing is seeing their active projects and what needs attention. Think of it like a "what should I work on today" view. It should feel personal, not like enterprise software.
+<decisions>
+## Implementation Decisions
 
-</vision>
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
 
-<essential>
-## What Must Be Nailed
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
 
-- **At-a-glance clarity** - Within 2 seconds of landing, user knows what needs their attention
-- **Personal feel** - This is YOUR dashboard, not a team dashboard. It should feel like opening your personal notebook.
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
 
-</essential>
+### OpenCode's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+
+</decisions>
 
 <specifics>
 ## Specific Ideas
 
-- I like how Linear's home screen highlights what's assigned to you without noise
-- Should show projects in a card format, not a list
-- Maybe a "Today" section at the top with urgent stuff
-- Dark mode is essential (already have this from Phase 2)
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
 
 </specifics>
 
-<notes>
-## Additional Context
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 03-post-feed*
+*Context gathered: 2025-01-20*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### OpenCode's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
 
-User mentioned they've abandoned several dashboards before because they felt too "corporate." The key differentiator is making it feel personal and calm.
+<deferred>
+## Deferred Ideas
 
-Priority is clarity over features. Better to show less and make it obvious than show everything.
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
 
-</notes>
+</deferred>
 
 ---
 
-*Phase: 03-user-dashboard*
+*Phase: 02-backup-command*
 *Context gathered: 2025-01-20*
 ```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### OpenCode's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
 </good_examples>
 
 <guidelines>
-**This template captures VISION, not technical specs.**
-
-The user is the visionary. They know:
-- How they imagine it working
-- What it should feel like
-- What's essential vs nice-to-have
-- References to things they like
-
-The user does NOT know (and shouldn't be asked):
-- Codebase patterns (OpenCode reads the code)
-- Technical risks (OpenCode identifies during research)
-- Implementation constraints (OpenCode figures out)
-- Success metrics (OpenCode infers from the work)
-
-**Content should read like:**
-- A founder describing their product vision
-- "When you use this, it should feel like..."
-- "The most important thing is..."
-- "I don't want it to be like X, I want it to feel like Y"
-
-**Content should NOT read like:**
-- A technical specification
-- Risk assessment matrix
-- Success criteria checklist
-- Codebase analysis
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**Sections explained:**
+
+- **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
+- **Decisions** — Organized by areas discussed (NOT predefined categories). Section headers come from the actual discussion — "Layout style", "Flag design", "Grouping criteria", etc.
+- **OpenCode's Discretion** — Explicit acknowledgment of what OpenCode can decide during implementation.
+- **Specifics** — Product references, examples, "like X but..." statements.
+- **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas.
 
 **After creation:**
 - File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
-- Research phase adds technical context (patterns, risks, constraints)
-- Planning phase creates executable tasks informed by both vision AND research
+- `gsd-phase-researcher` uses decisions to focus investigation
+- `gsd-planner` uses decisions + research to create executable tasks
+- Downstream agents should NOT need to ask the user again about captured decisions
 </guidelines>

package/get-shit-done/templates/debug-subagent-prompt.md

@@ -0,0 +1,91 @@
+# Debug Subagent Prompt Template
+
+Template for spawning gsd-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
+
+---
+
+## Template
+
+```markdown
+<objective>
+Investigate issue: {issue_id}
+
+**Summary:** {issue_summary}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: {true_or_false}
+goal: {find_root_cause_only | find_and_fix}
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Source | Example |
+|-------------|--------|---------|
+| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` |
+| `{issue_summary}` | User description | `Auth screen is too dark` |
+| `{expected}` | From symptoms | `See logo clearly` |
+| `{actual}` | From symptoms | `Screen is dark` |
+| `{errors}` | From symptoms | `None in console` |
+| `{reproduction}` | From symptoms | `Open /auth page` |
+| `{timeline}` | From symptoms | `After recent deploy` |
+| `{goal}` | Orchestrator sets | `find_and_fix` |
+| `{slug}` | Generated | `auth-screen-dark` |
+
+---
+
+## Usage
+
+**From /gsd-debug:**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="gsd-debugger",
+  description="Debug {slug}"
+)
+```
+
+**From diagnose-issues (UAT):**
+```python
+Task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")
+```
+
+---
+
+## Continuation
+
+For checkpoints, spawn fresh agent with:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: {goal}
+</mode>
+```

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

@@ -51,21 +51,21 @@ Output: DISCOVERY.md with recommendation
 **Source Priority:**
 1. **Context7 MCP** - For library/framework documentation (current, authoritative)
 2. **Official Docs** - For platform-specific or non-indexed libraries
-3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
+3. **webfetch** - For comparisons, trends, community patterns (verify all findings)
 
 **Quality Checklist:**
 Before completing discovery, verify:
 - [ ] All claims have authoritative sources (Context7 or official docs)
 - [ ] Negative claims ("X is not possible") verified with official documentation
-- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
-- [ ] WebSearch findings cross-checked with authoritative sources
+- [ ] API syntax/configuration from Context7 or official docs (never webfetch alone)
+- [ ] webfetch findings cross-checked with authoritative sources
 - [ ] Recent updates/changelogs checked for breaking changes
 - [ ] Alternative approaches considered (not just first solution found)
 
 **Confidence Levels:**
 - HIGH: Context7 or official docs confirm
-- MEDIUM: WebSearch + Context7/official docs confirm
-- LOW: WebSearch only or training knowledge only (mark for validation)
+- MEDIUM: webfetch + Context7/official docs confirm
+- LOW: webfetch only or training knowledge only (mark for validation)
 
 </discovery_protocol>
 

package/get-shit-done/templates/phase-prompt.md

@@ -1,5 +1,8 @@
 # Phase Prompt Template
 
+> **Note:** Planning methodology is in `agents/gsd-planner.md`.
+> This template defines the PLAN.md output format that the agent produces.
+
 Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans optimized for parallel execution.
 
 **Naming:** Use `{phase}-{plan}-PLAN.md` format (e.g., `01-02-PLAN.md` for Phase 1, Plan 2)
@@ -17,7 +20,13 @@ wave: N                     # Execution wave (1, 2, 3...). Pre-computed at plan
 depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"]).
 files_modified: []          # Files this plan modifies.
 autonomous: true            # false if plan has checkpoints requiring user interaction
-domain: [optional - if domain skill loaded]
+user_setup: []              # Human-required setup OpenCode cannot automate (see below)
+
+# Goal-backward verification (derived during planning, verified after execution)
+must_haves:
+  truths: []                # Observable behaviors that must be true for goal achievement
+  artifacts: []             # Files that must exist with real implementation
+  key_links: []             # Critical connections between artifacts
 ---
 
 <objective>
@@ -130,10 +139,13 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `depends_on` | Yes | Array of plan IDs this plan requires. |
 | `files_modified` | Yes | Files this plan touches. |
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
-| `domain` | No | Domain skill if loaded (e.g., `next-js`) |
+| `user_setup` | No | Array of human-required setup items (external services) |
+| `must_haves` | Yes | Goal-backward verification criteria (see below) |
 
 **Wave is pre-computed:** Wave numbers are assigned during `/gsd-plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
 
+**Must-haves enable verification:** The `must_haves` field carries goal-backward requirements from planning to execution. After all plans complete, execute-phase spawns a verification subagent that checks these criteria against the actual codebase.
+
 ---
 
 ## Parallel vs Sequential
@@ -461,3 +473,104 @@ files_modified: [...]
 - Only reference prior SUMMARYs when genuinely needed
 - Group checkpoints with related auto tasks in same plan
 - 2-3 tasks per plan, ~50% context max
+
+---
+
+## User Setup (External Services)
+
+When a plan introduces external services requiring human configuration, declare in frontmatter:
+
+```yaml
+user_setup:
+  - service: stripe
+    why: "Payment processing requires API keys"
+    env_vars:
+      - name: STRIPE_SECRET_KEY
+        source: "Stripe Dashboard → Developers → API keys → Secret key"
+      - name: STRIPE_WEBHOOK_SECRET
+        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
+    dashboard_config:
+      - task: "Create webhook endpoint"
+        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
+        details: "URL: https://[your-domain]/api/webhooks/stripe"
+    local_dev:
+      - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
+```
+
+**The automation-first rule:** `user_setup` contains ONLY what OpenCode literally cannot do:
+- Account creation (requires human signup)
+- Secret retrieval (requires dashboard access)
+- Dashboard configuration (requires human in browser)
+
+**NOT included:** Package installs, code changes, file creation, CLI commands OpenCode can run.
+
+**Result:** Execute-plan generates `{phase}-USER-SETUP.md` with checklist for the user.
+
+See `~/.config/opencode/get-shit-done/templates/user-setup.md` for full schema and examples
+
+---
+
+## Must-Haves (Goal-Backward Verification)
+
+The `must_haves` field defines what must be TRUE for the phase goal to be achieved. Derived during planning, verified after execution.
+
+**Structure:**
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+    - "Messages persist across refresh"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+      min_lines: 30
+    - path: "src/app/api/chat/route.ts"
+      provides: "Message CRUD operations"
+      exports: ["GET", "POST"]
+    - path: "prisma/schema.prisma"
+      provides: "Message model"
+      contains: "model Message"
+  key_links:
+    - from: "src/components/Chat.tsx"
+      to: "/api/chat"
+      via: "fetch in useEffect"
+      pattern: "fetch.*api/chat"
+    - from: "src/app/api/chat/route.ts"
+      to: "prisma.message"
+      via: "database query"
+      pattern: "prisma\\.message\\.(find|create)"
+```
+
+**Field descriptions:**
+
+| Field | Purpose |
+|-------|---------|
+| `truths` | Observable behaviors from user perspective. Each must be testable. |
+| `artifacts` | Files that must exist with real implementation. |
+| `artifacts[].path` | File path relative to project root. |
+| `artifacts[].provides` | What this artifact delivers. |
+| `artifacts[].min_lines` | Optional. Minimum lines to be considered substantive. |
+| `artifacts[].exports` | Optional. Expected exports to verify. |
+| `artifacts[].contains` | Optional. Pattern that must exist in file. |
+| `key_links` | Critical connections between artifacts. |
+| `key_links[].from` | Source artifact. |
+| `key_links[].to` | Target artifact or endpoint. |
+| `key_links[].via` | How they connect (description). |
+| `key_links[].pattern` | Optional. Regex to verify connection exists. |
+
+**Why this matters:**
+
+Task completion ≠ Goal achievement. A task "create chat component" can complete by creating a placeholder. The `must_haves` field captures what must actually work, enabling verification to catch gaps before they compound.
+
+**Verification flow:**
+
+1. Plan-phase derives must_haves from phase goal (goal-backward)
+2. Must_haves written to PLAN.md frontmatter
+3. Execute-phase runs all plans
+4. Verification subagent checks must_haves against codebase
+5. Gaps found → fix plans created → execute → re-verify
+6. All must_haves pass → phase complete
+
+See `~/.config/opencode/get-shit-done/workflows/verify-phase.md` for verification logic.