How to Add GSD to an Existing Codebase with /gsd-map-codebase and /gsd-ingest-docs

Apr 21, 2026

GSD Brownfield Integration

The Problem

I have an existing project with thousands of lines of code. I want to use GSD (Get Stuff Done) for planning my next feature, but GSD seems designed for new projects. How do I add GSD structure without throwing away what I already have?

This is the brownfield problem. Greenfield projects start fresh with a clean slate. Brownfield projects have existing patterns, architecture decisions, and coding conventions that GSD needs to understand before it can help plan new features.

Why Brownfield Needs Mapping First

When I start a new project with /gsd-new-project, GSD asks me questions about my tech stack, architecture, and conventions. But for an existing project, those decisions are already made. They’re embedded in my code.

If I run /gsd-new-project directly on an existing codebase, GSD asks questions about things I already know. It wastes time and misses the patterns already present in my code.

The solution is simple: run /gsd-map-codebase first.

How /gsd-map-codebase Works

/gsd-map-codebase spawns parallel agents to analyze my existing project:

Stack researcher:     Technology choices, frameworks, libraries
Architecture researcher: Patterns, layering, data flow
Conventions researcher: Coding standards, file organization, naming
Concerns researcher:    Security areas, performance hotspots, tech debt

Each agent investigates a specific aspect of my codebase. They work simultaneously, so the analysis completes faster than sequential investigation.

The output goes into the research/ directory:

research/STACK.md       - What technologies I'm using
research/ARCHITECTURE.md - How my code is organized
research/CONVENTIONS.md  - My coding standards and patterns
research/CONCERNS.md     - Areas that need attention

Running the Mapping Command

Here’s what happened when I ran it on my Flask project:

/gsd-map-codebase

# Output:
Spawning 4 parallel research agents...
Stack researcher: Analyzing package.json, requirements.txt, config files
Architecture researcher: Mapping directory structure, layer boundaries
Conventions researcher: Scanning for patterns, naming conventions
Concerns researcher: Identifying security-sensitive code, performance areas

Analysis complete. Results in research/:
- STACK.md: Python 3.11, Flask 3.0, SQLAlchemy, PostgreSQL
- ARCHITECTURE.md: Repository pattern, service layer, API routes
- CONVENTIONS.md: Snake_case for functions, PascalCase for classes
- CONCERNS.md: Authentication routes, database connection pooling

GSD now knows my project context. When I run /gsd-new-project next, it asks about what I’m adding, not what I already have.

What /gsd-new-project Does After Mapping

With mapping complete, the initialization flow changes:

WITHOUT mapping:
  "What's your tech stack?" → "How do you organize code?" → "What conventions?"

WITH mapping:
  "You're using Flask + SQLAlchemy. What feature are you adding?"
  → Planning uses your existing patterns automatically

The mapping results load automatically during /gsd-new-project. GSD references my architecture when planning. It applies my conventions when generating specs. It highlights areas from my concerns list that relate to the new feature.

Area-Targeted Mapping

Sometimes I don’t need a full codebase scan. I can target specific areas:

/gsd-map-codebase [auth]

# Only analyzes authentication-related code:
# - STACK.md: Auth libraries, session management
# - ARCHITECTURE.md: Auth layer structure
# - CONVENTIONS.md: Auth-specific patterns
# - CONCERNS.md: Password handling, session security

This is useful when I’m adding a feature that touches a specific subsystem. The targeted analysis focuses on what matters for that area.

Importing Existing Documentation

Many projects have existing documentation that GSD should know about:

ADR  - Architecture Decision Records
PRD  - Product Requirements Documents
SPEC - Technical Specifications
DOC  - General documentation

I use /gsd-ingest-docs to import these:

/gsd-ingest-docs docs/

# Scans docs/ directory for:
# - ADR-001-auth-strategy.md → Imported to .planning/decisions/
# - PRD-user-dashboard.md    → Imported to .planning/requirements/
# - SPEC-api-v2.md           → Imported to .planning/specs/

This saves me from recreating documentation GSD can reuse. My existing ADRs become part of the planning context. My PRDs inform feature planning without manual re-entry.

Re-Importing After Context Loss

Sometimes I need to rebuild my GSD planning context. The project itself is fine, but the .planning/ directory needs refreshing.

The workflow is:

Step 1: /gsd-map-codebase     - Scan current project state
Step 2: /gsd-new-project      - Initialize fresh planning
Step 3: /gsd-ingest-docs docs/ - Import existing docs back

My code doesn’t change. Only the planning context rebuilds. This is useful after Anthropic ToS changes that affect how context is stored.

The Brownfield Workflow

Here’s the complete workflow for adding GSD to an existing project:

1. /gsd-map-codebase [area]    - Analyze existing code
2. /gsd-new-project            - Initialize with mapping context
3. /gsd-ingest-docs docs/      - Import existing documentation
4. /gsd-plan "feature"         - Plan using your existing patterns
5. /gsd-implement              - Build following your conventions

Each step uses what exists before creating what’s new. My patterns guide the planning. My conventions shape the implementation.

What Mapping Captures

The mapping agents look for specific information:

STACK.md captures:

Programming language and version
Frameworks and major libraries
Database technology
Build tools and CI/CD
Testing frameworks

ARCHITECTURE.md captures:

Directory structure and organization
Layer boundaries (if layered)
Data flow patterns
Module relationships
Dependency direction

CONVENTIONS.md captures:

Naming patterns (files, functions, classes)
Code style preferences
File size limits
Documentation habits
Test organization

CONCERNS.md captures:

Security-sensitive code paths
Performance-critical areas
Known tech debt locations
Complexity hotspots
Integration boundaries

Summary

In this post, I explained how to add GSD planning structure to an existing codebase. The key commands are:

/gsd-map-codebase analyzes existing code through parallel agents, producing STACK.md, ARCHITECTURE.md, CONVENTIONS.md, and CONCERNS.md
/gsd-new-project uses the mapping results to ask about what you’re adding, not what exists
/gsd-ingest-docs imports existing ADRs, PRDs, and specifications into .planning/
Area targeting [area] lets you focus mapping on specific subsystems

Brownfield projects get full GSD benefits without starting from scratch. The mapping step is essential for GSD to understand your patterns before planning your additions.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!