Skip to content

About

spec-kit Brownfield Bootstrap Extension

Resources

Contributing

Stars

33 stars

Watchers

1 watching

Forks

Latest commit

 

History

20 Commits

Folders and files

Repository files navigation

spec-kit Brownfield Extensions

Important

🌱 For Brownfield (Existing) Projects

This repository provides tools for existing projects to adopt spec-kit's Specification-Driven Development (SDD) workflow.

If you're starting a new project from scratch, use the standard specify init command instead.

Bootstrap your existing codebase into spec-kit's SDD workflow with automatic project analysis and customized template generation.

License: MIT

Repository Structure

This repository contains two independent components:

spec-kit-brownfield-extensions/
├── extension/                   # spec-kit Extension
│   ├── extension.yml            # Extension manifest (id: brownfield-bootstrap)
│   ├── README.md                # Extension documentation
│   ├── AI-INSTALL-GUIDE.md      # AI installation instructions
│   ├── config-template.yml      # Configuration template
│   └── commands/
│       ├── init.md              # English bootstrap command
│       └── init-cn.md           # Chinese bootstrap command
│
└── skills/                      # Claude Code Skills
    ├── README.md                # Skills documentation
    ├── AI-INSTALL-GUIDE.md      # AI installation instructions
    ├── brownfield-skills/       # Developer expertise generator
    │   ├── SKILL.md
    │   └── references/
    │       ├── analysis-guide.md
    │       ├── templates.md
    │       └── templates-cn.md
    └── brownfield-ears/         # EARS requirements converter
        ├── SKILL.md
        └── references/
            ├── conversion-guide.md
            ├── document-template.md
            └── examples.md

Components Overview

Component Type Purpose
extension/ spec-kit Extension Bootstrap SDD workflow for existing projects
skills/brownfield-skills Claude Code Skill Generate senior developer expertise
skills/brownfield-ears Claude Code Skill Convert requirements to EARS format

📊 Workflow Overview

This extension provides tools that extend the standard spec-kit SDD workflow for brownfield projects:

┌─────────────────────────────────────────────────────────────────────────────────┐
│                     Extended SDD Workflow for Brownfield Projects                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│   [Existing Project]                                                             │
│         │                                                                        │
│         ▼                                                                        │
│   ┌─────────────────────────────┐     ┌─────────────────────────────┐           │
│   │ /speckit.brownfield-        │     │ brownfield-skills           │           │
│   │ bootstrap.init              │     │ (Generate Developer Skills) │           │
│   │ (Bootstrap SDD Workflow)    │     └─────────────────────────────┘           │
│   └───────────┬─────────────────┘                                               │
│               │                                                                  │
│               ▼                                                                  │
│   ┌─────────────────────────────┐     ┌─────────────────────────────┐           │
│   │ User Requirements           │────▶│ brownfield-ears             │  Optional │
│   │ (Natural Language)          │     │ (EARS Format Conversion)    │  Pre-step │
│   └─────────────────────────────┘     └───────────┬─────────────────┘           │
│                                                   │                              │
│                                                   ▼                              │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │                    Standard spec-kit SDD Workflow                        │   │
│   │  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐              │   │
│   │  │ /speckit │──▶│ /speckit │──▶│ /speckit │──▶│ /speckit │              │   │
│   │  │ .specify │   │ .plan    │   │ .tasks   │   │.implement│              │   │
│   │  └──────────┘   └──────────┘   └──────────┘   └──────────┘              │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

Tools Provided

Tool Type Purpose When to Use
/speckit.brownfield-bootstrap.init Extension Command Initialize SDD for existing projects First time adopting spec-kit
brownfield-skills Skill Generate senior developer expertise Enable AI to master project conventions
brownfield-ears Skill Convert requirements to EARS format Before /speckit.specify for complex requirements

Quick Start

Install Extension

# Using spec-kit extension system
specify extension add --dev /path/to/spec-kit-brownfield-extensions/extension

# Or manually copy commands
cp extension/commands/init.md .claude/commands/speckit.brownfield-bootstrap.init.md
cp extension/commands/init-cn.md .claude/commands/speckit.brownfield-bootstrap.init-cn.md

Install Skills

mkdir -p .claude/skills
cp -r skills/brownfield-skills .claude/skills/
cp -r skills/brownfield-ears .claude/skills/

For AI Agents

See the AI installation guides:

Usage

1. Bootstrap Your Project

# Run the init command
/speckit.brownfield-bootstrap.init

# Or Chinese version
/speckit.brownfield-bootstrap.init-cn

2. Review Generated Files

File Path Description
Project Constitution .specify/memory/constitution.md Core principles and constraints
Spec Template .specify/templates/spec-template.md Feature specification template
Plan Template .specify/templates/plan-template.md Implementation plan template
Tasks Template .specify/templates/tasks-template.md Task breakdown template

3. Start SDD Workflow

/speckit.specify "Add user profile image upload"
/speckit.plan
/speckit.tasks
/speckit.implement

Command Reference

Command Description
/speckit.brownfield-bootstrap.init Initialize SDD for existing projects (English)
/speckit.brownfield-bootstrap.init-cn 初始化棕地项目的SDD工作流 (Chinese)

Aliases (Backward Compatibility)

Old Name New Name
speckit.brownfield.bootstrap speckit.brownfield-bootstrap.init
speckit.brownfield.bootstrap-cn speckit.brownfield-bootstrap.init-cn

Key Features

🔍 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

📋 Multi-Module Project Support

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

🧪 TDD Enforcement

  • Built-in Test-Driven Development discipline
  • Red-Green-Refactor cycle embedded in all templates
  • Coverage requirements and verification checkpoints

📁 Correct Directory Structure

  • Ensures all files are generated in spec-kit compatible locations
  • Pre-output self-check list to prevent common path mistakes
  • Clear path reference standards

🧠 Developer Skills Generation

The brownfield-skills skill generates Project Skills that make Claude Code behave like a senior developer who has been maintaining your project for years.

.claude/skills/brownfield-developer-[project-name]/
├── SKILL.md                    # Entry point
└── references/
    ├── architecture.md         # Architecture and layering
    ├── tech-stack.md           # Tech stack and versions
    ├── coding-conventions.md   # Coding standards
    ├── module-structure.md     # Module responsibilities
    └── development-patterns.md # Development patterns

📝 EARS Requirements Conversion

The brownfield-ears skill converts natural language requirements into EARS (Easy Approach to Requirements Syntax) format.

Pattern Template Example
Ubiquitous The system shall <function> The system shall encrypt all user passwords
Event-Driven When <trigger>, the system shall <response> When user clicks submit, the system shall validate input
State-Driven If <state>, then the system shall <behavior> If user is admin, then the system shall show admin panel

Compatibility

AI Agents

  • ✅ Claude Code (fully tested)
  • ✅ Cursor (tested)
  • ✅ GitHub Copilot (via instructions)
  • ✅ Windsurf (via project rules)

spec-kit Versions

  • ✅ spec-kit v0.1.0+
  • ✅ Fully compatible with core spec-kit workflows

Project Types

  • ✅ Single module projects
  • ✅ Multi-module Maven/Gradle projects
  • ✅ Node.js Monorepo (with workspaces)
  • ✅ Go Workspace, Rust Workspace, Python Monorepo

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE for details.

Credits

Support

About

spec-kit Brownfield Bootstrap Extension

Resources

Contributing

Stars

33 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors