golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
docs/tutorials/onboarding-an-existing-codebase.md Normal file
View File

@@ -0,0 +1,226 @@
# Onboarding an existing codebase
In this tutorial you will bring GSD Core into a repository that already has code in it. You will map the codebase, create a project that describes what you are *adding*, and run your first discuss-and-plan cycle for a small focused change. By the end, GSD Core's planning pipeline will know your stack, your conventions, and your concerns — and it will use that knowledge every time you plan.
---
## What you'll build
We will add a single `GET /health` endpoint to an existing Express application. The change is small enough that it will never distract from the real lesson: how GSD Core learns your codebase before it plans anything.
---
## Prerequisites
- **Node.js 18 or later** — `node --version` should print `v18.x.x` or higher.
- **An existing project** — any repo with code already in it. It does not have to be Express; the steps apply to any stack.
- **Claude Code** — open in your repo root.
---
## Step 1 — Install GSD Core
From your repo root:
```bash
npx @opengsd/gsd-core@latest
```
Choose **Claude Code** and **local** when prompted. You'll see:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
---
## Step 2 — Start Claude Code with permissions
```bash
claude --dangerously-skip-permissions
```
---
## Step 3 — Map the codebase
Before creating a project, let GSD Core learn what already exists. This is the step that makes brownfield planning accurate.
```text
/gsd-map-codebase
```
GSD Core spawns four parallel mapper sub-agents (you'll see "Spawning 4 parallel codebase mapper agents…" — this takes 1–5 minutes; do not interrupt). Each agent focuses on a different concern:
| Agent | Focus |
|-------|-------|
| Tech mapper | Stack, frameworks, dependencies |
| Architecture mapper | Patterns, layers, data flow |
| Quality mapper | Conventions, testing practices |
| Concerns mapper | Technical debt, risk areas |
When all four return, you'll see:
```text
Codebase mapping complete.
Created .planning/codebase/:
- STACK.md (47 lines) - Technologies and dependencies
- ARCHITECTURE.md (62 lines) - System design and patterns
- STRUCTURE.md (38 lines) - Directory layout and organisation
- CONVENTIONS.md (55 lines) - Code style and patterns
- TESTING.md (41 lines) - Test structure and practices
- INTEGRATIONS.md (29 lines) - External services and APIs
- CONCERNS.md (33 lines) - Technical debt and issues
```
Open `.planning/codebase/STACK.md`. You'll see the language, runtime, framework versions, and key dependencies GSD Core detected — grounded in the actual files it read, not guessed.
Open `.planning/codebase/CONVENTIONS.md`. You'll see the naming conventions, error-handling patterns, and code-style rules it observed from your source. Every plan GSD Core produces for this repo will follow these conventions automatically.
Open `.planning/codebase/CONCERNS.md`. This is the most useful file to read before any new feature work — it surfaces technical debt and fragile areas that might affect your plans.
---
## Step 4 — Clear context and create the project
Clear the session window:
```text
/clear
```
Now create the project. Because GSD Core found existing code in the last step, it already knows this is a brownfield project. When you run `/gsd-new-project`, the questions focus on what you are *adding*, not rebuilding what already exists:
```text
/gsd-new-project
```
GSD Core asks what you want to build. Answer with the feature you are adding, not a description of the whole codebase:
```text
Add a GET /health endpoint to the Express app. It should return
{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
health checks.
```
GSD Core follows up with a small number of clarifying questions, then proceeds to requirements and roadmap creation. Because it already read `ARCHITECTURE.md` and `STACK.md`, it will map existing capabilities into the **Validated** section of `PROJECT.md` automatically — you do not need to describe your existing API surface.
Choose recommended defaults for all workflow settings.
When the roadmapper sub-agent returns, you'll see a proposed roadmap. For a single small change it will be one phase:
```text
Proposed Roadmap
1 phase | 2 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|----------------|-----------------------------------------------|--------------|
| 1 | Health endpoint| GET /health returning status and uptime JSON | HLT-01, HLT-02 |
```
Approve the roadmap.
**What gets created in `.planning/`:**
```text
.planning/
PROJECT.md ← project description; existing capabilities in "Validated"
REQUIREMENTS.md ← HLT-01, HLT-02
ROADMAP.md ← Phase 1, status: pending
STATE.md ← session memory
config.json ← workflow settings
codebase/ ← the seven map files from Step 3
```
Notice that `.planning/codebase/` is already there from Step 3. GSD Core read those files when writing `PROJECT.md`, which is why it could populate the Validated requirements without you describing them.
---
## Step 5 — Clear context and discuss Phase 1
```text
/clear
```
```text
/gsd-discuss-phase 1
```
Because GSD Core has read your `CONVENTIONS.md` and `ARCHITECTURE.md`, its questions are grounded in your actual codebase — not generic advice. You might see:
```text
> Your routes are registered in src/routes/index.js. Should the health
endpoint live there, or in a dedicated src/routes/health.js?
A dedicated health.js — keep routes separated.
> Your existing error middleware returns { error: "message" }. Should
/health use the same shape for error responses?
Yes, stay consistent.
> Should uptime be calculated from process.uptime() or a stored start time?
process.uptime() is fine.
```
When the discussion closes, GSD Core writes:
```text
.planning/phases/01-health-endpoint/CONTEXT.md
```
Open that file. The `## Implementation Decisions` section captures your answers. The planner will read this file before writing a single task — so your preferences about file placement and response shape will appear in the plans, not just in the discussion.
---
## Step 6 — Plan Phase 1
```text
/gsd-plan-phase 1
```
Four research sub-agents run in parallel (1–5 minutes). When they return, the planner reads `CONTEXT.md`, the research findings, and your codebase map to create task plans that match your conventions.
**What gets created:**
```text
.planning/phases/01-health-endpoint/
RESEARCH.md ← findings on health endpoint patterns
01-01-PLAN.md ← Task: create src/routes/health.js
01-02-PLAN.md ← Task: register health route in src/routes/index.js
```
Open `01-01-PLAN.md`. Notice that the `<files>` tag references `src/routes/health.js` — the exact path you specified in the discussion, consistent with the routing pattern GSD Core observed in your codebase map. That is the codebase map at work.
---
## What's next
You now have a project with a codebase map, a discuss decision record, and verified task plans — all grounded in your actual code. From here, the workflow is identical to a greenfield project:
```text
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1
```
For every future feature, run `/gsd-map-codebase` again whenever the structure changes significantly, so the codebase map stays fresh.
---
## What you've learned
- How `/gsd-map-codebase` runs four parallel agents to produce `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md`, and `INTEGRATIONS.md` in `.planning/codebase/`.
- How `/gsd-new-project` in a brownfield repo focuses questions on what you are *adding* and populates Validated requirements from existing code.
- How the codebase map shapes every question in `/gsd-discuss-phase` — file paths, patterns, and conventions come from your actual code.
- How the planner reads `CONTEXT.md` plus `CONVENTIONS.md` to produce plans that match your repo's style.
---
## Related
- [Your first project](your-first-project.md) — the full greenfield loop from install to PR
- [Map codebase via Commands](../COMMANDS.md) — all `/gsd-map-codebase` flags and subcommands
- [Documentation index](../README.md)

291
docs/tutorials/your-first-project.md Normal file
View File

@@ -0,0 +1,291 @@
# 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.
---
## What you'll build
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.
---
## Prerequisites
- **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.
No other tools are required. GSD Core itself is installed in the next step.
---
## Step 1 — Install GSD Core
Open a terminal in your project directory and run:
```bash
npx @opengsd/gsd-core@latest
```
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.
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.
---
## Step 2 — Start Claude Code with permissions
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:
```bash
claude --dangerously-skip-permissions
```
You'll land at the Claude Code prompt in your project directory.
---
## Step 3 — Create the project
Type this slash command at the Claude Code 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:
```text
A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
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:
```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 |
```
Type **Approve** to accept the roadmap.
**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
```
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.
---
## Step 4 — Clear context and discuss Phase 1
GSD Core is designed around fresh contexts. Clear the main session window before each phase:
```text
/clear
```
Then start the discussion for Phase 1:
```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:
```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?
Create it silently on first add.
```
When the discussion closes, GSD Core writes:
```text
.planning/phases/01-core-cli/CONTEXT.md
```
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.
---
## Step 5 — Plan Phase 1
```text
/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.
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.
**What gets 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
```
Open `01-01-PLAN.md`. You'll see a `<task>` block with a name, the files it touches, the action steps, a verify command, and a done condition. Notice the `<verify>` tag — GSD Core's executor will run that command after writing the code.
---
## Step 6 — Execute Phase 1
```text
/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:
```text
Wave 1 (parallel):
[Executor A] → 01-01-PLAN.md (read/write helpers) ✓ committed
[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 ✓
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:
```bash
node todo.js add "buy milk"
node todo.js add "write tests"
node todo.js list
node todo.js done 1
node todo.js list
```
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.
---
## Step 7 — Verify the work
```text
/gsd-verify-work 1
```
GSD Core extracts the phase's success criteria and walks you through each one:
```text
[1/3] Can you run `node todo.js add "buy milk"` without errors?
> yes
[2/3] Does `node todo.js list` show only incomplete items by default?
> yes
[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
> yes
All 3 checks passed. Phase 1 verified.
```
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`.
**What gets created:**
```text
.planning/phases/01-core-cli/UAT.md ← all checks and their outcomes
```
---
## Step 8 — Ship it
```text
/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:
```text
Pull request created: https://github.com/your-org/your-repo/pull/1
Title: feat(phase-1): core CLI — add / list / done commands
```
That is the full loop — from idea to merged PR — for one phase.
---
## What you've learned
- 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, then run `/gsd-progress --next` to let GSD Core detect the next step automatically.
---
## Related
- [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