198 lines
8.8 KiB
Markdown
198 lines
8.8 KiB
Markdown
# Example Session: /adopt — Brownfield Project Onboarding
|
|
|
|
**Context:** Developer has been building a game for 3 months before discovering this agent system. They have code, some design docs, and rough notes — but nothing in the right format for the skills to use.
|
|
|
|
**Starting State:**
|
|
- `src/gameplay/` — ~4000 lines of Godot 4.6 GDScript
|
|
- `design/` — 3 markdown files with rough design notes (not in GDD template format)
|
|
- No `design/gdd/` directory
|
|
- No `docs/architecture/` directory
|
|
- No `production/` directory
|
|
- No `design/gdd/systems-index.md`
|
|
- CLAUDE.md exists (engine configured: Godot 4.6)
|
|
|
|
**Session Duration:** ~30 minutes
|
|
**Turns:** 8
|
|
**Outcome:** Adoption plan written, most urgent gap (missing system index) fixed immediately
|
|
|
|
---
|
|
|
|
## Turn 1: User Invokes /adopt
|
|
|
|
**User:**
|
|
> /adopt
|
|
|
|
## Turn 2: Agent Detects Project State
|
|
|
|
**Agent (technical-director, via /adopt, context: fork):**
|
|
> Running brownfield audit...
|
|
>
|
|
> **Phase 1: Project State Detection**
|
|
>
|
|
> | Artifact Category | Found | Notes |
|
|
> |------------------|-------|-------|
|
|
> | Engine configuration | ✅ | Godot 4.6 in CLAUDE.md |
|
|
> | Source code | ✅ | ~4000 lines in `src/gameplay/` |
|
|
> | Design docs | ⚠️ | 3 files in `design/`, not in GDD format |
|
|
> | Architecture docs | ❌ | `docs/architecture/` missing |
|
|
> | Systems index | ❌ | `design/gdd/systems-index.md` missing |
|
|
> | Production tracking | ❌ | `production/` directory missing |
|
|
> | Sprint/story files | ❌ | None |
|
|
>
|
|
> **Phase 2: Format Audit (existing files)**
|
|
>
|
|
> Checking internal structure of the 3 design files...
|
|
>
|
|
> *`design/combat-notes.md`:*
|
|
> - Has informal notes, no GDD template sections
|
|
> - Contains: some rule descriptions, a damage formula, rough balance numbers
|
|
> - Missing from GDD template: Overview, Player Fantasy, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria (6 of 8 sections)
|
|
>
|
|
> *`design/crafting-ideas.md`:*
|
|
> - Brainstorm-style notes, no structure
|
|
> - No formulas, no acceptance criteria
|
|
> - Represents early concept thinking — useful as input for a GDD, not yet a GDD
|
|
>
|
|
> *`design/inventory.md`:*
|
|
> - Closest to a GDD — has Overview and Rules sections
|
|
> - Missing: Player Fantasy, Formulas, Edge Cases, Tuning Knobs, Acceptance Criteria (5 of 8 sections)
|
|
>
|
|
> **Phase 3: Gap Classification**
|
|
>
|
|
> | Gap | Severity | Reason |
|
|
> |-----|----------|--------|
|
|
> | No systems index | BLOCKING | `/design-system`, `/create-stories`, `/gate-check` all require it |
|
|
> | GDD files not in template format | HIGH | Skills cannot reference TR-IDs from malformed GDDs |
|
|
> | No architecture docs | HIGH | Cannot run `/architecture-review` or `/create-control-manifest` |
|
|
> | No production tracking | MEDIUM | Sprint and story skills won't work, but not needed until production phase |
|
|
> | `design/crafting-ideas.md` — pre-GDD content | LOW | Useful as input; needs full GDD authoring before it blocks anything |
|
|
|
|
## Turn 3: Agent Presents the Migration Plan
|
|
|
|
**Agent:**
|
|
> **Phase 4: Migration Plan**
|
|
>
|
|
> 7 ordered steps to bring your project into full alignment. NEVER overwrites your existing content — each step fills gaps only.
|
|
>
|
|
> | # | Step | Skill | Priority | Notes |
|
|
> |---|------|-------|----------|-------|
|
|
> | 1 | Create `design/gdd/systems-index.md` | `/map-systems` or `/adopt` inline | BLOCKING | Unblocks all downstream skills |
|
|
> | 2 | Retrofit `design/inventory.md` → GDD format | `/design-system retrofit design/inventory.md` | HIGH | Adds 5 missing sections, keeps your existing content |
|
|
> | 3 | Retrofit `design/combat-notes.md` → GDD format | `/design-system retrofit design/combat-notes.md` | HIGH | Adds 6 missing sections |
|
|
> | 4 | Convert `design/crafting-ideas.md` → full GDD | `/design-system crafting` (new authoring, uses ideas as input) | MEDIUM | Not a retrofit — too informal to retrofit |
|
|
> | 5 | Create architecture ADRs from existing code | `/reverse-document` + `/architecture-decision` | HIGH | Captures decisions already made in code |
|
|
> | 6 | Create master architecture document | `/create-architecture` | HIGH | After ADRs |
|
|
> | 7 | Set up production tracking | `/sprint-plan new` | MEDIUM | After architecture phase |
|
|
>
|
|
> **Important:** Step 1 must happen before any other step. Everything else can be done in parallel or reordered based on your priorities.
|
|
>
|
|
> May I write this plan to `docs/adoption-plan-2026-03-12.md`?
|
|
|
|
**User:**
|
|
> Yes. Write it.
|
|
|
|
**Agent writes adoption plan.**
|
|
|
|
## Turn 4: Agent Offers to Fix the Most Urgent Gap
|
|
|
|
**Agent:**
|
|
> The BLOCKING gap is the missing `design/gdd/systems-index.md`.
|
|
>
|
|
> I can create one now by reading your existing code and design docs to infer what systems you've built. This is faster than running `/map-systems` from scratch — I'll populate it based on what already exists, then you confirm or adjust.
|
|
>
|
|
> Would you like me to do that now?
|
|
|
|
**User:**
|
|
> Yes, do it.
|
|
|
|
## Turn 5: Agent Reads Codebase and Drafts Systems Index
|
|
|
|
**Agent:**
|
|
> Reading `src/gameplay/` to infer systems...
|
|
>
|
|
> Found these system boundaries in the code:
|
|
>
|
|
> - `src/gameplay/combat/` — damage calculation, hit detection, status effects
|
|
> - `src/gameplay/inventory/` — item management, weight, stacks
|
|
> - `src/gameplay/crafting/` — recipe lookup, result generation (references inventory)
|
|
> - `src/gameplay/movement/` — CharacterBody2D, terrain modifiers (referenced by combat for positioning)
|
|
> - `src/gameplay/ui/` — HUD, inventory screen, dialogue box
|
|
> - `src/gameplay/world/` — tile map, terrain types, chunk loading
|
|
>
|
|
> **Draft systems index:**
|
|
>
|
|
> | System | Category | Priority | Dependencies | GDD Status |
|
|
> |--------|----------|----------|--------------|------------|
|
|
> | Movement | Foundation | MVP | None | ❌ Missing |
|
|
> | World/Terrain | Foundation | MVP | Movement | ❌ Missing |
|
|
> | Combat | Core | MVP | Movement | ⚠️ Needs retrofit |
|
|
> | Inventory | Core | MVP | None | ⚠️ Needs retrofit |
|
|
> | Crafting | Feature | MVP | Inventory | ❌ Pre-GDD only |
|
|
> | UI / HUD | Presentation | MVP | Combat, Inventory, Movement | ❌ Missing |
|
|
>
|
|
> Does this look right? Anything I missed or miscategorized?
|
|
|
|
**User:**
|
|
> Looks right. Add a Stamina system — it's in combat/ but should be its own system.
|
|
|
|
**Agent:**
|
|
> Added Stamina as a Core / MVP system:
|
|
>
|
|
> | Stamina | Core | MVP | Movement, Combat | ❌ Missing |
|
|
>
|
|
> Updated dependency: Movement depends on Stamina (movement drains it).
|
|
>
|
|
> May I write this to `design/gdd/systems-index.md`?
|
|
|
|
## Turn 6: User Approves
|
|
|
|
**User:**
|
|
> Yes
|
|
|
|
**Agent writes `design/gdd/systems-index.md`.**
|
|
|
|
## Turn 7: Agent Shows What's Now Unlocked
|
|
|
|
**Agent:**
|
|
> `design/gdd/systems-index.md` created.
|
|
>
|
|
> **BLOCKING gap resolved.** The following skills can now run:
|
|
>
|
|
> - ✅ `/design-system [name]` — guided GDD authoring for any system
|
|
> - ✅ `/design-system retrofit [path]` — fill missing sections in existing docs
|
|
> - ✅ `/gate-check` — now has a systems index to validate
|
|
> - ✅ `/help` — can now show correct phase workflow
|
|
>
|
|
> **Recommended next steps (from adoption plan):**
|
|
>
|
|
> 1. Run `/design-system retrofit design/inventory.md` — your most complete existing doc, easiest win
|
|
> 2. Run `/design-system retrofit design/combat-notes.md`
|
|
> 3. Run `/design-system crafting` — author crafting GDD using your ideas file as input
|
|
>
|
|
> After those 3, you'll have 5 of 7 systems with complete GDDs. Then run `/review-all-gdds` to catch cross-system consistency issues before architecture work.
|
|
|
|
## Turn 8: User Confirms Plan
|
|
|
|
**User:**
|
|
> Perfect. I'll start with the inventory retrofit.
|
|
|
|
**Agent:**
|
|
> Run:
|
|
> ```
|
|
> /design-system retrofit design/inventory.md
|
|
> ```
|
|
>
|
|
> The skill will detect your existing Overview and Rules sections, show you which of the 8 sections are missing, and run the section cycle only for the gaps. Your existing content won't be touched.
|
|
|
|
---
|
|
|
|
## What This Example Demonstrates
|
|
|
|
- **FORMAT audit, not existence audit**: `/adopt` doesn't just check whether files exist — it checks whether their internal structure matches what skills expect. A file named `gdd.md` with no template sections is flagged as a gap.
|
|
- **Migration, not replacement**: existing content is never overwritten. The plan fills gaps only.
|
|
- **BLOCKING gaps surface first**: the missing systems index is identified as BLOCKING because it prevents the most skills from functioning.
|
|
- **Inline creation of the urgent gap**: rather than just reporting the gap, the agent offers to fix it immediately in the same session.
|
|
- **Inferred from code**: the systems index is bootstrapped from the codebase structure, not written from scratch — brownfield code already contains the answer.
|
|
- **Retrofit vs. new authoring**: `/design-system retrofit` handles existing-but-incomplete docs; full `/design-system` handles net-new docs. The adoption plan distinguishes which applies to each file.
|
|
- **Context: fork**: `/adopt` runs in a forked context to avoid polluting the main session with large file reads across the whole codebase.
|