gsd-opencode 1.22.1 → 1.33.0

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

@@ -0,0 +1,111 @@
+# 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. Session-scoped active workstream pointer in temp storage (per runtime session / terminal)
+4. `.planning/active-workstream` file (legacy shared fallback when no session key exists)
+5. `null` — flat mode (no workstreams)
+
+## Why session-scoped pointers exist
+
+The shared `.planning/active-workstream` file is fundamentally unsafe when multiple
+OpenCode/Codex instances are active on the same repo at the same time. One session can
+silently repoint another session's `STATE.md`, `ROADMAP.md`, and phase paths.
+
+GSD now prefers a session-scoped pointer keyed by runtime/session identity
+(`GSD_SESSION_KEY`, `CODEX_THREAD_ID`, `CLAUDE_CODE_SSE_PORT`, terminal session IDs,
+or the controlling TTY). This keeps concurrent sessions isolated while preserving
+legacy compatibility for runtimes that do not expose a stable session key.
+
+## Session Identity Resolution
+
+When GSD resolves the session-scoped pointer in step 3 above, it uses this order:
+
+1. Explicit runtime/session env vars such as `GSD_SESSION_KEY`, `CODEX_THREAD_ID`,
+   `CLAUDE_SESSION_ID`, `CLAUDE_CODE_SSE_PORT`, `OPENCODE_SESSION_ID`,
+   `GEMINI_SESSION_ID`, `CURSOR_SESSION_ID`, `WINDSURF_SESSION_ID`,
+   `TERM_SESSION_ID`, `WT_SESSION`, `TMUX_PANE`, and `ZELLIJ_SESSION_NAME`
+2. `TTY` or `SSH_TTY` if the shell/runtime already exposes the terminal path
+3. A single best-effort `tty` probe, but only when stdin is interactive
+
+If none of those produce a stable identity, GSD does not keep probing. It falls
+back directly to the legacy shared `.planning/active-workstream` file.
+
+This matters in headless or stripped environments: when stdin is already
+non-interactive, GSD intentionally skips shelling out to `tty` because that path
+cannot discover a stable session identity and only adds avoidable failures on the
+routing hot path.
+
+## Pointer Lifecycle
+
+Session-scoped pointers are intentionally lightweight and best-effort:
+
+- Clearing a workstream for one session removes only that session's pointer file
+- If that was the last pointer for the repo, GSD also removes the now-empty
+  per-project temp directory
+- If sibling session pointers still exist, the temp directory is left in place
+- When a pointer refers to a workstream directory that no longer exists, GSD
+  treats it as stale state: it removes that pointer file and resolves to `null`
+  until the session explicitly sets a new active workstream again
+
+GSD does not currently run a background garbage collector for historical temp
+directories. Cleanup is opportunistic at the pointer being cleared or self-healed,
+and broader temp hygiene is left to OS temp cleanup or future maintenance work.
+
+## 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   # Legacy shared fallback only
+└── 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
+
+# Session-local switching without --ws on every command
+GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs workstream set feature-a
+GSD_SESSION_KEY=my-terminal-a node gsd-tools.cjs state json
+GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs workstream set feature-b
+GSD_SESSION_KEY=my-terminal-b node gsd-tools.cjs state json
+
+# 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/SECURITY.md

@@ -0,0 +1,61 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+threats_open: 0
+asvs_level: 1
+created: {date}
+---
+
+# Phase {N} — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| {boundary} | {description} | {data type / sensitivity} |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-{N}-01 | {STRIDE category} | {component} | {mitigate / accept / transfer} | {control or reference} | open |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+
+*Accepted risks do not resurface in future audit runs.*
+
+*If none: "No accepted risks."*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| {YYYY-MM-DD} | {N} | {N} | {N} | {name / agent} |
+
+---
+
+## Sign-Off
+
+- [ ] All threats have a disposition (mitigate / accept / transfer)
+- [ ] Accepted risks documented in Accepted Risks Log
+- [ ] `threats_open: 0` confirmed
+- [ ] `status: verified` set in frontmatter
+
+**Approval:** {pending / verified YYYY-MM-DD}

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/VALIDATION.md

@@ -36,9 +36,9 @@ created: {date}
 
 ## Per-task Verification Map
 
-| task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
-|---------|------|------|-------------|-----------|-------------------|-------------|--------|
-| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
+| task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | T-{N}-01 / — | {expected secure behavior or "N/A"} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
 
 *Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
 

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

@@ -0,0 +1,145 @@
+# AGENTS.md Template
+
+Template for project-root `AGENTS.md` — auto-generated by `gsd-tools generate-OpenCode-md`.
+
+Contains 7 marker-bounded sections. Each section is independently updatable.
+The `generate-OpenCode-md` subcommand manages 6 sections (project, stack, conventions, architecture, skills, 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.
+```
+
+### Skills Section
+```
+<!-- GSD:skills-start source:skills/ -->
+## Project Skills
+
+| skill          | Description           | Path                      |
+| -------------- | --------------------- | ------------------------- |
+| {{skill_name}} | {{skill_description}} | `{{skill_path}}/SKILL.md` |
+<!-- GSD:skills-end -->
+```
+
+**Fallback text:**
+```
+No project skills found. Add skills to any of: `.OpenCode/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.
+```
+
+**Discovery behavior:**
+- Scans `.OpenCode/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/` for subdirectories containing `SKILL.md`
+- Extracts `name` and `description` from YAML frontmatter (supports multi-line descriptions)
+- Skips GSD's own installed skills (directories starting with `gsd-`)
+- Deduplicates by skill name across directories
+
+### 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. **Skills** — Discovered project skills with name and description (what domain knowledge is available)
+6. **Workflow Enforcement** — Default GSD entry points for file-changing work
+7. **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,17 @@
     "plan_check": true,
     "verifier": true,
     "auto_advance": false,
-    "nyquist_validation": true
+    "nyquist_validation": true,
+    "security_enforcement": true,
+    "security_asvs_level": 1,
+    "security_block_on": "high",
+    "discuss_mode": "discuss",
+    "research_before_questions": false
   },
   "planning": {
     "commit_docs": true,
-    "search_gitignored": false
+    "search_gitignored": false,
+    "sub_repos": []
   },
   "parallelization": {
     "enabled": true,
@@ -33,5 +39,10 @@
   "safety": {
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
-  }
+  },
+  "hooks": {
+    "context_warnings": true
+  },
+  "project_code": null,
+  "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/debug-subagent-prompt.md

@@ -53,16 +53,12 @@ Create: .planning/debug/{slug}.md
 
 **From /gsd-debug:**
 ```python
-task(
-  prompt=filled_template,
-  subagent_type="gsd-debugger",
-  description="Debug {slug}"
-)
+@gsd-debugger filled_template
 ```
 
 **From diagnose-issues (UAT):**
 ```python
-task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")
+@gsd-debugger template
 ```
 
 ---

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}}