mirror of
https://github.com/glittercowboy/get-shit-done
synced 2026-04-25 17:25:23 +02:00
docs: update release notes and command reference for v1.37.0 (#2382)
* fix(tests): clear CLAUDECODE env var in read-guard test runner The hook skips its advisory on two env vars: CLAUDE_SESSION_ID and CLAUDECODE. runHook() cleared CLAUDE_SESSION_ID but inherited CLAUDECODE from process.env, so tests run inside a Claude Code session silently no-oped and produced no stdout, causing JSON.parse to throw. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(ci): update ARCHITECTURE.md counts and add TEXT_MODE fallback to sketch workflow Four new spike/sketch files were added in 1.37.0 but two housekeeping items were missed: ARCHITECTURE.md component counts (75→79 commands, 72→76 workflows) and the required TEXT_MODE fallback in sketch.md for non-Claude runtimes (#2012). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(ci): update directory-tree slash command count in ARCHITECTURE.md Missed the second count in the directory tree (# 75 slash commands → 79). The prose "Total commands" was updated but the tree annotation was not, causing command-count-sync.test.cjs to fail. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: update release notes and command reference for v1.37.0 Covers spike/sketch commands, agent size-budget enforcement, and shared boilerplate extraction across README, COMMANDS, FEATURES, and USER-GUIDE. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
11
README.md
11
README.md
@@ -89,14 +89,11 @@ People who want to describe what they want and have it built correctly — witho
|
||||
|
||||
Built-in quality gates catch real problems: schema drift detection flags ORM changes missing migrations, security enforcement anchors verification to threat models, and scope reduction detection prevents the planner from silently dropping your requirements.
|
||||
|
||||
### v1.36.0 Highlights
|
||||
### v1.37.0 Highlights
|
||||
|
||||
- **Knowledge graph integration** — `/gsd-graphify` brings knowledge graphs to planning agents for richer context connections
|
||||
- **SDK typed query foundation** — Registry-based `gsd-sdk query` command with classified errors and handlers for state, roadmap, phase lifecycle, and config
|
||||
- **TDD pipeline mode** — Opt-in test-driven development workflow with `--tdd` flag
|
||||
- **Context-window-aware prompt thinning** — Automatic prompt size reduction for sub-200K models
|
||||
- **Project skills awareness** — 9 GSD agents now discover and use project-scoped skills
|
||||
- **30+ bug fixes** — Worktree safety, state management, installer paths, and health check optimizations
|
||||
- **Spiking & sketching** — `/gsd-spike` runs 2–5 focused experiments with Given/When/Then verdicts; `/gsd-sketch` produces 2–3 interactive HTML mockup variants per design question — both store artifacts in `.planning/` and pair with wrap-up commands to package findings into project-local skills
|
||||
- **Agent size-budget enforcement** — Tiered line-count limits (XL: 1 600, Large: 1 000, Default: 500) keep agent prompts lean; violations surface in CI
|
||||
- **Shared boilerplate extraction** — Mandatory-initial-read and project-skills-discovery logic extracted to reference files, reducing duplication across a dozen agents
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -806,6 +806,74 @@ Archive accumulated phase directories from completed milestones.
|
||||
|
||||
---
|
||||
|
||||
## Spiking & Sketching Commands
|
||||
|
||||
### `/gsd-spike`
|
||||
|
||||
Run 2–5 focused feasibility experiments before committing to an implementation approach. Each experiment uses Given/When/Then framing, produces executable code, and returns a VALIDATED / INVALIDATED / PARTIAL verdict.
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `idea` | No | The technical question or approach to investigate |
|
||||
| `--quick` | No | Skip intake conversation; use `idea` text directly |
|
||||
|
||||
**Produces:** `.planning/spikes/NNN-experiment-name/` with code, results, and README; `.planning/spikes/MANIFEST.md`
|
||||
|
||||
```bash
|
||||
/gsd-spike # Interactive intake
|
||||
/gsd-spike "can we stream LLM tokens through SSE"
|
||||
/gsd-spike --quick websocket-vs-polling
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-spike-wrap-up`
|
||||
|
||||
Package completed spike findings into a reusable project-local skill so future sessions can reference the conclusions.
|
||||
|
||||
**Prerequisites:** `.planning/spikes/` exists with at least one completed spike
|
||||
**Produces:** `.claude/skills/spike-findings-[project]/` skill file
|
||||
|
||||
```bash
|
||||
/gsd-spike-wrap-up
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-sketch`
|
||||
|
||||
Explore design directions through throwaway HTML mockups before committing to implementation. Produces 2–3 variants per design question for direct browser comparison.
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `idea` | No | The UI design question or direction to explore |
|
||||
| `--quick` | No | Skip mood intake; use `idea` text directly |
|
||||
| `--text` | No | Text-mode fallback — replace interactive prompts with numbered lists (for non-Claude runtimes) |
|
||||
|
||||
**Produces:** `.planning/sketches/NNN-descriptive-name/index.html` (2–3 interactive variants), `README.md`, shared `themes/default.css`; `.planning/sketches/MANIFEST.md`
|
||||
|
||||
```bash
|
||||
/gsd-sketch # Interactive mood intake
|
||||
/gsd-sketch "dashboard layout"
|
||||
/gsd-sketch --quick "sidebar navigation"
|
||||
/gsd-sketch --text "onboarding flow" # Non-Claude runtime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/gsd-sketch-wrap-up`
|
||||
|
||||
Package winning sketch decisions into a reusable project-local skill so future sessions inherit the visual direction.
|
||||
|
||||
**Prerequisites:** `.planning/sketches/` exists with at least one completed sketch (winner marked)
|
||||
**Produces:** `.claude/skills/sketch-findings-[project]/` skill file
|
||||
|
||||
```bash
|
||||
/gsd-sketch-wrap-up
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostics Commands
|
||||
|
||||
### `/gsd-forensics`
|
||||
|
||||
@@ -116,6 +116,11 @@
|
||||
- [SDK Workstream Support](#113-sdk-workstream-support)
|
||||
- [Context-Window-Aware Prompt Thinning](#114-context-window-aware-prompt-thinning)
|
||||
- [Configurable CLAUDE.md Path](#115-configurable-claudemd-path)
|
||||
- [v1.37.0 Features](#v1370-features)
|
||||
- [Spike Command](#117-spike-command)
|
||||
- [Sketch Command](#118-sketch-command)
|
||||
- [Agent Size-Budget Enforcement](#119-agent-size-budget-enforcement)
|
||||
- [Shared Boilerplate Extraction](#120-shared-boilerplate-extraction)
|
||||
- [v1.32 Features](#v132-features)
|
||||
- [STATE.md Consistency Gates](#69-statemd-consistency-gates)
|
||||
- [Autonomous `--to N` Flag](#70-autonomous---to-n-flag)
|
||||
@@ -2423,3 +2428,82 @@ Test suite that scans all agent, workflow, and command files for embedded inject
|
||||
|
||||
**Configuration:** `workflow.tdd_mode`
|
||||
**Reference files:** `tdd.md`, `checkpoints.md`
|
||||
|
||||
---
|
||||
|
||||
## v1.37.0 Features
|
||||
|
||||
### 117. Spike Command
|
||||
|
||||
**Command:** `/gsd-spike [idea] [--quick]`
|
||||
|
||||
**Purpose:** Run 2–5 focused feasibility experiments before committing to an implementation approach. Each experiment uses Given/When/Then framing, produces executable code, and returns a VALIDATED / INVALIDATED / PARTIAL verdict. Companion `/gsd-spike-wrap-up` packages findings into a project-local skill.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SPIKE-01: Each experiment MUST produce a Given/When/Then hypothesis before any code is written
|
||||
- REQ-SPIKE-02: Each experiment MUST include working code or a minimal reproduction
|
||||
- REQ-SPIKE-03: Each experiment MUST return one of: VALIDATED, INVALIDATED, or PARTIAL verdict with evidence
|
||||
- REQ-SPIKE-04: Results MUST be stored in `.planning/spikes/NNN-experiment-name/` with a README and MANIFEST.md
|
||||
- REQ-SPIKE-05: `--quick` flag skips intake conversation and uses the argument text as the experiment direction
|
||||
- REQ-SPIKE-06: `/gsd-spike-wrap-up` MUST package findings into `.claude/skills/spike-findings-[project]/`
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `.planning/spikes/NNN-name/README.md` | Hypothesis, experiment code, verdict, and evidence |
|
||||
| `.planning/spikes/MANIFEST.md` | Index of all spikes with verdicts |
|
||||
| `.claude/skills/spike-findings-[project]/` | Packaged findings (via `/gsd-spike-wrap-up`) |
|
||||
|
||||
---
|
||||
|
||||
### 118. Sketch Command
|
||||
|
||||
**Command:** `/gsd-sketch [idea] [--quick] [--text]`
|
||||
|
||||
**Purpose:** Explore design directions through throwaway HTML mockups before committing to implementation. Produces 2–3 interactive variants per design question, all viewable directly in a browser with no build step. Companion `/gsd-sketch-wrap-up` packages winning decisions into a project-local skill.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-SKETCH-01: Each sketch MUST answer one specific visual design question
|
||||
- REQ-SKETCH-02: Each sketch MUST include 2–3 meaningfully different variants in a single `index.html` with tab navigation
|
||||
- REQ-SKETCH-03: All interactive elements (hover, click, transitions) MUST be functional
|
||||
- REQ-SKETCH-04: Sketches MUST use real-ish content, not lorem ipsum
|
||||
- REQ-SKETCH-05: A shared `themes/default.css` MUST provide CSS variables adapted to the agreed aesthetic
|
||||
- REQ-SKETCH-06: `--quick` flag skips mood intake; `--text` flag replaces `AskUserQuestion` with numbered lists for non-Claude runtimes
|
||||
- REQ-SKETCH-07: The winning variant MUST be marked in the README frontmatter and with a ★ in the HTML tab
|
||||
- REQ-SKETCH-08: `/gsd-sketch-wrap-up` MUST package winning decisions into `.claude/skills/sketch-findings-[project]/`
|
||||
|
||||
**Produces:**
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `.planning/sketches/NNN-name/index.html` | 2–3 interactive HTML variants |
|
||||
| `.planning/sketches/NNN-name/README.md` | Design question, variants, winner, what to look for |
|
||||
| `.planning/sketches/themes/default.css` | Shared CSS theme variables |
|
||||
| `.planning/sketches/MANIFEST.md` | Index of all sketches with winners |
|
||||
| `.claude/skills/sketch-findings-[project]/` | Packaged decisions (via `/gsd-sketch-wrap-up`) |
|
||||
|
||||
---
|
||||
|
||||
### 119. Agent Size-Budget Enforcement
|
||||
|
||||
**Purpose:** Keep agent prompt files lean with tiered line-count limits enforced in CI. Oversized agents are caught before they bloat context windows in production.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-BUDGET-01: `agents/gsd-*.md` files are classified into three tiers: XL (≤ 1 600 lines), Large (≤ 1 000 lines), Default (≤ 500 lines)
|
||||
- REQ-BUDGET-02: Tier assignment is declared in the file's YAML frontmatter (`size: xl | large | default`)
|
||||
- REQ-BUDGET-03: `tests/agent-size-budget.test.cjs` enforces limits and fails CI on violation
|
||||
- REQ-BUDGET-04: Files without a `size` frontmatter key default to the Default (500-line) limit
|
||||
|
||||
**Test file:** `tests/agent-size-budget.test.cjs`
|
||||
|
||||
---
|
||||
|
||||
### 120. Shared Boilerplate Extraction
|
||||
|
||||
**Purpose:** Reduce duplication across agents by extracting two common boilerplate blocks into shared reference files loaded on demand. Keeps agent files within size budget and makes boilerplate updates a single-file change.
|
||||
|
||||
**Requirements:**
|
||||
- REQ-BOILER-01: Mandatory-initial-read instructions extracted to `references/mandatory-initial-read.md`
|
||||
- REQ-BOILER-02: Project-skills-discovery instructions extracted to `references/project-skills-discovery.md`
|
||||
- REQ-BOILER-03: Agents that previously inlined these blocks MUST now reference them via `@` required_reading
|
||||
|
||||
**Reference files:** `references/mandatory-initial-read.md`, `references/project-skills-discovery.md`
|
||||
|
||||
@@ -8,6 +8,7 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic
|
||||
|
||||
- [Workflow Diagrams](#workflow-diagrams)
|
||||
- [UI Design Contract](#ui-design-contract)
|
||||
- [Spiking & Sketching](#spiking--sketching)
|
||||
- [Backlog & Threads](#backlog--threads)
|
||||
- [Workstreams](#workstreams)
|
||||
- [Security](#security)
|
||||
@@ -259,6 +260,59 @@ Controlled by `workflow.ui_safety_gate` config toggle.
|
||||
|
||||
---
|
||||
|
||||
## Spiking & Sketching
|
||||
|
||||
Use `/gsd-spike` to validate technical feasibility before planning, and `/gsd-sketch` to explore visual direction before designing. Both store artifacts in `.planning/` and integrate with the project-skills system via their wrap-up companions.
|
||||
|
||||
### When to Spike
|
||||
|
||||
Spike when you're uncertain whether a technical approach is feasible or want to compare two implementations before committing a phase to one of them.
|
||||
|
||||
```
|
||||
/gsd-spike # Interactive intake — describes the question, you confirm
|
||||
/gsd-spike "can we stream LLM tokens through SSE"
|
||||
/gsd-spike --quick "websocket vs SSE latency"
|
||||
```
|
||||
|
||||
Each spike runs 2–5 experiments. Every experiment has:
|
||||
- A **Given / When / Then** hypothesis written before any code
|
||||
- **Working code** (not pseudocode)
|
||||
- A **VALIDATED / INVALIDATED / PARTIAL** verdict with evidence
|
||||
|
||||
Results land in `.planning/spikes/NNN-name/README.md` and are indexed in `.planning/spikes/MANIFEST.md`.
|
||||
|
||||
Once you have signal, run `/gsd-spike-wrap-up` to package the findings into `.claude/skills/spike-findings-[project]/` — future sessions will load them automatically via project-skills discovery.
|
||||
|
||||
### When to Sketch
|
||||
|
||||
Sketch when you need to compare layout structures, interaction models, or visual treatments before writing any real component code.
|
||||
|
||||
```
|
||||
/gsd-sketch # Mood intake — explores feel, references, core action
|
||||
/gsd-sketch "dashboard layout"
|
||||
/gsd-sketch --quick "sidebar navigation"
|
||||
/gsd-sketch --text "onboarding flow" # For non-Claude runtimes (Codex, Gemini, etc.)
|
||||
```
|
||||
|
||||
Each sketch answers **one design question** with 2–3 variants in a single `index.html` you open directly in a browser — no build step. Variants use tab navigation and shared CSS variables from `themes/default.css`. All interactive elements (hover, click, transitions) are functional.
|
||||
|
||||
After picking a winner, run `/gsd-sketch-wrap-up` to capture the visual decisions into `.claude/skills/sketch-findings-[project]/`.
|
||||
|
||||
### Spike → Sketch → Phase Flow
|
||||
|
||||
```
|
||||
/gsd-spike "SSE vs WebSocket" # Validate the approach
|
||||
/gsd-spike-wrap-up # Package learnings
|
||||
|
||||
/gsd-sketch "real-time feed UI" # Explore the design
|
||||
/gsd-sketch-wrap-up # Package decisions
|
||||
|
||||
/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
|
||||
/gsd-plan-phase N # Plan with confidence
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backlog & Threads
|
||||
|
||||
### Backlog Parking Lot
|
||||
@@ -1108,6 +1162,14 @@ For reference, here is what GSD creates in your project:
|
||||
done/ # Completed todos
|
||||
debug/ # Active debug sessions
|
||||
resolved/ # Archived debug sessions
|
||||
spikes/ # Feasibility experiments (from /gsd-spike)
|
||||
NNN-name/ # Experiment code + README with verdict
|
||||
MANIFEST.md # Index of all spikes
|
||||
sketches/ # HTML mockups (from /gsd-sketch)
|
||||
NNN-name/ # index.html (2-3 variants) + README
|
||||
themes/
|
||||
default.css # Shared CSS variables for all sketches
|
||||
MANIFEST.md # Index of all sketches with winners
|
||||
codebase/ # Brownfield codebase mapping (from /gsd-map-codebase)
|
||||
phases/
|
||||
XX-phase-name/
|
||||
|
||||
Reference in New Issue
Block a user