gsd-opencode 1.22.1 → 1.30.0

package/get-shit-done/references/workstream-flag.md

@@ -0,0 +1,58 @@
+# Workstream Flag (`--ws`)
+
+## Overview
+
+The `--ws <name>` flag scopes GSD operations to a specific workstream, enabling
+parallel milestone work by multiple OpenCode instances on the same codebase.
+
+## Resolution Priority
+
+1. `--ws <name>` flag (explicit, highest priority)
+2. `GSD_WORKSTREAM` environment variable (per-instance)
+3. `.planning/active-workstream` file (shared, last-writer-wins)
+4. `null` — flat mode (no workstreams)
+
+## Routing Propagation
+
+All workflow routing commands include `${GSD_WS}` which:
+- Expands to `--ws <name>` when a workstream is active
+- Expands to empty string in flat mode (backward compatible)
+
+This ensures workstream scope chains automatically through the workflow:
+`new-milestone → discuss-phase → plan-phase → execute-phase → transition`
+
+## Directory Structure
+
+```
+.planning/
+├── PROJECT.md          # Shared
+├── config.json         # Shared
+├── milestones/         # Shared
+├── codebase/           # Shared
+├── active-workstream   # Points to current ws
+└── workstreams/
+    ├── feature-a/      # Workstream A
+    │   ├── STATE.md
+    │   ├── ROADMAP.md
+    │   ├── REQUIREMENTS.md
+    │   └── phases/
+    └── feature-b/      # Workstream B
+        ├── STATE.md
+        ├── ROADMAP.md
+        ├── REQUIREMENTS.md
+        └── phases/
+```
+
+## CLI Usage
+
+```bash
+# All gsd-tools commands accept --ws
+node gsd-tools.cjs state json --ws feature-a
+node gsd-tools.cjs find-phase 3 --ws feature-b
+
+# Workstream CRUD
+node gsd-tools.cjs workstream create <name>
+node gsd-tools.cjs workstream list
+node gsd-tools.cjs workstream status <name>
+node gsd-tools.cjs workstream complete <name>
+```

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

