From 71a3f86fbe0a6d2356fd6a084130570413617178 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Sun, 26 Apr 2026 13:33:47 -0400 Subject: [PATCH] docs: add end-to-end workflow walkthrough to USER-GUIDE.md (#2749) Adds a concrete single-phase walkthrough (webhook validator project) showing ROADMAP.md, CONTEXT.md, PLAN.md, SUMMARY.md, and STATE.md excerpts and how each command consumes the previous step's output. Also adds links to the walkthrough from README.md's nav bar and How It Works section. Closes #2359 Co-authored-by: Claude Sonnet 4.6 --- README.md | 4 +- docs/USER-GUIDE.md | 236 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 904e1e4c4..03e606f63 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ npx get-shit-done-cc@latest **Trusted by engineers at Amazon, Google, Shopify, and Webflow.** -[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md) +[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md) · [Walkthrough](docs/USER-GUIDE.md#end-to-end-walkthrough) @@ -263,6 +263,8 @@ If you prefer not to use that flag, add this to your project's `.claude/settings ## How It Works +> **New to GSD?** See the [end-to-end walkthrough](docs/USER-GUIDE.md#end-to-end-walkthrough) in the User Guide — it shows a complete project from `/gsd-new-project` through `/gsd-verify-work` with concrete example outputs. + > **Already have code?** Run `/gsd-map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/gsd-new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns. ### 1. Initialize Project diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index c09146f9f..ad3d6ae36 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -6,6 +6,7 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic ## Table of Contents +- [End-to-End Walkthrough](#end-to-end-walkthrough) - [Workflow Diagrams](#workflow-diagrams) - [UI Design Contract](#ui-design-contract) - [Spiking & Sketching](#spiking--sketching) @@ -19,6 +20,241 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic --- +## End-to-End Walkthrough + +This walkthrough shows how GSD phases connect for a typical single-phase project — a small Node.js REST API that validates webhook signatures. Follow it to understand what each command does, what it creates, and how the next command consumes it. + +### 1. Create the project + +``` +/gsd-new-project +``` + +GSD asks questions about your idea, spawns parallel research agents, extracts requirements, and creates a roadmap. You approve the roadmap before any code is written. + +**Example output (abridged):** + +``` +> What are you building? + A webhook signature validator middleware for Express apps. + +> Who's the user? + Backend developers integrating third-party webhooks (Stripe, GitHub, Shopify). + +[Research agents run in parallel...] +[Requirements extracted...] + +Roadmap (1 phase): + Phase 1 — Core middleware: HMAC-SHA256 signature validation, + timing-safe compare, configurable tolerance window. + +Approve? [y/n] +``` + +**What gets created:** + +``` +.planning/ + PROJECT.md # "Webhook validator middleware — Express, HMAC-SHA256..." + REQUIREMENTS.md # REQ-001: Validate signature header; REQ-002: Timing-safe... + ROADMAP.md # Phase 1 status: pending + STATE.md # Session memory, current position +``` + +`ROADMAP.md` excerpt: +```markdown +## Phase 1 — Core middleware +**Status:** pending +**Goal:** HMAC-SHA256 signature validation with timing-safe compare and a +configurable replay-protection tolerance window. +**Requirements:** REQ-001, REQ-002, REQ-003 +``` + +### 2. Discuss and plan the phase + +``` +/gsd-discuss-phase 1 +``` + +GSD reads the phase goal and asks about your implementation preferences before any planning happens. This is where you shape *how* it builds — not just *what* it builds. + +``` +> How should invalid signatures be handled? + Reject immediately with 401, log the raw header for debugging. + +> Should the tolerance window be configurable per-route or global? + Global config, but allow per-route override via middleware options. + +> Any library preferences for HMAC? + Node built-in crypto only — no extra dependencies. +``` + +**What gets created:** `.planning/phases/01-core-middleware/CONTEXT.md` + +`CONTEXT.md` excerpt: +```markdown +## Implementation Decisions +- Invalid signatures → 401, log raw header +- Tolerance window → global default, per-route override via options object +- HMAC library → Node built-in crypto (no external deps) +- Error format → { error: "invalid_signature", ts: } +``` + +Now plan the phase: + +``` +/gsd-plan-phase 1 +``` + +GSD spawns four parallel research agents (stack, features, architecture, pitfalls), then a planner reads `CONTEXT.md` + research findings and creates atomic task plans. A plan-checker verifies each plan achieves the phase goal before saving. + +**What gets created:** + +``` +.planning/phases/01-core-middleware/ + RESEARCH.md # Findings: crypto.timingSafeEqual docs, replay attack patterns... + 01-01-PLAN.md # Task: create validateSignature() core function + 01-02-PLAN.md # Task: Express middleware wrapper + error handling +``` + +`01-01-PLAN.md` excerpt: +```xml + + Create validateSignature core function + src/validate.js, src/validate.test.js + + Use crypto.createHmac('sha256', secret).update(rawBody).digest('hex'). + Compare with crypto.timingSafeEqual() — never === or ==. + Accept tolerance window in ms; reject if |timestamp - now| exceeds it. + + npm test -- --grep "validateSignature" + All timing-safe comparison tests pass; replay outside window returns false + +``` + +### 3. Execute + +``` +/gsd-execute-phase 1 +``` + +GSD groups plans into waves (parallel where independent, sequential where dependent), spawns a fresh 200k-context executor per plan, and commits each task atomically. + +``` +Wave 1 (parallel): + [Executor A] → 01-01-PLAN.md (core function) ✓ committed + [Executor B] → 01-02-PLAN.md (middleware) ✓ committed + +[Verifier] Checking codebase against phase goals... + REQ-001 validateSignature() ✓ + REQ-002 timing-safe compare ✓ + REQ-003 tolerance window ✓ + Status: PASS +``` + +**Git history after execution:** + +``` +a1b2c3d feat(01-01): implement validateSignature with timingSafeEqual +d4e5f6g feat(01-02): add Express middleware wrapper and 401 error format +h7i8j9k chore(01): phase 1 verification — all requirements met +``` + +**What gets created:** + +``` +.planning/phases/01-core-middleware/ + 01-01-SUMMARY.md # "Implemented validateSignature(), 47 lines, tests passing" + 01-02-SUMMARY.md # "Middleware wraps validator, logs raw header on 401" + VERIFICATION.md # REQ-001 ✓, REQ-002 ✓, REQ-003 ✓ — PASS +``` + +`STATE.md` is updated automatically to reflect the new phase status: + +```markdown +## Current Position +Phase 1 — Core middleware: executed, pending verify +``` + +### 4. Verify + +``` +/gsd-verify-work 1 +``` + +GSD extracts testable deliverables from the phase goal and walks you through them one at a time. + +``` +[1/3] Can you require the middleware and pass it to an Express route? +> yes + +[2/3] Does a request with a valid signature return 200? +> yes + +[3/3] Does a request with an invalid signature return 401 with { error: "invalid_signature" }? +> no — I'm getting a 500 instead + +[Diagnosing...] +Root cause: middleware catches crypto.timingSafeEqual TypeError when +buffers are different lengths. Fix: normalize to same length before compare. + +Fix plan created: .planning/phases/01-core-middleware/01-03-PLAN.md +Run /gsd-execute-phase 1 to apply. +``` + +After re-running execute and re-verifying: + +``` +All 3 checks passed. Phase 1 verified. +``` + +**What gets created:** `.planning/phases/01-core-middleware/UAT.md` + +### What's next + +Once a phase is verified, ship it: + +``` +/gsd-ship 1 # Creates a PR with auto-generated body +``` + +For multi-phase projects, repeat the loop: + +``` +/gsd-discuss-phase 2 +/gsd-plan-phase 2 +/gsd-execute-phase 2 +/gsd-verify-work 2 +``` + +Or let GSD figure out the next step automatically: + +``` +/gsd-next +``` + +When all phases are done: + +``` +/gsd-audit-milestone # Verify all requirements shipped +/gsd-complete-milestone # Archive, tag release +``` + +**Relevant flags covered in this walkthrough:** + +| Flag | Command | When to use | +| ---- | ------- | ----------- | +| `--auto` | `/gsd-new-project` | Skip interactive questions, ingest from a PRD file | +| `--research` | `/gsd-quick` | Add a research agent to an ad-hoc task | +| `--validate` | `/gsd-quick` | Add plan-checking and post-execution verification | +| `--chain` | `/gsd-discuss-phase` | Auto-chain discuss → plan → execute without stopping | +| `--skip-research` | `/gsd-plan-phase` | Skip research agents when the domain is already familiar | +| `--draft` | `/gsd-ship` | Create a draft PR instead of a ready-for-review one | + +For the full command reference with all flags, see [`docs/COMMANDS.md`](COMMANDS.md). For configuration options (model profiles, workflow agents, git branching), see [`docs/CONFIGURATION.md`](CONFIGURATION.md). + +--- + ## Workflow Diagrams ### Full Project Lifecycle