From 00623e53d8871dc95274475b08a76fc05464e45c Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Thu, 18 Dec 2025 09:26:26 -0600
Subject: [PATCH] docs: add brownfield/existing projects section to README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Explains map-codebase as starting point
- Lists 7 codebase documents created
- Shows workflow: map → new-project → continue as normal
- Keeps it concise, doesn't repeat greenfield content

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/README.md b/README.md
index 38b761b62..5858b35a7 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,42 @@ Ship your MVP in a day. Add features. Insert hotfixes. The system stays modular
 
 ---
 
+## Existing Projects (Brownfield)
+
+Already have code? Start here instead.
+
+### 1. Map the codebase
+
+```
+/gsd:map-codebase
+```
+
+Spawns parallel agents to analyze your code. Creates `.planning/codebase/` with 7 documents:
+
+- **STACK.md** — Languages, frameworks, dependencies
+- **ARCHITECTURE.md** — Patterns, layers, data flow
+- **STRUCTURE.md** — Directory layout, where things live
+- **CONVENTIONS.md** — Code style, naming patterns
+- **TESTING.md** — Test framework, patterns
+- **INTEGRATIONS.md** — External services, APIs
+- **CONCERNS.md** — Tech debt, known issues, fragile areas
+
+### 2. Initialize project
+
+```
+/gsd:new-project
+```
+
+Same as greenfield, but the system knows your codebase. Questions focus on what you're adding/changing, not starting from scratch.
+
+### 3. Continue as normal
+
+From here, it's the same: `/gsd:create-roadmap` → `/gsd:plan-phase` → `/gsd:execute-plan`
+
+The codebase docs load automatically during planning. Claude knows your patterns, conventions, and where to put things.
+
+---
+
 ## Why It Works
 
 ### Context Engineering