From 9bd0dbf0dd6fddb4ad2a4eb3350ef0082a03673f Mon Sep 17 00:00:00 2001 From: clezcoding <72379688+clezcoding@users.noreply.github.com> Date: Fri, 31 Jul 2026 15:48:54 +0200 Subject: [PATCH] docs(#2534): rewrite your-first-project tutorial for beginners (#2569) * docs(#2534): rewrite your-first-project tutorial for beginners Adds a loop mental-model primer (Mermaid), per-step "what just happened" callouts, a prerequisites flow, a glossary and a troubleshooting table. Same commands, same .planning artefacts, same to-do CLI example. Closes #2534 * docs(#2534): make the tutorial runtime-agnostic (all IDEs) Adds a "Pick your runtime" section (Cursor, Claude Code, OpenCode, Codex, Gemini CLI, Copilot, Windsurf, Kilo, Cline, Qwen, Antigravity, ...) with the installer flag and command syntax per runtime (/gsd-*, /gsd:* colon form, and Cline rules). Keeps the same guaranteed worked example and .planning artefacts. Closes #2534 * docs(#2534): address review - drop gsd-cursor aside + dead hero comment - Remove the '(pair with the gsd-cursor EoS ...)' parenthetical from the Cursor row. - Remove the commented-out reference to a non-existent hero asset. (Gemini CLI references retained: --gemini is still live in bin/install.js on next.) Closes #2534 * docs(#2534): fix review defects (keep multi-runtime) - Replace dead Gemini CLI / --gemini with its live successor Antigravity (#1928); remove the invalid --gemini row/flag everywhere. - Replace fabricated Step 1 output with realistic installer lines (71 skills/commands + destination suffix; exact lines vary by runtime). - Fix 'Skip research' -> choose 'No' on the real Research prompt. - behaviours -> behaviors (2x). Multi-runtime 'Pick your runtime' section retained per author intent; scope re-approval on #2534 still pending. * docs(#2534): scope tutorial back to single-runtime (Claude Code) Per trek-e's 2026-07-27 review, resolve the multi-runtime blockers by returning to the approved scope: - Remove the 'Pick your runtime' table + per-runtime notes; leave a one- line pointer to docs/how-to/install-on-your-runtime.md (which already documents all runtimes) rather than duplicate it (avoids the drift). This kills Blocker 1 (Antigravity is slash-hyphen, not colon) and Blocker 2 (Codex is $gsd-*) at the source. - Step 1 uses --claude concretely; config-dir prose is Claude-local. - Step 5: fix singular researcher (plan-phase spawns one gsd-phase- researcher), and make the research choice consistent with Step 3 (choose 'Skip research'); drop the RESEARCH.md artifact line. - Glossary/troubleshooting/prereqs/Step 2 de-multi-runtimed. Returns the PR to #2534's approved 'docs-only, same commands' scope. * docs(#2534): correct tutorial prerequisites and outputs * docs(#2534): match tutorial research prompts to workflow * docs(#2534): complete tutorial step guidance --------- Co-authored-by: clezcoding Co-authored-by: Tom Boucher --- docs/tutorials/your-first-project.md | 535 ++++++++++++++++++++------- 1 file changed, 408 insertions(+), 127 deletions(-) diff --git a/docs/tutorials/your-first-project.md b/docs/tutorials/your-first-project.md index 694977322..9198c5895 100644 --- a/docs/tutorials/your-first-project.md +++ b/docs/tutorials/your-first-project.md @@ -1,76 +1,245 @@ -# Your first project +
-In this tutorial you will install GSD Core and build a small command-line to-do app from scratch β€” one phase, one PR, the full loop. By the end you will have run every command in the core phase loop at least once, and you will have seen the planning artefacts that each command produces. +# πŸš€ Your first project + +**From an empty GitHub repository to a shipped pull request β€” in one guided loop.** + +![level](https://img.shields.io/badge/level-beginner-3fb950?style=flat-square) +![time](https://img.shields.io/badge/time-30–45%20min-f0883e?style=flat-square) +![runtime](https://img.shields.io/badge/runtime-Claude%20Code-8957e5?style=flat-square) +![node](https://img.shields.io/badge/Node-22%2B-2f81f7?style=flat-square) +![npm](https://img.shields.io/badge/npm-10%2B-cb3837?style=flat-square) + +
+ +> [!TIP] +> **This is the one guaranteed path.** You will build a tiny app, run **every** +> command in the core loop exactly once, and β€” the part most tutorials skip β€” +> understand *why* each step exists. This tutorial uses **Claude Code**; GSD +> works in 15+ runtimes β€” see [Install on your runtime](../how-to/install-on-your-runtime.md) +> for the flag and command syntax for yours. --- -## What you'll build +## πŸ“– Table of contents -A Node.js CLI that lets you add, list, and complete to-do items stored in a local JSON file. It is small enough to finish in one session and uses nothing beyond the Node.js standard library, so there is nothing unusual to install. +1. [The one idea that makes GSD click](#-the-one-idea-that-makes-gsd-click) +2. [What you'll build](#-what-youll-build) +3. [Prerequisites](#-prerequisites) +4. [Step 1 β€” Install GSD Core](#step-1--install-gsd-core-into-your-runtime) +5. [Step 2 β€” Open Claude Code](#step-2--open-claude-code) +6. [Step 3 β€” Create the project](#step-3--create-the-project) +7. [Step 4 β€” Discuss Phase 1](#step-4--clear-context-then-discuss-phase-1) +8. [Step 5 β€” Plan Phase 1](#step-5--plan-phase-1) +9. [Step 6 β€” Execute Phase 1](#step-6--execute-phase-1) +10. [Step 7 β€” Verify the work](#step-7--verify-the-work) +11. [Step 8 β€” Ship it](#step-8--ship-it) +12. [Glossary](#-mini-glossary) Β· [Troubleshooting](#-troubleshooting) Β· [What next](#-what-next) --- -## Prerequisites +## πŸ’‘ The one idea that makes GSD click -- **Node.js 18 or later** β€” `node --version` should print `v18.x.x` or higher. -- **Claude Code** β€” open in the project directory you want to use. -- An internet connection for the initial install. +GSD Core does **not** "write your whole app in one shot." It runs a **repeating +five-step loop**, and it does the heavy thinking in **fresh, throwaway +sub-agents** so your main chat window never fills up with clutter β€” the quality +killer GSD calls [context rot](../explanation/context-engineering.md). -No other tools are required. GSD Core itself is installed in the next step. +You drive that loop **one phase at a time**: + +```mermaid +flowchart LR + D([πŸ’¬ Discuss]) --> P([πŸ“ Plan]) + P --> E([βš™οΈ Execute]) + E --> V([βœ… Verify]) + V --> S([πŸš€ Ship]) + S -. next phase .-> D + classDef step fill:#1f2430,stroke:#f0883e,stroke-width:2px,color:#e6edf3; + class D,P,E,V,S step; +``` + +| Step | Command | In one sentence | Typical time | +|:----:|---------|-----------------|:------------:| +| πŸ’¬ **Discuss** | `/gsd-discuss-phase` | GSD asks *how* to build it and writes your answers down. | 2–4 min | +| πŸ“ **Plan** | `/gsd-plan-phase` | GSD splits the work into small, checkable task plans. | 1–5 min | +| βš™οΈ **Execute** | `/gsd-execute-phase` | Fresh agents write the code and commit each task. | 2–6 min | +| βœ… **Verify** | `/gsd-verify-work` | GSD walks you through "does it actually work?" | 1–3 min | +| πŸš€ **Ship** | `/gsd-ship` | A pull request is opened for you. | <1 min | + +> [!NOTE] +> **Keep that table handy.** Whenever you feel lost, ask yourself one question: +> *"which step of the loop am I on?"* That's the entire mental model. + +
+🧠 Why fresh sub-agents? (the 30-second version) + +
+ +A single long chat slowly degrades: the more it holds, the more the model +juggles, and quality quietly drops. GSD sidesteps this by spawning a **clean +200k-token worker** for each heavy job (research, execution) and throwing it away +after. Your main session stays lean; the shared `.planning/` files carry memory +between them. + +```mermaid +flowchart TB + subgraph main [Your main session Β· stays lean] + you([You + GSD]) + end + subgraph workers [Fresh sub-agents Β· clean context each time] + r1[Researcher] + r2[Researcher] + ex[Executor A] + ey[Executor B] + end + you -- spawns --> r1 & r2 & ex & ey + r1 & r2 & ex & ey -- write --> plan[(.planning/ files)] + plan -- memory --> you + classDef m fill:#132a1a,stroke:#3fb950,color:#e6edf3; + classDef w fill:#1f2430,stroke:#58a6ff,color:#e6edf3; + classDef f fill:#2d2410,stroke:#f0883e,color:#e6edf3; + class you m; class r1,r2,ex,ey w; class plan f; +``` + +
--- -## Step 1 β€” Install GSD Core +## 🎯 What you'll build -Open a terminal in your project directory and run: +A small **Node.js command-line to-do app**: ```bash -npx @opengsd/gsd-core@latest +todo add "buy milk" # βž• add an item +todo list # πŸ“‹ see open items +todo done 1 # βœ… complete item 1 ``` -The installer asks which AI coding runtime you are using and whether to install globally or into the current project. Choose **Claude Code** and **local** (just this project) for now. +Items live in a local `todos.json`. It uses **only the Node.js standard library** +β€” nothing to install, nothing to configure β€” so you focus entirely on the GSD +loop, not a toolchain. -You'll see output like: - -```text -βœ“ Installed 86 skills to .claude/commands/ -βœ“ Installed agents to .claude/agents/ -βœ“ GSD Core ready β€” run /gsd-new-project to start -``` - -Notice that a `.claude/` directory now exists in your project. That is where GSD Core's commands and agents live. - -> Why local vs global? A local install keeps the skills version pinned to this project. See [Install on your runtime](../how-to/install-on-your-runtime.md) when you want to install globally. +> [!TIP] +> Small on purpose. Once the loop is muscle memory, the *exact same* eight steps +> scale to a real multi-phase product. --- -## Step 2 β€” Start Claude Code with permissions +## βœ… Prerequisites -GSD Core spawns sub-agents that read and write files. Start Claude Code with the permissions flag so it does not pause to ask about every file operation: +| You need | Check with | "Good" looks like | +|----------|------------|-------------------| +| **Node.js 22+** | `node --version` | `v22.x.x` or higher | +| **npm 10+** | `npm --version` | `10.x.x` or higher | +| **Claude Code** | `claude --version` | installed and opens | +| **Git** | `git --version` | installed | +| **GitHub CLI** | `gh --version` and `gh auth status` | installed and authenticated | +| **An empty GitHub repository cloned locally** | `git remote get-url origin` | your repository's GitHub URL | +| **Internet** | β€” | available for installation and GitHub operations | + +If you do not already have an empty repository, create and clone one now. If +`gh auth status` says you are not logged in, run `gh auth login` first. + +```bash +gh repo create gsd-todo-tutorial --private --clone +cd gsd-todo-tutorial +git remote get-url origin +``` + +```mermaid +flowchart LR + A[node --version β‰₯ 22?] -->|no| A1[Install/upgrade Node] --> A + A -->|yes| B[npm --version β‰₯ 10?] + B -->|no| B1[Install/upgrade npm] --> B + B -->|yes| C[Claude Code installed?] + C -->|no| C1[Install Claude Code] --> C + C -->|yes| D[gh authenticated?] + D -->|no| D1[Run gh auth login] --> D + D -->|yes| E[origin points to GitHub?] + E -->|no| E1[Create or clone a repository] --> E + E -->|yes| R([βœ… Ready for Step 1]) + classDef ok fill:#132a1a,stroke:#3fb950,color:#e6edf3; + class R ok; +``` + +--- + +## Step 1 β€” Install GSD Core into your runtime + +From a terminal **in your project directory**, run the installer: + +```bash +npx @opengsd/gsd-core@latest --claude --local +``` + +This tutorial uses `--local`, so GSD is installed only in this project. On a +different runtime? See [Install on your runtime](../how-to/install-on-your-runtime.md) +for its flag. You'll see a summary of what was installed, e.g.: + +```text +βœ“ Installed 71 commands to commands/ (gsd-.md flat form) +βœ“ Installed agents +``` + +Then **restart Claude Code** so it picks up the new commands and agents. + +
+πŸ’‘ What just happened? + +
+ +A `.claude/` directory in your project now holds GSD's **commands** and +**agents**. You never edit these by hand β€” the installer owns them and keeps them +in Claude Code's native format. + +
+ +> [!WARNING] +> **Don't copy files from `agents/` or `commands/` directly** β€” that bypasses the +> installer's transformations and produces schema errors or missing commands. +> Always use the installer. + +--- + +## Step 2 β€” Open Claude Code + +For this disposable tutorial project, open (or restart) Claude Code in your +project directory with: ```bash claude --dangerously-skip-permissions ``` -You'll land at the Claude Code prompt in your project directory. +You'll land at a prompt ready for input. + +> [!CAUTION] +> **The permissions flag is optional.** It skips per-file confirmation while +> GSD's sub-agents read and write files. Use it only for this throwaway tutorial +> in an empty folder. To keep confirmations enabled, start with `claude` instead. +> For real work, read the [security model](../explanation/security-model.md) first. + +
+πŸ’‘ What just happened? + +
+ +Claude Code opened in the project where Step 1 installed GSD. It loaded the +project-local `.claude/` commands and agents, so `/gsd-*` commands are now +available at the prompt. + +
--- ## Step 3 β€” Create the project -Type this slash command at the Claude Code prompt: +At Claude Code's prompt: ```text /gsd-new-project ``` -GSD Core will open a conversation. It asks one question first: - -```text -What do you want to build? -``` - -Type something like: +The first question is always **"What do you want to build?"** Paste this: ```text A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`, @@ -78,75 +247,93 @@ A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`, No external dependencies β€” Node built-ins only. ``` -GSD Core follows up with a handful of clarifying questions. Answer them naturally. It is learning what you care about before it writes a single plan. - -After the questions, it offers to run domain research. For a project this small you can skip research β€” choose **Skip research** when prompted. - -GSD Core then asks you to pick workflow settings (mode, granularity, research agents). Choose the recommended defaults for each. These are written to `.planning/config.json`. - -Finally, a roadmapper sub-agent runs (you'll see the "Spawning roadmapper…" notice β€” this is normal and takes roughly a minute). When it returns, GSD Core presents a proposed roadmap. For a single-phase project it will look something like: +Then answer the **clarifying questions**, choose **No** when asked *"Research before planning each phase? (adds tokens/time)"* (skip it for this small build), take the +**recommended defaults** for workflow settings, and wait for the **roadmapper** +(~1 min). Type **Approve** on the proposed roadmap: ```text Proposed Roadmap - 1 phase | 4 requirements mapped | All v1 requirements covered βœ“ -| # | Phase | Goal | Requirements | -|---|--------------------|-----------------------------------------|-------------------| -| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 | +| # | Phase | Goal | Requirements | +|---|----------|----------------------------------------|-----------------| +| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 | ``` -Type **Approve** to accept the roadmap. +
+πŸ’‘ What just got created in .planning/? -**What gets created in `.planning/`:** +
-```text -.planning/ - PROJECT.md ← your project description and requirements - REQUIREMENTS.md ← REQ-IDs for every v1 capability - ROADMAP.md ← Phase 1, status: pending - STATE.md ← session memory, current position - config.json ← workflow settings +```mermaid +flowchart TD + root[.planning/] + root --> PROJECT[PROJECT.md
your description + requirements] + root --> REQ[REQUIREMENTS.md
a REQ-ID per capability] + root --> ROAD[ROADMAP.md
Phase 1 Β· status: pending] + root --> STATE[STATE.md
session memory Β· where you are] + root --> CFG[config.json
your workflow settings] + classDef f fill:#1f2430,stroke:#f0883e,color:#e6edf3; + class root,PROJECT,REQ,ROAD,STATE,CFG f; ``` -Open `.planning/ROADMAP.md` now and read through it. Notice that Phase 1 has a Goal, a list of Requirements it must satisfy, and Success Criteria β€” these are the observable behaviours that execution must deliver. +These files are GSD's **shared memory** β€” they survive `/clear`, survive closing +your laptop, and let a fresh sub-agent pick up exactly where the last left off. + +
+ +πŸ‘‰ **Do this now:** open `.planning/ROADMAP.md`. Phase 1 has a **Goal**, +**Requirements**, and **Success Criteria** β€” the observable behaviors execution +must deliver. This file is your map for the rest of the tutorial. --- -## Step 4 β€” Clear context and discuss Phase 1 +## Step 4 β€” Clear context, then discuss Phase 1 -GSD Core is designed around fresh contexts. Clear the main session window before each phase: +GSD is built around **fresh contexts**. Clear the window before each phase: ```text /clear ``` -Then start the discussion for Phase 1: +Then open the discussion: ```text /gsd-discuss-phase 1 ``` -GSD Core reads the phase goal and asks about your implementation preferences. These are the decisions that shape *how* it builds, not just *what* it builds. Example exchange: +GSD asks about your **implementation preferences** β€” *how* to build, not just +*what*: ```text > How should done items be stored β€” mark them in place or move them? Mark them in place with a "done" flag. - > Should `todo list` show completed items by default? No, hide them unless --all is passed. - -> Error format when todos.json doesn't exist yet? +> What if todos.json doesn't exist yet? Create it silently on first add. ``` -When the discussion closes, GSD Core writes: +It writes `.planning/phases/01-core-cli/01-CONTEXT.md`. -```text -.planning/phases/01-core-cli/CONTEXT.md -``` +πŸ‘‰ **Do this now:** open that file β†’ find `## Implementation Decisions`. Those are +your words, captured. The planner reads this next, so every decision here flows +into the task plans. -Open that file. You'll see an `## Implementation Decisions` section capturing exactly what you said. The planner reads this file β€” so the decisions you made here will flow through into every task plan. +> [!NOTE] +> **Why discuss before planning?** Decide the small stuff up front and the plan is +> right the first time β€” instead of you correcting a wrong plan, choice by choice. + +
+πŸ’‘ What just happened? + +
+ +`/clear` discarded the old chat context, then `/gsd-discuss-phase 1` captured +your implementation choices in `01-CONTEXT.md`. The next planner receives those +decisions without needing the earlier conversation. + +
--- @@ -156,20 +343,42 @@ Open that file. You'll see an `## Implementation Decisions` section capturing ex /gsd-plan-phase 1 ``` -Four research sub-agents fan out in parallel (you'll see the "Spawning 4 researchers…" notice). They take 1–5 minutes. Do not interrupt. +```mermaid +sequenceDiagram + participant You + participant GSD + participant PL as Planner + participant PC as Plan-checker + You->>GSD: /gsd-plan-phase 1 + GSD->>You: Research before planning Phase 1: Core CLI? + You->>GSD: Skip research + GSD->>PL: 01-CONTEXT.md + PL-->>GSD: atomic task plans + GSD->>PC: verify each plan hits the goal + PC-->>You: plans saved βœ“ +``` -When they return, a planner reads CONTEXT.md plus the research findings and creates atomic task plans. A plan-checker then verifies each plan achieves the phase goal before saving. +GSD asks **"Research before planning Phase 1: Core CLI?"** β€” choose **Skip research** (same +as Step 3; this build is small and well-understood). A **planner** then turns +`01-CONTEXT.md` into **atomic task plans**, and a **plan-checker** verifies each +before saving. -**What gets created:** +
+πŸ’‘ What just got created? + +
```text .planning/phases/01-core-cli/ - RESEARCH.md ← domain findings - 01-01-PLAN.md ← Task: create todos.json read/write helpers - 01-02-PLAN.md ← Task: implement add / list / done commands + 01-01-PLAN.md ← Task: todos.json read/write helpers + 01-02-PLAN.md ← Task: add / list / done commands ``` -Open `01-01-PLAN.md`. You'll see a `` block with a name, the files it touches, the action steps, a verify command, and a done condition. Notice the `` tag β€” GSD Core's executor will run that command after writing the code. +
+ +πŸ‘‰ **Do this now:** open `01-01-PLAN.md`. Inside the `` block: a name, the +files it touches, action steps, a `` command, and a "done" condition. +That `` isn't decoration β€” the executor runs it after writing code. --- @@ -179,9 +388,8 @@ Open `01-01-PLAN.md`. You'll see a `` block with a name, the files it touc /gsd-execute-phase 1 ``` -GSD Core groups the plans into waves (independent plans run in parallel), spawns a fresh 200k-context executor per plan, and commits each task atomically. - -You'll see something like: +GSD groups plans into **waves** (independent plans run in parallel), spawns a +**fresh 200k-context executor per plan**, and commits each task atomically: ```text Wave 1 (parallel): @@ -189,33 +397,36 @@ Wave 1 (parallel): [Executor B] β†’ 01-02-PLAN.md (CLI commands) βœ“ committed [Verifier] Checking codebase against phase goals... - CLI-01 todo add βœ“ - CLI-02 todo list βœ“ - CLI-03 todo done βœ“ - CLI-04 --all flag βœ“ + CLI-01 todo add βœ“ CLI-03 todo done βœ“ + CLI-02 todo list βœ“ CLI-04 --all flag βœ“ Status: PASS ``` -**What gets created:** - -```text -.planning/phases/01-core-cli/ - 01-01-SUMMARY.md ← what Executor A built and committed - 01-02-SUMMARY.md ← what Executor B built and committed - VERIFICATION.md ← REQ coverage: PASS -``` - -Run your CLI now: +**Run your app** β€” your first visible result: ```bash node todo.js add "buy milk" node todo.js add "write tests" -node todo.js list +node todo.js list # β†’ both items node todo.js done 1 -node todo.js list +node todo.js list # β†’ only "write tests" ``` -You should see items appear, and item 1 disappear from the default list after marking it done. That is your first visible result delivered by GSD Core. +πŸŽ‰ Item 1 disappears from the default list after `done`. It works. + +
+πŸ’‘ What just got created? + +
+ +```text +.planning/phases/01-core-cli/ + 01-01-SUMMARY.md ← what Executor A built + committed + 01-02-SUMMARY.md ← what Executor B built + committed + 01-VERIFICATION.md ← requirement coverage: PASS +``` + +
--- @@ -225,28 +436,45 @@ You should see items appear, and item 1 disappear from the default list after ma /gsd-verify-work 1 ``` -GSD Core extracts the phase's success criteria and walks you through each one: +GSD reads the phase's `SUMMARY.md` files and turns their user-visible +deliverables into checkpoints. It presents one checkpoint at a time; the first +one looks like this (the test wording depends on what was built): ```text -[1/3] Can you run `node todo.js add "buy milk"` without errors? -> yes +╔══════════════════════════════════════════════════════════════╗ +β•‘ CHECKPOINT: Verification Required β•‘ +β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• -[2/3] Does `node todo.js list` show only incomplete items by default? -> yes +**Test 1: Add a to-do** -[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list? -> yes +Running `node todo.js add "buy milk"` creates a pending item without errors. -All 3 checks passed. Phase 1 verified. +────────────────────────────────────────────────────────────── +Type `pass` or describe what's wrong. +────────────────────────────────────────────────────────────── ``` -If any check fails, GSD Core diagnoses the root cause and creates a fix plan. Run `/gsd-execute-phase 1` again to apply it, then re-run `/gsd-verify-work 1`. +Type `pass` when reality matches, or describe what differs. GSD records the +answer in `01-UAT.md` and then presents the next checkpoint. -**What gets created:** +If a check **fails**, GSD diagnoses the root cause and writes a fix plan β†’ re-run +`/gsd-execute-phase 1`, then `/gsd-verify-work 1` again. (Result: +`.planning/phases/01-core-cli/01-UAT.md`.) -```text -.planning/phases/01-core-cli/UAT.md ← all checks and their outcomes -``` +> [!NOTE] +> **Why a separate verify step?** "The code was written" and "the code works" are +> different claims. Verify proves the second one *before* you open a PR. + +
+πŸ’‘ What just happened? + +
+ +GSD turned the phase summaries into user-visible checks, recorded your answers +in `01-UAT.md`, and routed any failure back through a concrete fix plan. Shipping +only starts after those checks match reality. + +
--- @@ -256,36 +484,89 @@ If any check fails, GSD Core diagnoses the root cause and creates a fix plan. Ru /gsd-ship 1 ``` -GSD Core creates a pull request with a generated body. The PR body always includes: Summary, Changes, Requirements Addressed, Verification, and Key Decisions. - -You'll see: +GSD creates a pull request with a generated body (Summary Β· Changes Β· +Requirements Addressed Β· Verification Β· Key Decisions): ```text Pull request created: https://github.com/your-org/your-repo/pull/1 - -Title: feat(phase-1): core CLI β€” add / list / done commands +Title: Phase 01: core-cli ``` -That is the full loop β€” from idea to merged PR β€” for one phase. +That's the **full loop** β€” idea β†’ opened PR β€” for one phase, start to finish. πŸš€ + +```mermaid +flowchart LR + idea([πŸ’‘ idea]) --> loop + subgraph loop [one phase] + direction LR + d[Discuss]-->p[Plan]-->e[Execute]-->v[Verify]-->s[Ship] + end + loop --> pr([βœ… Pull request]) + classDef a fill:#1f2430,stroke:#f0883e,color:#e6edf3; + classDef ok fill:#132a1a,stroke:#3fb950,color:#e6edf3; + class d,p,e,v,s a; class pr,idea ok; +``` + +
+πŸ’‘ What just happened? + +
+ +`/gsd-ship 1` assembled the completed phase's requirements, decisions, and +verification evidence into a pull request. The PR is open for review; nothing +has been merged into the default branch yet. + +
--- -## What you've learned +## πŸ” Doing more than one phase -- How to install GSD Core with `npx @opengsd/gsd-core@latest`. -- How `/gsd-new-project` turns a conversation into a roadmap backed by `.planning/` artefacts. -- How `/gsd-discuss-phase` captures implementation decisions before any planning happens. -- How `/gsd-plan-phase` spawns parallel researchers and produces atomic task plans. -- How `/gsd-execute-phase` runs those plans in parallel waves and commits each task. -- How `/gsd-verify-work` walks through success criteria and generates fix plans when needed. -- How `/gsd-ship` turns a verified phase into a pull request. +For a multi-phase project, repeat **Steps 4–8** for each phase. Not sure what's +next? Let GSD detect it: -For a multi-phase project, repeat Steps 4–8 for each phase, then run `/gsd-progress --next` to let GSD Core detect the next step automatically. +```text +/gsd-progress --next +``` --- -## Related +## πŸ“š Mini-glossary -- [The phase loop](../explanation/the-phase-loop.md) β€” why the loop is shaped this way -- [How-to guides](../README.md#how-to-guides) β€” task-focused recipes for specific situations -- [Onboarding an existing codebase](onboarding-an-existing-codebase.md) β€” bring GSD Core to a brownfield repo +| Term | Meaning in GSD | +|------|----------------| +| **Runtime** | Your AI coding tool. This tutorial uses Claude Code. | +| **Phase** | One slice of the roadmap you take through the whole loop. | +| **The loop** | Discuss β†’ Plan β†’ Execute β†’ Verify β†’ Ship. | +| **Sub-agent** | A fresh, throwaway worker GSD spawns for research or execution. | +| **Context rot** | Quality decay as the main window fills up; fresh sub-agents prevent it. | +| **`.planning/`** | GSD's shared memory: PROJECT, REQUIREMENTS, ROADMAP, STATE, per-phase files. | +| **Requirement (REQ-ID)** | A single v1 capability the roadmap must cover, e.g. `CLI-01`. | +| **Success criteria** | Observable behaviors a phase must deliver, checked in Verify. | +| **Wave** | A batch of independent task plans executed in parallel. | + +--- + +## πŸ›Ÿ Troubleshooting + +| Symptom | Likely cause | Fix | +|---------|--------------|-----| +| A GSD command isn't recognized | Claude Code not restarted after install | Restart Claude Code so it loads the new `/gsd-*` commands. | +| `Spawning researchers…` looks stuck | Research runs 1–5 min | Wait β€” don't interrupt. If truly hung, `/clear` and re-run the step. | +| Verify keeps failing | Real bug in the code | Let GSD write the fix plan β†’ `/gsd-execute-phase 1` β†’ re-verify. | +| Lost track of where you are | β€” | Open `.planning/STATE.md`, or run `/gsd-progress --next`. | +| Wrong install directory | Alternate/prerelease Claude Code config dir | Set `CLAUDE_CONFIG_DIR` to match β€” see [Install on your runtime](../how-to/install-on-your-runtime.md). | + +--- + +## πŸŽ“ What next + +- [Install on your runtime](../how-to/install-on-your-runtime.md) β€” exact steps for every supported runtime +- [The phase loop](../explanation/the-phase-loop.md) β€” why it's shaped this way +- [Context engineering](../explanation/context-engineering.md) β€” the theory behind fresh sub-agents +- [Configure model profiles](../how-to/configure-model-profiles.md) β€” quality / balanced / budget tiers +- [Onboarding an existing codebase](onboarding-an-existing-codebase.md) β€” bring GSD to a brownfield repo + +> [!TIP] +> **You now know the whole loop.** Everything else in GSD is a refinement of these +> eight steps. Welcome aboard. πŸš€