[Extension Proposal] Brownfield Bootstrap: SDD Workflow for Existing (Brownfield) Projects

[wcpaxx]

Summary

I've created an extension command /speckit.brownfield-bootstrap that helps bring existing (brownfield) projects into the spec-kit SDD workflow. This extension addresses a gap in the current spec-kit toolchain: while specify init works great for greenfield projects, it creates generic templates that don't reflect the actual architecture, tech stack, and coding conventions of existing codebases.

The Problem

When teams want to adopt spec-kit's Specification-Driven Development workflow for their existing projects, they face several challenges:

1. Generic templates don't fit: The standard specify init creates templates that don't reflect the project's actual tech stack, architecture patterns, or coding conventions
2. Manual constitution creation is tedious: Teams must manually analyze their codebase and create a constitution from scratch
3. Multi-module projects are complex: Projects with Maven/Gradle multi-module, Monorepo structures need module-level guidance for code placement
4. No reverse-engineering support: There's no automated way to extract architectural DNA from existing code

Brownfield Project Special Considerations

1. Respect existing architecture: Don't try to "improve" existing architecture, accurately reflect it
2. Tech stack lock: Brownfield project tech stack is established fact, constitution must anchor it
3. Gradual introduction: SDD workflow should seamlessly integrate into existing development process
4. Compatibility first: All generated code must be consistent with existing code style
5. No code duplication: Before creating new classes and methods, must first search for existing ones, only create new code if nothing reusable exists
6. Understand existing code: When understanding existing code is needed, use Repomix to generate/update skills for the project, command: repomix --skill-generate

The Solution

The brownfield-bootstrap extension solves these problems by:

1. 🔍 Automatic Project Discovery

   • Scans project structure to identify tech stack, frameworks, and patterns
   • Recognizes common architectural patterns (MVC, Hexagonal, Microservices, etc.)
   • Extracts coding conventions from config files and code samples

2. 📋 Multi-Module Project Support

   • Full support for Maven/Gradle multi-module projects
   • Node.js Monorepo with workspaces, Go Workspace, Rust Workspace, Python Monorepo
   • Automatic module responsibility mapping and dependency analysis
   • Code placement decision trees for each module

3. 📄 Customized Constitution & Templates

   • Generates project constitution reflecting actual project principles
   • Creates templates adapted to specific tech stack and coding style
   • Tech stack anchoring ensures consistency across all specs

4. 🧪 TDD Enforcement

   • Built-in Test-Driven Development discipline
   • Red-Green-Refactor cycle embedded in all templates

Workflow Comparison

Aspect	Greenfield (specify init)	Brownfield (This Extension)
Starting Point	Empty project	Existing codebase
Tech Stack	You choose	Auto-detected and locked
Architecture	You design	Reverse-engineered
Templates	Generic	Project-specific
Constitution	Minimal	Comprehensive from code analysis
Multi-module	Basic	Full module mapping

Example Usage

/speckit.brownfield-bootstrap

Or with specific focus:

/speckit.brownfield-bootstrap Focus on the user authentication module

The command generates:

• .specify/memory/constitution.md - Project constitution with extracted principles
• .specify/templates/spec-template.md - Customized spec template
• .specify/templates/plan-template.md - Customized plan template
• .specify/templates/tasks-template.md - Customized tasks template

Repository

The extension is available at: https://github.com/wcpaxx/spec-kit-brownfield-extensions

Both English and Chinese versions are provided:

• speckit.brownfield-bootstrap.md

Installation

Simply copy the command file to your AI tool's commands directory:

# For Claude Code
cp speckit.brownfield-bootstrap.md .claude/commands/

# For Cursor
cp speckit.brownfield-bootstrap.md .cursor/commands/

Compatibility

• ✅ spec-kit v0.0.18+ (uses /speckit. prefix)
• ✅ Claude Code, Cursor, GitHub Copilot, Windsurf, and other AI coding tools
• ✅ All major project types (single module, multi-module, monorepo)

Discussion Points

1. Would this be a valuable addition to the spec-kit ecosystem?
2. Should this be considered for inclusion in the core spec-kit toolchain?
3. Any suggestions for improving the project discovery or template generation?

Related

• Similar to the approach in spec-kit-extensions which provides workflows for bugfix, modify, refactor, etc.
• Complements the existing specify init by handling the brownfield project use case

---

Looking forward to feedback from the spec-kit community! 🚀