# 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": }. 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 `` 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)