@@ -8,7 +8,7 @@ Template for `.planning/phases/XX-name/{phase_num}-UAT.md` — persistent UAT se
 
 ```markdown
 ---
-status: testing | complete | diagnosed
+status: testing | partial | complete | diagnosed
 phase: XX-name
 source: [list of SUMMARY.md files tested]
 started: [ISO timestamp]
@@ -45,6 +45,12 @@ expected: [observable behavior]
 result: skipped
 reason: [why skipped]
 
+### 5. [Test Name]
+expected: [observable behavior]
+result: blocked
+blocked_by: server | physical-device | release-build | third-party | prior-phase
+reason: [why blocked]
+
 ...
 
 ## Summary
@@ -54,6 +60,7 @@ passed: [N]
 issues: [N]
 pending: [N]
 skipped: [N]
+blocked: [N]
 
 ## Gaps
 
@@ -74,7 +81,7 @@ skipped: [N]
 <section_rules>
 
 **Frontmatter:**
-- `status`: OVERWRITE - "testing" or "complete"
+- `status`: OVERWRITE - "testing", "partial", or "complete"
 - `phase`: IMMUTABLE - set on creation
 - `source`: IMMUTABLE - SUMMARY files being tested
 - `started`: IMMUTABLE - set on creation
@@ -87,9 +94,10 @@ skipped: [N]
 
 **Tests:**
 - Each test: OVERWRITE result field when user responds
-- `result` values: [pending], pass, issue, skipped
+- `result` values: [pending], pass, issue, skipped, blocked
 - If issue: add `reported` (verbatim) and `severity` (inferred)
 - If skipped: add `reason` if provided
+- If blocked: add `blocked_by` (tag) and `reason` (if provided)
 
 **Summary:**
 - OVERWRITE counts after each response
@@ -156,6 +164,16 @@ skipped: [N]
 - Commit file
 - Present summary with next steps
 
+**Partial completion:**
+- status → "partial" (if pending, blocked, or unresolved skipped tests remain)
+- Current Test → "[testing paused — {N} items outstanding]"
+- Commit file
+- Present summary with outstanding items highlighted
+
+**Resuming partial session:**
+- `/gsd-verify-work {phase}` picks up from first pending/blocked test
+- When all items resolved, status advances to "complete"
+
 **Resume after /new:**
 1. read frontmatter → know phase and status
 2. read Current Test → know where we are

package/get-shit-done/templates/UI-SPEC.md

@@ -0,0 +1,100 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+shadcn_initialized: false
+preset: none
+created: {date}
+---
+
+# Phase {N} — UI Design Contract
+
+> Visual and interaction contract for frontend phases. Generated by gsd-ui-researcher, verified by gsd-ui-checker.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | {shadcn / none} |
+| Preset | {preset string or "not applicable"} |
+| Component library | {radix / base-ui / none} |
+| Icon library | {library} |
+| Font | {font} |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon gaps, inline padding |
+| sm | 8px | Compact element spacing |
+| md | 16px | Default element spacing |
+| lg | 24px | Section padding |
+| xl | 32px | Layout gaps |
+| 2xl | 48px | Major section breaks |
+| 3xl | 64px | Page-level spacing |
+
+Exceptions: {list any, or "none"}
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height |
+|------|------|--------|-------------|
+| Body | {px} | {weight} | {ratio} |
+| Label | {px} | {weight} | {ratio} |
+| Heading | {px} | {weight} | {ratio} |
+| Display | {px} | {weight} | {ratio} |
+
+---
+
+## Color
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Dominant (60%) | {hex} | Background, surfaces |
+| Secondary (30%) | {hex} | Cards, sidebar, nav |
+| Accent (10%) | {hex} | {list specific elements only} |
+| Destructive | {hex} | Destructive actions only |
+
+Accent reserved for: {explicit list — never "all interactive elements"}
+
+---
+
+## Copywriting Contract
+
+| Element | Copy |
+|---------|------|
+| Primary CTA | {specific verb + noun} |
+| Empty state heading | {copy} |
+| Empty state body | {copy + next step} |
+| Error state | {problem + solution path} |
+| Destructive confirmation | {action name}: {confirmation copy} |
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| shadcn official | {list} | not required |
+| {third-party name} | {list} | shadcn view + diff required |
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** {pending / approved YYYY-MM-DD}

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

@@ -0,0 +1,122 @@
+# AGENTS.md Template
+
+Template for project-root `AGENTS.md` — auto-generated by `gsd-tools generate-OpenCode-md`.
+
+Contains 6 marker-bounded sections. Each section is independently updatable.
+The `generate-OpenCode-md` subcommand manages 5 sections (project, stack, conventions, architecture, workflow enforcement).
+The profile section is managed exclusively by `generate-OpenCode-profile`.
+
+---
+
+## Section Templates
+
+### Project Section
+```
+<!-- GSD:project-start source:PROJECT.md -->
+## Project
+
+{{project_content}}
+<!-- GSD:project-end -->
+```
+
+**Fallback text:**
+```
+Project not yet initialized. Run /gsd-new-project to set up.
+```
+
+### Stack Section
+```
+<!-- GSD:stack-start source:STACK.md -->
+## Technology Stack
+
+{{stack_content}}
+<!-- GSD:stack-end -->
+```
+
+**Fallback text:**
+```
+Technology stack not yet documented. Will populate after codebase mapping or first phase.
+```
+
+### Conventions Section
+```
+<!-- GSD:conventions-start source:CONVENTIONS.md -->
+## Conventions
+
+{{conventions_content}}
+<!-- GSD:conventions-end -->
+```
+
+**Fallback text:**
+```
+Conventions not yet established. Will populate as patterns emerge during development.
+```
+
+### Architecture Section
+```
+<!-- GSD:architecture-start source:ARCHITECTURE.md -->
+## Architecture
+
+{{architecture_content}}
+<!-- GSD:architecture-end -->
+```
+
+**Fallback text:**
+```
+Architecture not yet mapped. Follow existing patterns found in the codebase.
+```
+
+### Workflow Enforcement Section
+```
+<!-- GSD:workflow-start source:GSD defaults -->
+## GSD Workflow Enforcement
+
+Before using edit, write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
+
+Use these entry points:
+- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
+- `/gsd-debug` for investigation and bug fixing
+- `/gsd-execute-phase` for planned phase work
+
+Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
+<!-- GSD:workflow-end -->
+```
+
+### Profile Section (Placeholder Only)
+```
+<!-- GSD:profile-start -->
+## Developer Profile
+
+> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
+> This section is managed by `generate-OpenCode-profile` — do not edit manually.
+<!-- GSD:profile-end -->
+```
+
+**Note:** This section is NOT managed by `generate-OpenCode-md`. It is managed exclusively
+by `generate-OpenCode-profile`. The placeholder above is only used when creating a new
+AGENTS.md file and no profile section exists yet.
+
+---
+
+## Section Ordering
+
+1. **Project** — Identity and purpose (what this project is)
+2. **Stack** — Technology choices (what tools are used)
+3. **Conventions** — Code patterns and rules (how code is written)
+4. **Architecture** — System structure (how components fit together)
+5. **Workflow Enforcement** — Default GSD entry points for file-changing work
+6. **Profile** — Developer behavioral preferences (how to interact)
+
+## Marker Format
+
+- Start: `<!-- GSD:{name}-start source:{file} -->`
+- End: `<!-- GSD:{name}-end -->`
+- Source attribute enables targeted updates when source files change
+- Partial match on start marker (without closing `-->`) for detection
+
+## Fallback Behavior
+
+When a source file is missing, fallback text provides OpenCode-actionable guidance:
+- Guides OpenCode's behavior in the absence of data
+- Not placeholder ads or "missing" notices
+- Each fallback tells OpenCode what to do, not just what's absent

package/get-shit-done/templates/config.json

@@ -6,11 +6,14 @@
     "plan_check": true,
     "verifier": true,
     "auto_advance": false,
-    "nyquist_validation": true
+    "nyquist_validation": true,
+    "discuss_mode": "discuss",
+    "research_before_questions": false
   },
   "planning": {
     "commit_docs": true,
-    "search_gitignored": false
+    "search_gitignored": false,
+    "sub_repos": []
   },
   "parallelization": {
     "enabled": true,
@@ -33,5 +36,9 @@
   "safety": {
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
-  }
+  },
+  "hooks": {
+    "context_warnings": true
+  },
+  "agent_skills": {}
 }

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

@@ -31,14 +31,14 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem
 ## Implementation Decisions
 
 ### [Area 1 that was discussed]
-- [Specific decision made]
-- [Another decision if applicable]
+- **D-01:** [Specific decision made]
+- **D-02:** [Another decision if applicable]
 
 ### [Area 2 that was discussed]
-- [Specific decision made]
+- **D-03:** [Specific decision made]
 
 ### [Area 3 that was discussed]
-- [Specific decision made]
+- **D-04:** [Specific decision made]
 
 ### OpenCode's Discretion
 [Areas where user explicitly said "you decide" — OpenCode has flexibility here during planning/implementation]
@@ -54,6 +54,24 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem
 
 </specifics>
 
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+[List every spec, ADR, feature doc, or design doc that defines requirements or constraints for this phase. Use full relative paths so agents can read them directly. Group by topic area when the phase has multiple concerns.]
+
+### [Topic area 1]
+- `path/to/spec-or-adr.md` — [What this doc decides/defines that's relevant]
+- `path/to/doc.md` §N — [Specific section and what it covers]
+
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What capability this defines]
+
+[If the project has no external specs: "No external specs — requirements are fully captured in decisions above"]
+
+</canonical_refs>
+
 <code_context>
 ## Existing Code Insights
 
@@ -124,6 +142,18 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 
 </decisions>
 
+<canonical_refs>
+## Canonical References
+
+### Feed display
+- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
+- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualization requirements
+
+### Empty states
+- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
+
+</canonical_refs>
+
 <specifics>
 ## Specific Ideas
 
@@ -186,6 +216,15 @@ CLI command to backup database to local file or S3. Supports full and incrementa
 
 </decisions>
 
+<canonical_refs>
+## Canonical References
+
+### Backup CLI
+- `docs/features/backup-restore.md` — Backup requirements, supported backends, encryption spec
+- `docs/decisions/adr-007-cli-conventions.md` — Flag naming, exit codes, output format standards
+
+</canonical_refs>
+
 <specifics>
 ## Specific Ideas
 
@@ -248,6 +287,15 @@ Organize existing photo library into structured folders. Handle duplicates and a
 
 </decisions>
 
+<canonical_refs>
+## Canonical References
+
+### Organization rules
+- `docs/features/photo-organization.md` — Grouping rules, duplicate policy, naming spec
+- `docs/decisions/adr-003-exif-handling.md` — EXIF extraction strategy, fallback for missing metadata
+
+</canonical_refs>
+
 <specifics>
 ## Specific Ideas
 
@@ -291,7 +339,14 @@ The output should answer: "What does the researcher need to investigate? What ch
 
 **After creation:**
 - File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
-- `gsd-phase-researcher` uses decisions to focus investigation
-- `gsd-planner` uses decisions + research to create executable tasks
+- `gsd-phase-researcher` uses decisions to focus investigation AND reads canonical_refs to know WHAT docs to study
+- `gsd-planner` uses decisions + research to create executable tasks AND reads canonical_refs to verify alignment
 - Downstream agents should NOT need to ask the user again about captured decisions
+
+**CRITICAL — Canonical references:**
+- The `<canonical_refs>` section is MANDATORY. Every CONTEXT.md must have one.
+- If your project has external specs, ADRs, or design docs, list them with full relative paths grouped by topic
+- If ROADMAP.md lists `Canonical refs:` per phase, extract and expand those
+- Inline mentions like "see ADR-019" scattered in decisions are useless to downstream agents — they need full paths and section references in a dedicated section they can find
+- If no external specs exist, say so explicitly — don't silently omit the section
 </guidelines>

package/get-shit-done/templates/dev-preferences.md

@@ -0,0 +1,21 @@
+---
+description: Load developer preferences into this session
+---
+
+# Developer Preferences
+
+> Generated by GSD on {{generated_at}} from {{data_source}}.
+> Run `/gsd-profile-user --refresh` to regenerate.
+
+## Behavioral Directives
+
+Follow these directives when working with this developer. Higher confidence
+directives should be applied directly. Lower confidence directives should be
+tried with hedging ("Based on your profile, I'll try X -- let me know if
+that's off").
+
+{{behavioral_directives}}
+
+## Stack Preferences
+
+{{stack_preferences}}

package/get-shit-done/templates/discussion-log.md

@@ -0,0 +1,63 @@
+# Discussion Log Template
+
+Template for `.planning/phases/XX-name/{phase_num}-DISCUSSION-LOG.md` — audit trail of discuss-phase Q&A sessions.
+
+**Purpose:** Software audit trail for decision-making. Captures all options considered, not just the selected one. Separate from CONTEXT.md which is the implementation artifact consumed by downstream agents.
+
+**NOT for LLM consumption.** This file should never be referenced in `<files_to_read>` blocks or agent prompts.
+
+## Format
+
+```markdown
+# Phase [X]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+## [Area 1 Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Brief description] | |
+| [Option 2] | [Brief description] | ✓ |
+| [Option 3] | [Brief description] | |
+
+**User's choice:** [Selected option or verbatim free-text response]
+**Notes:** [Any clarifications or rationale provided during discussion]
+
+---
+
+## [Area 2 Name]
+
+...
+
+---
+
+## OpenCode's Discretion
+
+[Areas delegated to OpenCode's judgment — list what was deferred and why]
+
+## Deferred Ideas
+
+[Ideas mentioned but not in scope for this phase]
+
+---
+
+*Phase: XX-name*
+*Discussion log generated: [date]*
+```
+
+## Rules
+
+- Generated automatically at end of every discuss-phase session
+- Includes ALL options considered, not just the selected one
+- Includes user's freeform notes and clarifications
+- Clearly marked as audit-only, not an implementation artifact
+- Does NOT interfere with CONTEXT.md generation or downstream agent behavior
+- Committed alongside CONTEXT.md in the same git commit

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

@@ -63,21 +63,29 @@ Output: [What artifacts will be created]
 <task type="auto">
   <name>task 1: [Action-oriented name]</name>
   <files>path/to/file.ext, another/file.ext</files>
-  <action>[Specific implementation - what to do, how to do it, what to avoid and WHY]</action>
+  <read_first>path/to/reference.ext, path/to/source-of-truth.ext</read_first>
+  <action>[Specific implementation - what to do, how to do it, what to avoid and WHY. Include CONCRETE values: exact identifiers, parameters, expected outputs, file paths, command arguments. Never say "align X with Y" without specifying the exact target state.]</action>
   <verify>[Command or check to prove it worked]</verify>
+  <acceptance_criteria>
+    - [grep-verifiable condition: "file.ext contains 'exact string'"]
+    - [Measurable condition: "output.ext uses 'expected-value', NOT 'wrong-value'"]
+  </acceptance_criteria>
   <done>[Measurable acceptance criteria]</done>
 </task>
 
 <task type="auto">
   <name>task 2: [Action-oriented name]</name>
   <files>path/to/file.ext</files>
-  <action>[Specific implementation]</action>
+  <read_first>path/to/reference.ext</read_first>
+  <action>[Specific implementation with concrete values]</action>
   <verify>[Command or check]</verify>
+  <acceptance_criteria>
+    - [grep-verifiable condition]
+  </acceptance_criteria>
   <done>[Acceptance criteria]</done>
 </task>
 
 <!-- For checkpoint task examples and patterns, see @$HOME/.config/opencode/get-shit-done/references/checkpoints.md -->
-<!-- Key rule: OpenCode starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
 
 <task type="checkpoint:decision" gate="blocking">
   <decision>[What needs deciding]</decision>
@@ -333,7 +341,7 @@ Output: User model, API endpoints, and UI components.
   <name>task 2: Create User API endpoints</name>
   <files>src/features/user/api.ts</files>
   <action>GET /users (list), GET /users/:id (single), POST /users (create). Use User type from model.</action>
-  <verify>curl tests pass for all endpoints</verify>
+  <verify>fetch tests pass for all endpoints</verify>
   <done>All CRUD operations work</done>
 </task>
 </tasks>
@@ -399,7 +407,7 @@ Output: Working dashboard component.
 <task type="auto">
   <name>Start dev server</name>
   <action>Run `npm run dev` in background, wait for ready</action>
-  <verify>curl localhost:3000 returns 200</verify>
+  <verify>fetch http://localhost:3000 returns 200</verify>
 </task>
 
 <task type="checkpoint:human-verify" gate="blocking">
@@ -456,6 +464,39 @@ files_modified: [...]
 </task>
 ```
 
+**Bad: Missing read_first (executor modifies files it hasn't read)**
+```xml
+<task type="auto">
+  <name>Update database config</name>
+  <files>src/config/database.ts</files>
+  <!-- No read_first! Executor doesn't know current state or conventions -->
+  <action>Update the database config to match production settings</action>
+</task>
+```
+
+**Bad: Vague acceptance criteria (not verifiable)**
+```xml
+<acceptance_criteria>
+  - Config is properly set up
+  - Database connection works correctly
+</acceptance_criteria>
+```
+
+**Good: Concrete with read_first + verifiable criteria**
+```xml
+<task type="auto">
+  <name>Update database config for connection pooling</name>
+  <files>src/config/database.ts</files>
+  <read_first>src/config/database.ts, .env.example, docker-compose.yml</read_first>
+  <action>Add pool configuration: min=2, max=20, idleTimeoutMs=30000. Add SSL config: rejectUnauthorized=true when NODE_ENV=production. Add .env.example entry: DATABASE_POOL_MAX=20.</action>
+  <acceptance_criteria>
+    - database.ts contains "max: 20" and "idleTimeoutMillis: 30000"
+    - database.ts contains SSL conditional on NODE_ENV
+    - .env.example contains DATABASE_POOL_MAX
+  </acceptance_criteria>
+</task>
+```
+
 ---
 
 ## Guidelines

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

@@ -127,6 +127,8 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 <evolution>
 
 PROJECT.md evolves throughout the project lifecycle.
+These rules are embedded in the generated PROJECT.md (## Evolution section)
+and implemented by workflows/transition.md and workflows/complete-milestone.md.
 
 **After each phase transition:**
 1. Requirements invalidated? → Move to Out of Scope with reason

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

@@ -73,7 +73,7 @@ Stopped at: [Description of last completed action]
 Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
 ```
 
-<purpose>
+<objective>
 
 STATE.md is the project's short-term memory spanning all phases and sessions.
 
@@ -85,7 +85,7 @@ STATE.md is the project's short-term memory spanning all phases and sessions.
 - Contains digest of accumulated context
 - Enables instant session restoration
 
-</purpose>
+</objective>
 
 <lifecycle>