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

* 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>
2026-06-02 08:13:09 -04:00
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
--- a/docs/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/tutorials/onboarding-an-existing-codebase.md
@@ -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)