AI-DLC Quick Start

Get up and running with AI-DLC flow in minutes

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

   npx specsmd@latest install
   
2. Select AI-DLC flow

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

   ? Select a development flow:
   ❯ AI-DLC - Full methodology with DDD
     FIRE - Adaptive execution, brownfield & monorepo ready
     Simple - Spec generation only
   
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:

Claude Code

/specsmd-master-agent

Cursor

/specsmd-master-agent

Or use the @ prefix:

@specsmd-master-agent

GitHub Copilot

/specsmd-master-agent

Then type:

project-init

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”

/specsmd-inception-agent intent-create

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

# Plan bolts for your stories
/specsmd-inception-agent bolt-plan

# Execute a bolt
/specsmd-construction-agent bolt-start

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

memory-bank/                   # Created after project-init
├── intents/                   # Your captured intents
│   └── {intent-name}/
│       ├── requirements.md
│       ├── system-context.md
│       └── units/
├── bolts/                     # Bolt execution records
├── standards/                 # Project standards
│   ├── tech-stack.md
│   ├── coding-standards.md
│   └── ...
└── operations/                # Deployment context

Command Reference

Agent	Command	Purpose
Master	project-init	Initialize project with standards
Master	analyze-context	View current project state
Inception	intent-create	Create a new intent
Inception	bolt-plan	Plan bolts for stories
Construction	bolt-start	Start/continue executing a bolt
Construction	bolt-status	Check bolt progress
Operations	deploy	Deploy to environment

Troubleshooting

Agent doesn't remember context

Agents are stateless—they read artifacts from Memory Bank at startup. Ensure artifacts are saved after each step.

Bolt stuck in stage

Run bolt-status to check current stage. If validation failed, address the feedback and continue with bolt-start.

Want to restart a bolt

Bolts can be replanned with /specsmd-inception-agent bolt-replan. This creates a new bolt for the same stories.

Multiple intents exist

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