msd-core/.planning/ROADMAP.md

Roadmap: GSD Brownfield Support

Overview

Add comprehensive brownfield support to GSD. Users adopting GSD for existing codebases will have a systematic way to capture architectural knowledge before planning begins. A new /gsd:map-codebase workflow will produce structured .planning/codebase/ documents that stay current as plans execute.

Domain Expertise

None - this is internal GSD development following existing command/workflow/template patterns.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work

• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

• Phase 1: Templates & Structure - Create codebase map templates and folder structure

• Phase 2: Map Codebase Command - Build /gsd:map-codebase with parallel Explore agents

• Phase 3: Integration - Wire brownfield support into existing GSD workflows

Phase Details

Phase 1: Templates & Structure

Goal: Create templates for all codebase map document types and define the folder structure Depends on: Nothing (first phase) Research: Unlikely (established GSD template patterns) Plans: TBD

Documents to template:

• stack.md (languages, frameworks, dependencies)
• architecture.md (patterns, layers, data flow)
• structure.md (directory layout, key files)
• conventions.md (coding standards, naming)
• testing.md (test setup, patterns)
• integrations.md (external services, APIs)
• concerns.md (tech debt, known issues)

Phase 2: Map Codebase Command

Goal: Build the /gsd:map-codebase slash command with parallel Explore agent workflow Depends on: Phase 1 Research: Unlikely (using existing Explore agent patterns, GSD workflow conventions) Plans: TBD

Components:

• Slash command: commands/gsd/map-codebase.md
• Workflow: get-shit-done/workflows/map-codebase.md
• Parallel Explore agent orchestration
• Output to .planning/codebase/

Phase 3: Integration

Goal: Wire brownfield support into existing GSD workflows Depends on: Phase 2 Research: Unlikely (modifying existing GSD commands, established patterns) Plans: TBD

Integration points:

• /gsd:new-project - detect existing code, offer to map first
• /gsd:plan-phase - load relevant codebase context automatically
• Post-execution - update codebase map after plan execution

Phase 4: Plan-Phase Optimizations

Goal: Reduce context usage in /gsd:plan-phase by ~37% through file consolidation and verbosity reduction Depends on: Phase 3 Research: Unlikely (internal optimization of existing files) Plans: TBD

Optimization targets:

• Merge cli-automation.md into checkpoints.md (-15KB)
• Compress plan-format.md to reference card (-7KB)
• Trim scope-estimation.md verbosity (-6KB)
• Streamline plan-phase.md workflow (-9KB)

Phase 5: TDD Instructions

Goal: Add TDD guidance to GSD so Claude uses test-driven development when appropriate and beneficial Depends on: Phase 4 Research: Unlikely (established TDD patterns, GSD integration points clear) Plans: 2 plans

Plans:

• 05-01: TDD Foundation - Create tdd.md reference, add TDD annotation to plan-format.md
• 05-02: TDD Integration - Update plan-phase.md detection, execute-phase.md execution flow

Phase 6: Frontmatter System Upgrade

Goal: Add YAML frontmatter to SUMMARY.md enabling automatic context assembly via dependency graph Depends on: Phase 5 Plans: 2 plans

Plans:

• 06-01: Frontmatter Schema - Add comprehensive YAML frontmatter to summary.md template with dependency metadata
• 06-02: Intelligent Selection - Implement frontmatter-based context assembly in plan-phase.md

Details: Transform planning from "Claude guesses which summaries to read" to "System automatically assembles optimal context" by:

• Adding frontmatter with subsystem, requires/provides/affects, tech-stack, key-files, key-decisions
• Scanning all summary frontmatter (fast - first ~25 lines each)
• Building dependency graph to auto-select relevant prior phases
• Extracting context from frontmatter before reading full summaries
• Making context assembly deterministic and optimal

Phase 7: Backfill Existing Summaries With Frontmatter

Goal: Backfill YAML frontmatter with dependency graph metadata to Phase 1-6 historical summaries Depends on: Phase 6 Plans: 1 plan

Plans:

• 07-01: Backfill frontmatter to all Phase 1-5 summaries (10 files)

Details: Enable intelligent context assembly for all historical phases by adding consistent frontmatter with subsystem categorization, dependency graph (requires/provides/affects), tech tracking, key decisions, and patterns established.

Phase 8: Improve Roadmap System

Goal: [To be planned] Depends on: Phase 7 Research: Unlikely (internal GSD workflow improvements) Plans: TBD

Plans:

• TBD (run /gsd:plan-phase 8 to break down)

Details: [To be added during planning]

Phase 9: Integrate Verify-Work

Goal: Properly integrate /gsd:verify-work into GSD with workflow delegation, templates, and /gsd:plan-fix command Depends on: Phase 8 Research: Unlikely (refactoring contributed command to match GSD patterns) Plans: TBD

Components:

• Refactor commands/gsd/verify-work.md to GSD style (workflow delegation)
• Create workflows/verify-work.md for UAT logic
• Create templates/uat-issues.md for phase-scoped issues format
• Create commands/gsd/plan-fix.md for planning fixes from UAT issues
• Update commands/gsd/progress.md to offer plan-fix when issues exist
• Update README.md with new commands

Details: Community contribution from OracleGreyBeard. Original command works but doesn't follow GSD patterns (no workflow delegation, inline templates, verbose steps). Refactor to match conventions, then add /gsd:plan-fix to complete the verify → fix loop.

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6

Phase	Plans Complete	Status	Completed
1. Templates & Structure	3/3	Complete	2025-12-17
2. Map Codebase Command	2/2	Complete	2025-12-17
3. Integration	1/1	Complete	2025-12-17
4. Plan-Phase Optimizations	2/2	Complete	2025-12-29
5. TDD Instructions	2/2	Complete	2025-12-31
6. Frontmatter System Upgrade	2/2	Complete	2026-01-05
7. Backfill Existing Summaries	1/1	Complete	2026-01-05
8. Improve Roadmap System	1/1	Complete	2026-01-05
9. Integrate Verify-Work	1/?	In Progress	-