msd-core/docs/tutorials/onboarding-an-existing-codebase.md

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:

npx @opengsd/gsd-core@latest

Choose Claude Code and local when prompted. You'll see:

✓ 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

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.

/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:

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:

/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:

/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:

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:

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/:

.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

/clear

/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:

> 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:

.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

/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:

.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:

/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 — the full greenfield loop from install to PR
• Map codebase via Commands — all /gsd-map-codebase flags and subcommands
• Documentation index