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