gsd-remix 1.0.2 → 1.1.0

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

@@ -1,111 +0,0 @@
-# Workstream Flag (`--ws`)
-
-## Overview
-
-The `--ws <name>` flag scopes GSD operations to a specific workstream, enabling
-parallel milestone work by multiple Claude Code 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
-Claude/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-remix-sdk query commands accept --ws
-gsd-remix-sdk query state.json --ws feature-a
-gsd-remix-sdk query find-phase 3 --ws feature-b
-
-# Session-local switching without --ws on every command
-GSD_SESSION_KEY=my-terminal-a gsd-remix-sdk query workstream.set feature-a
-GSD_SESSION_KEY=my-terminal-a gsd-remix-sdk query state.json
-GSD_SESSION_KEY=my-terminal-b gsd-remix-sdk query workstream.set feature-b
-GSD_SESSION_KEY=my-terminal-b gsd-remix-sdk query state.json
-
-# Workstream CRUD
-gsd-remix-sdk query workstream.create <name>
-gsd-remix-sdk query workstream.list
-gsd-remix-sdk query workstream.status <name>
-gsd-remix-sdk query workstream.complete <name>
-```

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

@@ -1,246 +0,0 @@
-# AI-SPEC — Phase {N}: {phase_name}
-
-> AI design contract generated by `/gsd-ai-integration-phase`. Consumed by `gsd-planner` and `gsd-eval-auditor`.
-> Locks framework selection, implementation guidance, and evaluation strategy before planning begins.
-
----
-
-## 1. System Classification
-
-**System Type:** <!-- RAG | Multi-Agent | Conversational | Extraction | Autonomous Agent | Content Generation | Code Automation | Hybrid -->
-
-**Description:**
-<!-- One-paragraph description of what this AI system does, who uses it, and what "good" looks like -->
-
-**Critical Failure Modes:**
-<!-- The 3-5 behaviors that absolutely cannot go wrong in this system -->
-1.
-2.
-3.
-
----
-
-## 1b. Domain Context
-
-> Researched by `gsd-domain-researcher`. Grounds the evaluation strategy in domain expert knowledge.
-
-**Industry Vertical:** <!-- healthcare | legal | finance | customer service | education | developer tooling | e-commerce | etc. -->
-
-**User Population:** <!-- who uses this system and in what context -->
-
-**Stakes Level:** <!-- Low | Medium | High | Critical -->
-
-**Output Consequence:** <!-- what happens downstream when the AI output is acted on -->
-
-### What Domain Experts Evaluate Against
-
-<!-- Domain-specific rubric ingredients — in practitioner language, not AI jargon -->
-<!-- Format: Dimension / Good (expert accepts) / Bad (expert flags) / Stakes / Source -->
-
-### Known Failure Modes in This Domain
-
-<!-- Domain-specific failure modes from research — not generic hallucination, but how it manifests here -->
-
-### Regulatory / Compliance Context
-
-<!-- Relevant regulations or constraints — or "None identified" if genuinely none apply -->
-
-### Domain Expert Roles for Evaluation
-
-| Role | Responsibility |
-|------|---------------|
-| <!-- e.g., Senior practitioner --> | <!-- Dataset labeling / rubric calibration / production sampling --> |
-
----
-
-## 2. Framework Decision
-
-**Selected Framework:** <!-- e.g., LlamaIndex v0.10.x -->
-
-**Version:** <!-- Pin the version -->
-
-**Rationale:**
-<!-- Why this framework fits this system type, team context, and production requirements -->
-
-**Alternatives Considered:**
-
-| Framework | Ruled Out Because |
-|-----------|------------------|
-| | |
-
-**Vendor Lock-In Accepted:** <!-- Yes / No / Partial — document the trade-off consciously -->
-
----
-
-## 3. Framework Quick Reference
-
-> Fetched from official docs by `gsd-ai-researcher`. Distilled for this specific use case.
-
-### Installation
-```bash
-# Install command(s)
-```
-
-### Core Imports
-```python
-# Key imports for this use case
-```
-
-### Entry Point Pattern
-```python
-# Minimal working example for this system type
-```
-
-### Key Abstractions
-<!-- Framework-specific concepts the developer must understand before coding -->
-| Concept | What It Is | When You Use It |
-|---------|-----------|-----------------|
-| | | |
-
-### Common Pitfalls
-<!-- Gotchas specific to this framework and system type — from docs, issues, and community reports -->
-1.
-2.
-3.
-
-### Recommended Project Structure
-```
-project/
-├── # Framework-specific folder layout
-```
-
----
-
-## 4. Implementation Guidance
-
-**Model Configuration:**
-<!-- Which model(s), temperature, max tokens, and other key parameters -->
-
-**Core Pattern:**
-<!-- The primary implementation pattern for this system type in this framework -->
-
-**Tool Use:**
-<!-- Tools/integrations needed and how to configure them -->
-
-**State Management:**
-<!-- How state is persisted, retrieved, and updated -->
-
-**Context Window Strategy:**
-<!-- How to manage context limits for this system type -->
-
----
-
-## 4b. AI Systems Best Practices
-
-> Written by `gsd-ai-researcher`. Cross-cutting patterns every developer building AI systems needs — independent of framework choice.
-
-### Structured Outputs with Pydantic
-
-<!-- Framework-specific Pydantic integration pattern for this use case -->
-<!-- Include: output model definition, how the framework uses it, retry logic on validation failure -->
-
-```python
-# Pydantic output model for this system type
-```
-
-### Async-First Design
-
-<!-- How async is handled in this framework, the one common mistake, and when to stream vs. await -->
-
-### Prompt Engineering Discipline
-
-<!-- System vs. user prompt separation, few-shot guidance, token budget strategy -->
-
-### Context Window Management
-
-<!-- Strategy specific to this system type: RAG chunking / conversation summarisation / agent compaction -->
-
-### Cost and Latency Budget
-
-<!-- Per-call cost estimate, caching strategy, sub-task model routing -->
-
----
-
-## 5. Evaluation Strategy
-
-### Dimensions
-
-| Dimension | Rubric (Pass/Fail or 1-5) | Measurement Approach | Priority |
-|-----------|--------------------------|---------------------|----------|
-| | | Code / LLM Judge / Human | Critical / High / Medium |
-
-### Eval Tooling
-
-**Primary Tool:** <!-- e.g., RAGAS + Langfuse -->
-
-**Setup:**
-```bash
-# Install and configure
-```
-
-**CI/CD Integration:**
-```bash
-# Command to run evals in CI/CD pipeline
-```
-
-### Reference Dataset
-
-**Size:** <!-- e.g., 20 examples to start -->
-
-**Composition:**
-<!-- What scenario types the dataset covers: critical paths, edge cases, failure modes -->
-
-**Labeling:**
-<!-- Who labels examples and how (domain expert, LLM judge with calibration, etc.) -->
-
----
-
-## 6. Guardrails
-
-### Online (Real-Time)
-
-| Guardrail | Trigger | Intervention |
-|-----------|---------|--------------|
-| | | Block / Escalate / Flag |
-
-### Offline (Flywheel)
-
-| Metric | Sampling Strategy | Action on Degradation |
-|--------|------------------|----------------------|
-| | | |
-
----
-
-## 7. Production Monitoring
-
-**Tracing Tool:** <!-- e.g., Langfuse self-hosted -->
-
-**Key Metrics to Track:**
-<!-- 3-5 metrics that will be monitored in production -->
-
-**Alert Thresholds:**
-<!-- When to page/alert -->
-
-**Smart Sampling Strategy:**
-<!-- How to select interactions for human review — signal-based filters -->
-
----
-
-## Checklist
-
-- [ ] System type classified
-- [ ] Critical failure modes identified (≥ 3)
-- [ ] Domain context researched (Section 1b: vertical, stakes, expert criteria, failure modes)
-- [ ] Regulatory/compliance context identified or explicitly noted as none
-- [ ] Domain expert roles defined for evaluation involvement
-- [ ] Framework selected with rationale documented
-- [ ] Alternatives considered and ruled out
-- [ ] Framework quick reference written (install, imports, pattern, pitfalls)
-- [ ] AI systems best practices written (Section 4b: Pydantic, async, prompt discipline, context)
-- [ ] Evaluation dimensions grounded in domain rubric ingredients
-- [ ] Each eval dimension has a concrete rubric (Good/Bad in domain language)
-- [ ] Eval tooling selected — Arize Phoenix default confirmed or override noted
-- [ ] Reference dataset spec written (size ≥ 10, composition + labeling defined)
-- [ ] CI/CD eval integration specified
-- [ ] Online guardrails defined
-- [ ] Production monitoring configured (tracing tool + sampling strategy)

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

@@ -1,61 +0,0 @@
----
-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/UI-SPEC.md

@@ -1,100 +0,0 @@
----
-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

@@ -1,76 +0,0 @@
----
-phase: {N}
-slug: {phase-slug}
-status: draft
-nyquist_compliant: false
-wave_0_complete: false
-created: {date}
----
-
-# Phase {N} — Validation Strategy
-
-> Per-phase validation contract for feedback sampling during execution.
-
----
-
-## Test Infrastructure
-
-| Property | Value |
-|----------|-------|
-| **Framework** | {pytest 7.x / jest 29.x / vitest / go test / other} |
-| **Config file** | {path or "none — Wave 0 installs"} |
-| **Quick run command** | `{quick command}` |
-| **Full suite command** | `{full command}` |
-| **Estimated runtime** | ~{N} seconds |
-
----
-
-## Sampling Rate
-
-- **After every task commit:** Run `{quick run command}`
-- **After every plan wave:** Run `{full suite command}`
-- **Before `/gsd-verify-work`:** Full suite must be green
-- **Max feedback latency:** {N} seconds
-
----
-
-## Per-Task Verification Map
-
-| 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*
-
----
-
-## Wave 0 Requirements
-
-- [ ] `{tests/test_file.py}` — stubs for REQ-{XX}
-- [ ] `{tests/conftest.py}` — shared fixtures
-- [ ] `{framework install}` — if no framework detected
-
-*If none: "Existing infrastructure covers all phase requirements."*
-
----
-
-## Manual-Only Verifications
-
-| Behavior | Requirement | Why Manual | Test Instructions |
-|----------|-------------|------------|-------------------|
-| {behavior} | REQ-{XX} | {reason} | {steps} |
-
-*If none: "All phase behaviors have automated verification."*
-
----
-
-## Validation Sign-Off
-
-- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
-- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
-- [ ] Wave 0 covers all MISSING references
-- [ ] No watch-mode flags
-- [ ] Feedback latency < {N}s
-- [ ] `nyquist_compliant: true` set in frontmatter
-
-**Approval:** {pending / approved YYYY-MM-DD}

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

@@ -1,21 +0,0 @@
----
-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}}