diff --git a/README.md b/README.md index 31faae65..56e2dccc 100644 --- a/README.md +++ b/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 --- diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index b34ac49d..d3f0bd8d 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -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` diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 620930f5..1cc7676e 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -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` diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index a8d9949c..9a9e1a95 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.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/