feat(03-01): brownfield integration into GSD workflows

- new-project.md detects existing code, offers /gsd:map-codebase first
- plan-phase loads relevant codebase context based on phase type
- execute-phase updates codebase map incrementally after execution

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commands/gsd/new-project.md

@@ -44,7 +44,40 @@ Creates `.planning/` with PROJECT.md and config.json.
    fi
    ```
 
-   **You MUST run both bash commands above using the Bash tool before proceeding.**
+3. **Detect existing code (brownfield detection):**
+   ```bash
+   # Check for existing code files
+   CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
+   HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
+   HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
+   ```
+
+   **You MUST run all bash commands above using the Bash tool before proceeding.**
+</step>
+
+<step name="brownfield_offer">
+**If existing code detected and .planning/codebase/ doesn't exist:**
+
+Check the results from setup step:
+- If `CODE_FILES` is non-empty OR `HAS_PACKAGE` is "yes"
+- AND `HAS_CODEBASE_MAP` is NOT "yes"
+
+Use AskUserQuestion:
+- header: "Existing Code"
+- question: "I detected existing code in this directory. Would you like to map the codebase first?"
+- options:
+  - "Map codebase first" - Run /gsd:map-codebase to understand existing architecture (Recommended)
+  - "Skip mapping" - Proceed with project initialization
+
+**If "Map codebase first":**
+```
+Run `/gsd:map-codebase` first, then return to `/gsd:new-project`
+```
+Exit command.
+
+**If "Skip mapping":** Continue to question step.
+
+**If no existing code detected OR codebase already mapped:** Continue to question step.
 </step>
 
 <step name="question">
@@ -140,6 +173,7 @@ Project initialized:
 
 - Project: .planning/PROJECT.md
 - Config: .planning/config.json (mode: [chosen mode])
+[If .planning/codebase/ exists:] - Codebase: .planning/codebase/ (7 documents)
 
 ---
 

commands/gsd/plan-phase.md

@@ -39,6 +39,9 @@ Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not pr
 
 **Load phase context if exists (created by /gsd:discuss-phase):**
 Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
+
+**Load codebase context if exists:**
+Check for `.planning/codebase/` and load relevant documents based on phase type.
 </context>
 
 <process>

get-shit-done/workflows/execute-phase.md

@@ -1148,6 +1148,52 @@ EOF
 For commit message conventions and git workflow patterns, see ~/.claude/get-shit-done/references/git-integration.md
 </step>
 
+<step name="update_codebase_map">
+**If .planning/codebase/ exists AND files were modified:**
+
+Check if execution modified significant code:
+
+```bash
+# Get list of code files modified in this plan
+MODIFIED_CODE=$(git diff --name-only HEAD~1 2>/dev/null | grep -E '\.(ts|js|py|go|rs|swift|java)$' | grep -v node_modules)
+```
+
+**If significant modifications (>3 code files changed):**
+
+Determine which codebase documents may need update based on what changed:
+
+| Changed Files | Documents to Update |
+|--------------|-------------------|
+| New directories created | STRUCTURE.md |
+| Package dependencies changed | STACK.md, INTEGRATIONS.md |
+| New patterns introduced | ARCHITECTURE.md, CONVENTIONS.md |
+| Test files added/changed | TESTING.md |
+| Config files changed | STACK.md |
+| External service integration | INTEGRATIONS.md |
+
+**Update strategy (incremental, not full remap):**
+
+For each document needing update:
+1. Read current document
+2. Identify what changed (new entries, removed entries, modified sections)
+3. Apply minimal edits to reflect new state
+4. Keep document under 100 lines (summarize if needed)
+
+**Commit codebase updates:**
+```bash
+git add .planning/codebase/*.md
+git commit --amend --no-edit  # Include in plan commit
+```
+
+**If no significant changes:**
+Skip codebase update - map is still current.
+
+**If .planning/codebase/ doesn't exist:**
+Skip this step - no codebase map to update.
+
+**Note:** Full remap via `/gsd:map-codebase` is available if incremental updates become stale.
+</step>
+
 <step name="check_phase_issues">
 **Check if issues were created during this phase:**
 
@@ -1330,4 +1376,5 @@ All [Y] plans finished.
 - SUMMARY.md created with substantive content
 - STATE.md updated (position, decisions, issues, session)
 - ROADMAP.md updated
+- If codebase map exists: map updated with execution changes (or skipped if no significant changes)
   </success_criteria>

get-shit-done/workflows/plan-phase.md

@@ -96,6 +96,44 @@ Options:
 This ensures planning has full project context.
 </step>
 
+<step name="load_codebase_context">
+Check if codebase map exists:
+
+```bash
+ls .planning/codebase/*.md 2>/dev/null
+```
+
+**If .planning/codebase/ exists:**
+
+Determine which codebase documents are relevant based on phase goal:
+
+| Phase Keywords | Load These Documents |
+|----------------|---------------------|
+| UI, frontend, components, layout | CONVENTIONS.md, STRUCTURE.md |
+| API, backend, endpoints, routes | ARCHITECTURE.md, CONVENTIONS.md |
+| database, schema, models, migration | ARCHITECTURE.md, STACK.md |
+| testing, tests, coverage | TESTING.md, CONVENTIONS.md |
+| integration, external, API, service | INTEGRATIONS.md, STACK.md |
+| refactor, cleanup, debt | CONCERNS.md, ARCHITECTURE.md |
+| setup, config, infrastructure | STACK.md, STRUCTURE.md |
+| (default - load minimal set) | STACK.md, ARCHITECTURE.md |
+
+Read the relevant documents and summarize key constraints for this phase:
+- From STACK.md: Technologies that must be used
+- From ARCHITECTURE.md: Patterns that must be followed
+- From CONVENTIONS.md: Code style requirements
+- From CONCERNS.md: Issues to avoid or address
+
+**Add to planning context:**
+Track codebase constraints for inclusion in PLAN.md context section:
+- Which documents loaded
+- Key constraints extracted
+- Patterns to follow
+
+**If .planning/codebase/ doesn't exist:**
+Skip this step - no codebase map available.
+</step>
+
 <step name="identify_phase">
 Check roadmap for phases:
 ```bash
@@ -651,6 +689,16 @@ Output: [What artifacts will be created by this plan]
 @.planning/ROADMAP.md
 @.planning/STATE.md
 
+[If codebase map exists (from /gsd:map-codebase):]
+@.planning/codebase/STACK.md
+@.planning/codebase/ARCHITECTURE.md
+[Add other relevant docs based on phase type - see load_codebase_context step]
+
+**Codebase constraints:**
+- [Extracted constraints from codebase documents]
+- [Technologies that must be used]
+- [Patterns that must be followed]
+
 [If comprehensive ecosystem research exists (from /gsd:research-phase):]
 @.planning/phases/XX-name/{phase}-RESEARCH.md