Skip to main content
Alpha Version: specs.md does not yet fully support brownfield applications as defined in the AI-DLC process. Currently, it relies on the underlying LLM model’s capabilities for existing codebase analysis. Full brownfield support is coming soon.

​
Prerequisites

  • Node.js 18+ installed
  • An AI coding tool (Claude Code, Cursor, GitHub Copilot, etc.)
  • A project to work on (greenfield recommended for AI-DLC)

​
Installation

1

Install specs.md

2

Select AI-DLC flow

When prompted, select AI-DLC as your development flow:
3

Choose your AI tool

Select your preferred AI coding tool for agent configuration

​
Initialize Your Project

Open your AI coding tool and start the Master Agent:
Then type:
This guides you through establishing:
1

Tech Stack

Languages, frameworks, databases, infrastructure
2

Coding Standards

Formatting, linting, naming, testing strategy
3

System Architecture

Architecture style, API design, state management
4

UX Guide (Optional)

Design system, styling, accessibility
5

API Conventions (Optional)

API style, versioning, response formats

​
Create Your First Intent

An Intent is your high-level goal:
  • “User authentication system”
  • “Product catalog with search”
  • “Payment processing integration”
The agent will:
  1. Ask clarifying questions to minimize ambiguity
  2. Elaborate into user stories and NFRs
  3. Define system context
  4. Decompose into loosely-coupled units

​
Plan and Execute Bolts

Each bolt goes through validated stages:

1. Domain Model

Model business logic using DDD principles

2. Technical Design

Apply patterns and make architecture decisions

3. ADR Analysis

Document significant decisions (optional)

4. Implement

Generate production code

5. Test

Verify correctness with automated tests
Human validation happens at each checkpoint. This ensures errors are caught early before cascading downstream.

​
Project Structure After Init

​
Command Reference

​
Troubleshooting

Agents are stateless—they read artifacts from Memory Bank at startup. Ensure artifacts are saved after each step.
Run bolt-status to check current stage. If validation failed, address the feedback and continue with bolt-start.
Bolts can be replanned with /specsmd-inception-agent bolt-replan. This creates a new bolt for the same stories.
Run /specsmd-master-agent analyze-context to see all intents and their status.

​
Next Steps

AI-DLC Overview

Understand the full AI-DLC methodology

Core Concepts

Deep dive into Intents, Units, and Bolts

Agents

Learn about the four specialized agents

Bolt Types

Choose between DDD and Simple bolts