Brownfield Projects

Running /gsd:new-project on an existing codebase makes GSD ask generic questions — it doesn’t know what patterns you’ve established, what libraries you’ve chosen, or how your code is organized. The result is plans that can contradict your existing architecture. Fix this by mapping first.

#Step 1: Map your codebase first

/gsd:map-codebase spawns four parallel agents that read your existing code and produce four context files:

• Stack Mapper → .planning/codebase/STACK.md — frameworks, libraries, build tooling, and why each was chosen
• Architecture Mapper → .planning/codebase/ARCHITECTURE.md — directory structure, module boundaries, data flow
• Convention Mapper → .planning/codebase/CONVENTIONS.md — naming patterns, file organization, coding style
• Concern Mapper → .planning/codebase/CONCERNS.md — known issues, tech debt, areas that need care

$ /gsd:map-codebase

Each agent reads your actual code — not a description of it. The output files become permanent context that every future PLAN.md loads automatically.

#Step 2: Initialize GSD

After mapping, run /gsd:new-project. Now the discuss phase asks focused questions about what you’re adding, not what already exists. The planner reads your codebase context files before writing any plans — naming conventions match yours, abstractions layer on top of what’s already there, no duplicate patterns.

$ /gsd:new-project

The planning system automatically loads your .planning/codebase/ files into every PLAN.md’s context. You don’t need to reference them manually.