# Construction Agent
Source: https://specs.md/agents/construction-agent

Executes bolts through validated stages to produce tested code

## Overview

The **Construction Agent** handles the second phase of AI-DLC. It executes bolts through validated stages, producing tested, production-ready code.

## Invocation

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /specsmd-construction-agent
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-construction-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-construction-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    /specsmd-construction-agent
    ```
  </Tab>
</Tabs>

## Commands

| Command       | Purpose                            |
| ------------- | ---------------------------------- |
| `bolt-start`  | Start or continue executing a bolt |
| `bolt-status` | Check bolt progress                |
| `bolt-list`   | List all bolts                     |
| `bolt-replan` | Replan bolts if needed             |

## bolt-start

Starts or continues a bolt execution:

```
> bolt-start
```

If no bolt is in progress, the agent will:

1. Show available bolts from your plan
2. Let you select which to start
3. Begin the first stage

If a bolt is in progress:

1. Load current stage context
2. Continue from where you left off

### Stage Progression

For a DDD Construction bolt:

<Steps>
  <Step title="Domain Model">
    The agent helps you model business logic:

    * Identify aggregates and entities
    * Define value objects
    * Map domain events
    * Establish ubiquitous language

    **Gate**: Review and approve the domain model
  </Step>

  <Step title="Technical Design">
    The agent creates the technical design:

    * Choose implementation patterns
    * Define interfaces and contracts
    * Plan data structures
    * Make architecture decisions

    **Gate**: Review and approve the design
  </Step>

  <Step title="ADR Analysis (Optional)">
    For significant decisions:

    * Document context and problem
    * List options considered
    * Record decision and rationale

    **Gate**: Review and approve ADR
  </Step>

  <Step title="Implement">
    The agent generates production code:

    * Follow coding standards
    * Apply design patterns
    * Write clean, maintainable code

    **Gate**: Review generated code
  </Step>

  <Step title="Test">
    The agent creates and runs tests:

    * Unit tests for domain logic
    * Integration tests for interfaces
    * Acceptance tests for stories

    **Gate**: Verify all tests pass
  </Step>
</Steps>

### Example Session

```
User: bolt-start

Construction Agent: Available bolts for User Registration:

1. Registration Domain Model (DDD) - Not started
2. Email Validation (TDD) - Not started
3. Welcome Email (BDD) - Not started

Which bolt would you like to start?

User: 1

Construction Agent: Starting "Registration Domain Model" bolt.

## Stage 1: Domain Model

Let's model the user registration domain. Based on your 
requirements, I'll identify the key domain concepts.

### Aggregates
- **User**: The root aggregate representing a registered user

### Entities  
- **EmailAddress**: Validated email with confirmation status
- **Password**: Hashed password with strength validation

### Value Objects
- **UserId**: Unique identifier for users
- **RegistrationDate**: When the user registered

### Domain Events
- **UserRegistered**: Raised when registration completes
- **EmailConfirmed**: Raised when email is verified

Does this domain model look correct? 
[Approve] [Request Changes]

User: Approve

Construction Agent: Domain model approved. Moving to Technical Design...
```

## bolt-status

Check the current progress of bolts:

```
> bolt-status
```

Output shows:

```
Current Bolt: Registration Domain Model
Status: In Progress
Current Stage: Technical Design (2 of 5)
Completed Stages:
  ✓ Domain Model - Approved
  → Technical Design - In Progress
  ○ ADR Analysis
  ○ Implement  
  ○ Test

Time in bolt: 45 minutes
```

## bolt-list

List all bolts across the project:

```
> bolt-list
```

Output:

```
User Authentication / User Registration
  ✓ Registration Domain Model - Completed (2h 15m)
  → Email Validation - In Progress
  ○ Welcome Email - Not Started

User Authentication / User Login
  ○ Login Domain Model - Not Started
  ○ Session Handling - Not Started
```

## bolt-replan

Replan bolts when scope changes:

```
> bolt-replan user-authentication/user-registration
```

Use this when:

* New requirements were added
* Stories were split or combined
* Priorities changed
* Estimates were off

## Human Checkpoints

The Construction Agent's checkpoints are defined by the bolt type. Each bolt type has its own checkpoint structure.

### DDD Construction (5 checkpoints)

```mermaid actions={false} theme={null}
flowchart LR
    M(Model):::plan --> G1{{"✋"}}:::check
    G1 --> D(Design):::plan
    D --> G2{{"✋"}}:::check
    G2 --> A(ADR):::plan
    A --> G3{{"✋"}}:::check
    G3 --> I(Implement):::build
    I --> G4{{"✋"}}:::check
    G4 --> T(Test):::warn
    T --> G5{{"✋"}}:::check
    G5 --> Done((Done)):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Gate       | After Stage      | Purpose                                |
| ---------- | ---------------- | -------------------------------------- |
| **Gate 1** | Domain Model     | Validate domain concepts before design |
| **Gate 2** | Technical Design | Approve architecture before ADR        |
| **Gate 3** | ADR Analysis     | Confirm decisions documented           |
| **Gate 4** | Implement        | Review code before testing             |
| **Gate 5** | Test             | Verify all tests pass, bolt complete   |

### Simple Construction (3 checkpoints)

```mermaid actions={false} theme={null}
flowchart LR
    S(Spec):::plan --> G1{{"✋"}}:::check
    G1 --> I(Implement):::build
    I --> G2{{"✋"}}:::check
    G2 --> T(Test):::warn
    T --> G3{{"✋"}}:::check
    G3 --> Done((Done)):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Gate       | After Stage | Purpose                              |
| ---------- | ----------- | ------------------------------------ |
| **Gate 1** | Spec        | Validate requirements before coding  |
| **Gate 2** | Implement   | Review code before testing           |
| **Gate 3** | Test        | Verify all tests pass, bolt complete |

<Warning>
  You cannot proceed to the next stage without explicit approval. This is intentional - it catches errors before they cascade.
</Warning>

At each gate, you can:

* **Approve**: Move to the next stage
* **Request Changes**: Ask for modifications
* **Reject**: Go back to a previous stage

## Artifacts Generated

Each bolt produces artifacts in the Memory Bank:

<Tabs>
  <Tab title="DDD Construction">
    ```
    memory-bank/intents/{intent}/units/{unit}/bolts/{bolt}/
    ├── domain-model.md       # Stage 1 output
    ├── technical-design.md   # Stage 2 output
    ├── adr-001.md           # Stage 3 output (if applicable)
    ├── implementation/       # Stage 4 output
    │   ├── src/
    │   └── ...
    └── tests/               # Stage 5 output
        ├── unit/
        └── integration/
    ```
  </Tab>

  <Tab title="Simple Construction">
    ```
    memory-bank/intents/{intent}/units/{unit}/bolts/{bolt}/
    ├── spec.md              # Stage 1 output
    ├── implementation/       # Stage 2 output
    │   ├── src/
    │   └── ...
    └── tests/               # Stage 3 output
        ├── unit/
        └── integration/
    ```
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Complete Before Starting">
    Ensure Inception is complete before starting Construction. Missing requirements cause rework.
  </Accordion>

  <Accordion title="Review Carefully at Checkpoints">
    Checkpoints are your opportunity to catch issues. Don't rubber-stamp approvals.
  </Accordion>

  <Accordion title="Keep Bolts Focused">
    If a bolt is taking too long, the scope may be too big. Consider splitting.
  </Accordion>

  <Accordion title="Test Thoroughly">
    Don't skip the Test stage. Untested code is a liability.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bolt Taking Too Long">
    * Check if scope is too large
    * Consider splitting into multiple bolts
    * Use `bolt-replan` to adjust
  </Accordion>

  <Accordion title="Stage Rejections">
    * Review the feedback carefully
    * Make requested changes
    * Resubmit for approval
  </Accordion>

  <Accordion title="Context Lost">
    * Ensure previous bolt artifacts are saved
    * Check Memory Bank for missing files
    * Reload with `bolt-start`
  </Accordion>
</AccordionGroup>


# Inception Agent
Source: https://specs.md/agents/inception-agent

Captures intents, elaborates requirements, and decomposes into units

## Overview

The **Inception Agent** handles the first phase of AI-DLC. It captures your high-level goals (Intents), elaborates them into detailed requirements, and decomposes them into manageable Units.

## Invocation

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /specsmd-inception-agent
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-inception-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-inception-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    /specsmd-inception-agent
    ```
  </Tab>
</Tabs>

## Commands

| Command         | Purpose                       |
| --------------- | ----------------------------- |
| `intent-create` | Create a new intent           |
| `intent-list`   | List all intents              |
| `requirements`  | Elaborate intent requirements |
| `context`       | Define system context         |
| `units`         | Decompose into units          |
| `story-create`  | Create stories for a unit     |
| `bolt-plan`     | Plan bolts for stories        |
| `review`        | Review inception artifacts    |

## intent-create

Creates a new intent from your high-level goal:

```
> intent-create
> I want to build a user authentication system
```

The agent will:

<Steps>
  <Step title="Capture Goal">
    Record your high-level intent description
  </Step>

  <Step title="Ask Clarifying Questions">
    Minimize ambiguity through targeted questions
  </Step>

  <Step title="Generate Requirements">
    Create user stories and non-functional requirements
  </Step>

  <Step title="Define Context">
    Establish system boundaries and constraints
  </Step>
</Steps>

### Example Session

```
User: intent-create

Inception Agent: What would you like to build?

User: A user authentication system with login, registration, 
and password reset

Inception Agent: I'll help you elaborate this intent. Let me 
ask some clarifying questions:

1. Should users be able to log in with social providers 
   (Google, GitHub)?
2. Do you need multi-factor authentication?
3. What password requirements do you have?
4. How long should sessions last?

User: No social login for now, no MFA, standard password rules, 
sessions should last 24 hours

Inception Agent: Based on your answers, I've generated the 
following requirements...

[Shows generated requirements.md]

Does this look correct? Should I adjust anything?
```

## requirements

Elaborate or refine requirements for an existing intent:

```
> requirements user-authentication
```

Use this to:

* Add new user stories
* Refine acceptance criteria
* Add non-functional requirements
* Update priorities

## context

Define or update system context:

```
> context user-authentication
```

The agent helps you specify:

* What's in scope vs out of scope
* External interfaces
* Technical constraints
* Dependencies

## units

Decompose an intent into units:

```
> units user-authentication
```

The agent will:

1. Analyze requirements and context
2. Identify natural boundaries
3. Propose unit structure
4. Define interfaces between units
5. Map dependencies

### Example Output

```
Intent: User Authentication
├── Unit: User Registration
│   └── Stories: 3
├── Unit: User Login  
│   └── Stories: 2
├── Unit: Password Management
│   └── Stories: 3
└── Unit: Session Management
    └── Stories: 2

Dependencies:
- Login depends on Registration (user must exist)
- Password Management depends on Session (must be logged in)
```

## story-create

Create user stories for a specific unit:

```
> story-create user-authentication/user-registration
```

The agent generates stories with:

* User story format (As a... I want... So that...)
* Acceptance criteria
* Edge cases
* Test scenarios

## bolt-plan

Plan the bolts needed to implement stories:

```
> bolt-plan user-authentication/user-registration
```

The agent:

1. Analyzes stories and their complexity
2. Groups related stories
3. Assigns bolt types (DDD, TDD, BDD)
4. Orders bolts by dependencies
5. Estimates duration

### Example Output

```
Bolt Plan for User Registration:

1. Bolt: Registration Domain Model (DDD Construction)
   - Stories: US-001, US-002
   - Duration: 2-4 hours
   - Stages: Model → Design → Implement → Test

2. Bolt: Email Validation (TDD Construction)  
   - Stories: US-003
   - Duration: 1-2 hours
   - Stages: Test → Implement → Refactor

3. Bolt: Welcome Email (BDD Construction)
   - Stories: US-004
   - Duration: 1-2 hours
   - Stages: Scenario → Implement → Verify
```

## review

Review all inception artifacts for an intent:

```
> review user-authentication
```

The agent checks for:

* Completeness of requirements
* Consistency between artifacts
* Gaps in coverage
* Potential issues

## Workflow

Typical Inception flow:

```
intent-create → requirements → context → units → story-create → bolt-plan → review
```

<Warning>
  Complete each step before moving on. Incomplete inception leads to problems in construction.
</Warning>

## Human Checkpoints

The Inception Agent has **4 human checkpoints** with auto-continue between artifact generation:

```mermaid actions={false} theme={null}
flowchart TB
    A(User Request):::build --> B(Clarifying Questions):::build
    B --> G1{{"✋ Gate 1"}}:::check
    G1 -->|User answers| C(Generate Requirements):::plan
    C --> G2{{"✋ Gate 2"}}:::check
    G2 -->|User approves| D(Auto-Generate Artifacts):::plan

    subgraph Auto-Continue
        D --> D1(Context):::plan
        D1 --> D2(Units):::plan
        D2 --> D3(Stories):::plan
        D3 --> D4(Bolt Plan):::plan
    end

    D4 --> G3{{"✋ Gate 3"}}:::check
    G3 -->|User approves| E(Ready for Construction?):::build
    E --> G4{{"✋ Gate 4"}}:::check
    G4 -->|User confirms| F(Route to Construction):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Gate       | Location                      | Purpose                                   |
| ---------- | ----------------------------- | ----------------------------------------- |
| **Gate 1** | After clarifying questions    | Ensure all ambiguities addressed          |
| **Gate 2** | After requirements generated  | Validate requirements are correct         |
| **Gate 3** | After all artifacts generated | Review context, units, stories, bolt plan |
| **Gate 4** | Ready for construction        | Confirm inception complete                |

<Info>
  Between Gate 2 and Gate 3, the agent auto-continues through context → units → stories → bolt-plan without stopping. This speeds up artifact generation while maintaining key validation points.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Be Specific">
    Provide detailed answers to clarifying questions. Vague inputs lead to vague outputs.
  </Accordion>

  <Accordion title="Review Generated Artifacts">
    Always review what the agent generates. Correct errors before moving forward.
  </Accordion>

  <Accordion title="Keep Units Focused">
    If a unit feels too big, ask the agent to split it further.
  </Accordion>

  <Accordion title="Plan Before Building">
    Don't skip to Construction. Good bolt plans save time later.
  </Accordion>
</AccordionGroup>


# Master Agent
Source: https://specs.md/agents/master-agent

Orchestrates the AI-DLC flow and maintains project awareness

## Overview

The **Master Agent** is the orchestrator of the AI-DLC flow. It maintains awareness of the entire project state and routes you to the appropriate specialized agent.

## Invocation

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /specsmd-master-agent
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-master-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-master-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    /specsmd-master-agent
    ```
  </Tab>
</Tabs>

## Commands

| Command           | Purpose                             |
| ----------------- | ----------------------------------- |
| `project-init`    | Initialize project with standards   |
| `analyze-context` | View current project state          |
| `route-request`   | Get directed to the right agent     |
| `explain-flow`    | Learn about AI-DLC methodology      |
| `answer-question` | Get help with any specs.md question |

## project-init

Initializes your project with standards. This is typically the first command you run.

```
> project-init
```

The agent guides you through establishing:

<Steps>
  <Step title="Tech Stack">
    Languages, frameworks, databases, infrastructure choices
  </Step>

  <Step title="Coding Standards">
    Formatting, linting, naming conventions, testing strategy
  </Step>

  <Step title="System Architecture">
    Architecture style, API design, state management patterns
  </Step>

  <Step title="UX Guide (Optional)">
    Design system, styling, accessibility guidelines
  </Step>

  <Step title="API Conventions (Optional)">
    API style, versioning, response formats
  </Step>
</Steps>

Each standard is established through a facilitation guide that asks relevant questions and generates the standard document.

## analyze-context

Shows the current state of your project:

```
> analyze-context
```

Output includes:

* Active intents and their status
* Units in progress
* Current bolt stage
* Incomplete artifacts
* Suggested next actions

## route-request

When you're not sure which agent to use:

```
> route-request
> I want to add payment processing to my app
```

The Master Agent analyzes your request and directs you:

```
This sounds like a new Intent. You should use the Inception Agent 
to capture and elaborate this requirement.

Next step: /specsmd-inception-agent intent-create
```

## explain-flow

Get an explanation of the AI-DLC methodology:

```
> explain-flow
```

Topics you can ask about:

* The three phases (Inception, Construction, Operations)
* What Intents, Units, and Bolts are
* How checkpoints work
* Memory Bank structure

## answer-question

Get help with any specs.md question:

```
> answer-question
> How do I create an ADR?
```

The agent provides context-aware answers using:

* AI-DLC methodology knowledge
* Your project's current state
* Memory Bank artifacts

## Routing Flow

The Master Agent doesn't have checkpoints - it routes to specialized agents based on project state:

```mermaid actions={false} theme={null}
flowchart TB
    Start(specsmd-master-agent):::design --> Check{{"Standards exist?"}}:::check

    Check -->|No| New[New User Flow]
    Check -->|Yes| Return[Returning User Flow]

    subgraph New[New User]
        E(Explain AI-DLC):::plan --> Init(Project Init):::plan
    end

    subgraph Return[Returning User]
        Analyze(Analyze Context):::build --> Route(Route to Agent):::build
    end

    Route --> IA(Inception Agent):::plan
    Route --> CA(Construction Agent):::build
    Route --> OA(Operations Agent):::warn
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

<Info>
  The Master Agent is the entry point. It determines where you are in the AI-DLC flow and routes you to the appropriate specialist agent.
</Info>

## When to Use Master Agent

<CardGroup>
  <Card title="Starting a New Project" icon="play">
    Run `project-init` to establish standards
  </Card>

  <Card title="Unsure Where to Go" icon="compass">
    Use `route-request` to find the right agent
  </Card>

  <Card title="Need Orientation" icon="map">
    Run `analyze-context` to see project state
  </Card>

  <Card title="Learning AI-DLC" icon="graduation-cap">
    Use `explain-flow` for methodology guidance
  </Card>
</CardGroup>

## Example Session

```
User: /specsmd-master-agent

Master Agent: Welcome to specs.md! I'm the Master Agent. 
I can help you navigate the AI-DLC flow.

What would you like to do?
- project-init: Initialize a new project
- analyze-context: View current project state  
- route-request: Get directed to the right agent
- explain-flow: Learn about AI-DLC
- answer-question: Get help

User: project-init

Master Agent: Let's establish your project standards.

First, let's define your Tech Stack. 
What programming language(s) will you use?

User: TypeScript for everything

Master Agent: Great choice! TypeScript provides strong typing 
and excellent tooling. Let me ask a few more questions...

[Continues through facilitation guide]
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start Here">
    For new projects, always start with the Master Agent and `project-init`.
  </Accordion>

  <Accordion title="Check Context Regularly">
    Use `analyze-context` to understand where you are in the flow.
  </Accordion>

  <Accordion title="Ask for Routing">
    When unsure, ask the Master Agent. It knows the methodology.
  </Accordion>
</AccordionGroup>


# Operations Agent
Source: https://specs.md/agents/operations-agent

Deploys, verifies, and monitors systems in production

## Overview

<Warning>
  The Operations Agent is in alpha and has known issues that are currently being fixed. Some commands may not work as expected. We're actively looking for feedback - if you encounter an error, please [report it here](https://github.com/fabriqaai/specsmd/issues).
</Warning>

The **Operations Agent** handles the third phase of AI-DLC. It takes constructed features to production, verifies they work correctly, and sets up monitoring.

## Invocation

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /specsmd-operations-agent
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-operations-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-operations-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    /specsmd-operations-agent
    ```
  </Tab>
</Tabs>

## Commands

| Command   | Purpose               |
| --------- | --------------------- |
| `build`   | Build the project     |
| `deploy`  | Deploy to environment |
| `verify`  | Verify deployment     |
| `monitor` | Set up monitoring     |

## build

Builds the project for deployment:

```
> build
```

The agent will:

<Steps>
  <Step title="Check Prerequisites">
    Verify all construction bolts are complete
  </Step>

  <Step title="Run Build">
    Execute build commands from tech stack
  </Step>

  <Step title="Run Tests">
    Execute full test suite
  </Step>

  <Step title="Create Artifacts">
    Package for deployment
  </Step>
</Steps>

### Example Session

```
User: build

Operations Agent: Starting build process...

## Prerequisites Check
✓ All construction bolts complete
✓ No uncommitted changes
✓ On main branch

## Build
Running: npm run build
✓ TypeScript compilation successful
✓ Bundle created (245KB gzipped)

## Tests
Running: npm test
✓ 47 unit tests passed
✓ 12 integration tests passed
✓ 5 e2e tests passed

## Artifacts
✓ Docker image built: myapp:1.2.0
✓ Image pushed to registry

Build complete. Ready for deployment.
```

## deploy

Deploys to a target environment:

```
> deploy staging
```

Or for production:

```
> deploy production
```

The agent will:

<Steps>
  <Step title="Environment Check">
    Verify target environment configuration
  </Step>

  <Step title="Pre-deployment">
    Run database migrations, cache warming
  </Step>

  <Step title="Deploy">
    Deploy using configured strategy
  </Step>

  <Step title="Health Check">
    Verify services are healthy
  </Step>
</Steps>

### Deployment Strategies

The agent supports common strategies based on your infrastructure:

| Strategy       | Description                                |
| -------------- | ------------------------------------------ |
| **Rolling**    | Replace instances gradually                |
| **Blue-Green** | Switch between two environments            |
| **Canary**     | Route percentage of traffic to new version |

<Warning>
  Production deployments require explicit confirmation. The agent will show you exactly what will happen before proceeding.
</Warning>

## verify

Runs verification after deployment:

```
> verify staging
```

The agent will:

<Steps>
  <Step title="Smoke Tests">
    Run quick sanity checks
  </Step>

  <Step title="Health Endpoints">
    Check all service health endpoints
  </Step>

  <Step title="Integration Check">
    Verify integrations are working
  </Step>

  <Step title="Performance Baseline">
    Ensure response times are acceptable
  </Step>
</Steps>

### Example Output

```
User: verify staging

Operations Agent: Running verification for staging...

## Smoke Tests
✓ Homepage loads (234ms)
✓ API responds (45ms)
✓ Authentication works

## Health Endpoints
✓ /health - OK (12ms)
✓ /health/db - OK (23ms)
✓ /health/cache - OK (8ms)

## Integration Check
✓ Database connection
✓ Redis connection
✓ Email service

## Performance
✓ p50 latency: 45ms (target: <100ms)
✓ p95 latency: 123ms (target: <500ms)
✓ p99 latency: 234ms (target: <1000ms)

Verification passed. Staging is healthy.
```

## monitor

Sets up or checks monitoring:

```
> monitor setup
```

Or check current status:

```
> monitor status
```

The agent helps with:

<CardGroup>
  <Card title="Logging" icon="file-lines">
    Structured logging configuration
  </Card>

  <Card title="Metrics" icon="chart-line">
    Key performance indicators
  </Card>

  <Card title="Alerts" icon="bell">
    Alert rules and thresholds
  </Card>

  <Card title="Dashboards" icon="gauge">
    Visualization of system health
  </Card>
</CardGroup>

### Key Metrics

The agent suggests monitoring:

| Category         | Metrics                                 |
| ---------------- | --------------------------------------- |
| **Availability** | Uptime, error rate, success rate        |
| **Performance**  | Latency (p50, p95, p99), throughput     |
| **Resources**    | CPU, memory, disk, connections          |
| **Business**     | Active users, transactions, conversions |

## Human Checkpoints

The Operations Agent has **4 human checkpoints** aligned with environment progression:

```mermaid actions={false} theme={null}
flowchart TB
    P{{Prerequisites}}:::build -->|Construction complete?| A(Build Artifacts):::build
    A --> G1{{"✋ Gate 1"}}:::check
    G1 -->|User approves| B(Deploy to Dev):::plan
    B --> C(Deploy to Staging):::plan
    C --> G2{{"✋ Gate 2"}}:::check
    G2 -->|User approves| D(Verify Staging):::plan
    D --> E(Deploy to Production):::warn
    E --> G3{{"✋ Gate 3"}}:::check
    G3 -->|User approves| F(Verify Production):::warn
    F --> G(Setup Monitoring):::build
    G --> G4{{"✋ Gate 4"}}:::check
    G4 -->|User approves| H((Complete)):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

| Gate       | Location                 | Purpose                                   |
| ---------- | ------------------------ | ----------------------------------------- |
| **Gate 1** | After build              | Approve build artifacts before deployment |
| **Gate 2** | Before staging deploy    | Confirm ready for staging environment     |
| **Gate 3** | Before production deploy | Critical approval for production          |
| **Gate 4** | After monitoring setup   | Confirm operations complete               |

<Warning>
  Production deployment (Gate 3) requires explicit confirmation. The agent will show exactly what will happen before proceeding.
</Warning>

## Artifacts

Operations artifacts are stored in:

```
memory-bank/operations/
├── environments.md      # Environment configurations
├── runbooks/           # Operational procedures
│   ├── deployment.md
│   ├── rollback.md
│   └── incident.md
└── monitoring/
    ├── alerts.md
    └── dashboards.md
```

## Runbooks

The agent generates runbooks for common operations:

<AccordionGroup>
  <Accordion title="Deployment Runbook">
    Step-by-step deployment procedure:

    1. Pre-deployment checklist
    2. Deployment commands
    3. Verification steps
    4. Rollback procedure
  </Accordion>

  <Accordion title="Incident Response">
    What to do when things go wrong:

    1. Detection and triage
    2. Escalation matrix
    3. Communication template
    4. Post-mortem process
  </Accordion>

  <Accordion title="Scaling Runbook">
    How to handle increased load:

    1. Signs of scaling needs
    2. Horizontal vs vertical
    3. Scaling commands
    4. Verification
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Always Verify">
    Never skip verification after deployment. Automated checks catch issues humans miss.
  </Accordion>

  <Accordion title="Stage Environments">
    Deploy to staging before production. Test the deployment process itself.
  </Accordion>

  <Accordion title="Monitor Proactively">
    Set up alerts before you need them. Don't wait for production issues.
  </Accordion>

  <Accordion title="Document Runbooks">
    Keep runbooks updated. They're essential during incidents.
  </Accordion>
</AccordionGroup>


# Agents Overview
Source: https://specs.md/agents/overview

Four specialized agents that guide the AI-DLC development lifecycle

## The Agent System

specs.md provides four specialized agents that guide you through the entire development lifecycle. Each agent has a focused responsibility and set of commands.

## Agent Architecture

```mermaid actions={false} theme={null}
flowchart TB
    MA(Master Agent):::design --> IA(Inception Agent):::plan
    MA --> CA(Construction Agent):::build
    MA --> OA(Operations Agent):::warn
    IA --> CA
    CA --> OA
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

## Agent Responsibilities

<CardGroup>
  <Card title="Master Agent" icon="crown" href="/agents/master-agent">
    Orchestrates the overall flow, routes requests, maintains project awareness
  </Card>

  <Card title="Inception Agent" icon="lightbulb" href="/agents/inception-agent">
    Captures intents, elaborates requirements, decomposes into units
  </Card>

  <Card title="Construction Agent" icon="hammer" href="/agents/construction-agent">
    Executes bolts, builds code, runs tests through validated stages
  </Card>

  <Card title="Operations Agent" icon="server" href="/agents/operations-agent">
    Deploys, verifies, and monitors systems in production
  </Card>
</CardGroup>

## Invoking Agents

<Warning>
  **These are NOT command-line commands.** These are prompts you type in your AI coding tool's chat interface (Claude Code, Cursor, Copilot, etc.).
</Warning>

### How to Use

1. Open your AI coding tool (Claude Code, Cursor, GitHub Copilot)
2. Start a chat/conversation
3. Type the agent prompt to activate it

<Tabs>
  <Tab title="Claude Code">
    Type in Claude Code's chat:

    ```
    /specsmd-master-agent
    /specsmd-inception-agent
    /specsmd-construction-agent
    /specsmd-operations-agent
    ```
  </Tab>

  <Tab title="Cursor">
    Type in Cursor's chat (either format works):

    ```
    /specsmd-master-agent
    /specsmd-inception-agent
    /specsmd-construction-agent
    /specsmd-operations-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-master-agent
    @specsmd-inception-agent
    @specsmd-construction-agent
    @specsmd-operations-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    Type in Copilot's chat:

    ```
    /specsmd-master-agent
    /specsmd-inception-agent
    /specsmd-construction-agent
    /specsmd-operations-agent
    ```
  </Tab>
</Tabs>

## Agent Session Lifecycle

Each agent session follows a pattern:

<Steps>
  <Step title="Context Loading">
    Agent reads relevant artifacts from Memory Bank
  </Step>

  <Step title="Command Execution">
    Agent performs the requested command
  </Step>

  <Step title="Human Validation">
    Agent pauses for approval at checkpoints
  </Step>

  <Step title="Artifact Storage">
    Agent writes results back to Memory Bank
  </Step>
</Steps>

<Warning>
  Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.
</Warning>

## Command Reference

### Master Agent

| Command           | Purpose                             |
| ----------------- | ----------------------------------- |
| `project-init`    | Initialize project with standards   |
| `analyze-context` | View current project state          |
| `route-request`   | Get directed to the right agent     |
| `explain-flow`    | Learn about AI-DLC methodology      |
| `answer-question` | Get help with any specs.md question |

### Inception Agent

| Command         | Purpose                       |
| --------------- | ----------------------------- |
| `intent-create` | Create a new intent           |
| `intent-list`   | List all intents              |
| `requirements`  | Elaborate intent requirements |
| `context`       | Define system context         |
| `units`         | Decompose into units          |
| `story-create`  | Create stories for a unit     |
| `bolt-plan`     | Plan bolts for stories        |
| `review`        | Review inception artifacts    |

### Construction Agent

| Command       | Purpose                         |
| ------------- | ------------------------------- |
| `bolt-start`  | Start/continue executing a bolt |
| `bolt-status` | Check bolt progress             |
| `bolt-list`   | List all bolts                  |
| `bolt-replan` | Replan bolts if needed          |

### Operations Agent

| Command   | Purpose               |
| --------- | --------------------- |
| `build`   | Build the project     |
| `deploy`  | Deploy to environment |
| `verify`  | Verify deployment     |
| `monitor` | Set up monitoring     |

## Routing Between Agents

The Master Agent can route you to the appropriate agent:

```
> I want to add a new feature

Master Agent: That sounds like a new Intent. Let me route you 
to the Inception Agent.

/specsmd-inception-agent intent-create
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start with Master">
    When unsure where to begin, start with the Master Agent. It will guide you to the right place.
  </Accordion>

  <Accordion title="Complete Artifacts">
    Finish and save artifacts before switching agents. Context is loaded from Memory Bank.
  </Accordion>

  <Accordion title="Follow the Flow">
    Inception → Construction → Operations. Don't skip phases.
  </Accordion>

  <Accordion title="Use Commands">
    Each agent has specific commands. Use them rather than free-form requests.
  </Accordion>
</AccordionGroup>


# AI-DLC Quick Start
Source: https://specs.md/agents/quick-start

Get up and running with AI-DLC flow in minutes

<Warning>
  **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.
</Warning>

## 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

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Choose your AI tool">
    Select your preferred AI coding tool for agent configuration
  </Step>
</Steps>

## Initialize Your Project

Open your AI coding tool and start the Master Agent:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    /specsmd-master-agent
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-master-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-master-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```bash theme={null}
    /specsmd-master-agent
    ```
  </Tab>
</Tabs>

Then type:

```
project-init
```

This guides you through establishing:

<Steps>
  <Step title="Tech Stack">
    Languages, frameworks, databases, infrastructure
  </Step>

  <Step title="Coding Standards">
    Formatting, linting, naming, testing strategy
  </Step>

  <Step title="System Architecture">
    Architecture style, API design, state management
  </Step>

  <Step title="UX Guide (Optional)">
    Design system, styling, accessibility
  </Step>

  <Step title="API Conventions (Optional)">
    API style, versioning, response formats
  </Step>
</Steps>

## Create Your First Intent

An **Intent** is your high-level goal:

* "User authentication system"
* "Product catalog with search"
* "Payment processing integration"

```bash theme={null}
/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

```bash theme={null}
# Plan bolts for your stories
/specsmd-inception-agent bolt-plan

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

Each bolt goes through validated stages:

<CardGroup>
  <Card title="1. Domain Model" icon="diagram-project">
    Model business logic using DDD principles
  </Card>

  <Card title="2. Technical Design" icon="compass-drafting">
    Apply patterns and make architecture decisions
  </Card>

  <Card title="3. ADR Analysis" icon="file-lines">
    Document significant decisions (optional)
  </Card>

  <Card title="4. Implement" icon="code">
    Generate production code
  </Card>

  <Card title="5. Test" icon="vial">
    Verify correctness with automated tests
  </Card>
</CardGroup>

<Warning>
  Human validation happens at each checkpoint. This ensures errors are caught early before cascading downstream.
</Warning>

## 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

<AccordionGroup>
  <Accordion title="Agent doesn't remember context">
    Agents are stateless—they read artifacts from Memory Bank at startup. Ensure artifacts are saved after each step.
  </Accordion>

  <Accordion title="Bolt stuck in stage">
    Run `bolt-status` to check current stage. If validation failed, address the feedback and continue with `bolt-start`.
  </Accordion>

  <Accordion title="Want to restart a bolt">
    Bolts can be replanned with `/specsmd-inception-agent bolt-replan`. This creates a new bolt for the same stories.
  </Accordion>

  <Accordion title="Multiple intents exist">
    Run `/specsmd-master-agent analyze-context` to see all intents and their status.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="AI-DLC Overview" icon="book" href="/aidlc/overview">
    Understand the full AI-DLC methodology
  </Card>

  <Card title="Core Concepts" icon="cube" href="/core-concepts/intents">
    Deep dive into Intents, Units, and Bolts
  </Card>

  <Card title="Agents" icon="robot" href="/agents/overview">
    Learn about the four specialized agents
  </Card>

  <Card title="Bolt Types" icon="hammer" href="/guides/bolt-types">
    Choose between DDD and Simple bolts
  </Card>
</CardGroup>


# AI-DLC Flow Overview
Source: https://specs.md/aidlc/overview

Full AI-Driven Development Lifecycle with comprehensive traceability

## What is AI-DLC?

**AI-DLC (AI-Driven Development Lifecycle)** is a complete methodology for AI-native software development, originally defined by AWS. It provides comprehensive traceability, DDD integration, and structured phases for complex projects.

<Info>
  **AI proposes, human validates.** Like Google Maps—humans set the destination, AI provides step-by-step directions, humans maintain oversight at every checkpoint.
</Info>

```mermaid actions={false} theme={null}
flowchart LR
    I(Intent):::design --> U(Units):::plan
    U --> S(Stories):::plan
    S --> B(Bolts):::build
    B --> D(Done):::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

## Key Differentiators

<CardGroup>
  <Card title="Complete Methodology" icon="book">
    Not just a tool—a full SDLC with defined phases, rituals, and artifacts based on AWS research.
  </Card>

  <Card title="DDD Integration" icon="diagram-project">
    Domain-Driven Design is core, not optional. Model business logic before writing code.
  </Card>

  <Card title="Comprehensive Checkpoints" icon="shield-check">
    10-26 human validation points per bolt. Every decision is reviewed.
  </Card>

  <Card title="Four Specialized Agents" icon="robot">
    Master, Inception, Construction, and Operations agents with clear responsibilities.
  </Card>

  <Card title="Walkthrough Generation" icon="file-lines">
    Every change documented automatically. Review what AI did without digging through code.
  </Card>
</CardGroup>

## AI-DLC vs Other Flows

| Aspect              | AI-DLC                                          | FIRE                               | Simple               |
| ------------------- | ----------------------------------------------- | ---------------------------------- | -------------------- |
| **Philosophy**      | Full methodology                                | Adaptive execution                 | Spec generation      |
| **Hierarchy**       | Intent → Unit → Story → Bolt → Stages           | Intent → Work Item → Run           | Feature → Phases     |
| **Checkpoints**     | Comprehensive (10-26 per bolt)                  | Adaptive (0-2)                     | 3 phase gates        |
| **Agents**          | 4 (Master, Inception, Construction, Operations) | 3 (Orchestrator, Planner, Builder) | 1                    |
| **Design Approach** | DDD or Simple bolt types                        | Adaptive                           | Basic                |
| **Phases**          | Inception → Construction → Operations           | Plan → Execute                     | Req → Design → Tasks |
| **Artifacts**       | memory-bank/                                    | .specs-fire/                       | specs/               |
| **Optimized For**   | Full traceability, complex domains              | Teams who hate friction            | Quick prototypes     |

<Info>
  **Shared philosophy**: All flows use intents, structured artifacts, and human validation. They differ in ceremony level and traceability depth.
</Info>

## When to Use AI-DLC

<AccordionGroup>
  <Accordion title="You need comprehensive traceability">
    Every decision, every change, every artifact is tracked. Perfect for regulated environments or audit requirements.
  </Accordion>

  <Accordion title="You're building complex domain logic">
    AI-DLC integrates DDD from the start. Model your business domain before writing code.
  </Accordion>

  <Accordion title="You have multi-team coordination">
    Clear phases and artifacts make handoffs explicit. Teams know exactly what's expected.
  </Accordion>

  <Accordion title="You want predictable ceremony">
    Unlike adaptive flows, AI-DLC has fixed checkpoints. You always know what's coming next.
  </Accordion>

  <Accordion title="You're in a regulated environment">
    Healthcare, finance, government—where documentation requirements are strict.
  </Accordion>
</AccordionGroup>

## When to Consider Other Flows

<Info>
  **Consider FIRE if:**

  * You want adaptive checkpoints based on complexity
  * You're working on brownfield projects
  * You have a monorepo with multiple tech stacks
  * You prefer less ceremony for simple changes

  **Consider Simple if:**

  * You just need specs, not execution tracking
  * You're prototyping or creating handoff documents
  * You want minimal overhead
</Info>

## Three Phases

AI-DLC follows three sequential phases:

```mermaid actions={false} theme={null}
flowchart LR
    subgraph Inception["Inception Phase"]
        I1(Capture):::plan --> I2(Elaborate):::plan
        I2 --> I3(Decompose):::plan
        I3 --> I4(Plan Bolts):::plan
    end

    subgraph Construction["Construction Phase"]
        C1(Model):::build --> C2(Design):::build
        C2 --> C3(ADR):::build
        C3 --> C4(Implement):::build
        C4 --> C5(Test):::build
    end

    subgraph Operations["Operations Phase"]
        O1(Build):::warn --> O2(Deploy):::warn
        O2 --> O3(Verify):::warn
        O3 --> O4(Monitor):::warn
    end

    Inception --> Construction
    Construction --> Operations
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

| Phase            | Agent              | Ritual           | Output                              |
| ---------------- | ------------------ | ---------------- | ----------------------------------- |
| **Inception**    | Inception Agent    | Mob Elaboration  | Intents, Units, Stories, Bolt Plans |
| **Construction** | Construction Agent | Mob Construction | Domain Models, Code, Tests          |
| **Operations**   | Operations Agent   | Continuous       | Deployments, Monitoring             |

## Core Concepts

### Intent

A high-level business objective. The starting point for all work.

```yaml theme={null}
intent:
  id: 001-user-authentication
  title: User Authentication System
  status: in_progress
```

### Unit

A loosely-coupled module that can be developed independently.

### Story

A user story within a unit, with acceptance criteria.

### Bolt

A time-boxed execution cycle (hours or days) that implements stories through validated stages.

<Info>
  Learn more in [Core Concepts](/core-concepts/intents).
</Info>

## Four-Agent Architecture

| Agent            | Phase        | Responsibility                                          |
| ---------------- | ------------ | ------------------------------------------------------- |
| **Master**       | All          | Orchestrates flow, routes requests, maintains awareness |
| **Inception**    | Inception    | Captures intents, elaborates requirements, plans bolts  |
| **Construction** | Construction | Executes bolts through DDD stages                       |
| **Operations**   | Operations   | Builds, deploys, verifies, monitors                     |

<Info>
  Learn more in [Agents Overview](/agents/overview).
</Info>

## Project Structure

```
memory-bank/                   # AI-DLC artifacts
├── intents/                   # Captured intents
│   └── {intent-id}/
│       ├── requirements.md
│       ├── system-context.md
│       └── units/
│           └── {unit-id}/
│               ├── unit-brief.md
│               └── stories/
├── bolts/                     # Bolt execution records
├── standards/                 # Project standards
│   ├── tech-stack.md
│   ├── coding-standards.md
│   ├── system-architecture.md
│   └── ...
└── operations/                # Deployment context
```

## Get Started

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Step>

  <Step title="Select AI-DLC during init">
    Choose "AI-DLC" when prompted for flow selection
  </Step>

  <Step title="Initialize project standards">
    ```
    /specsmd-master-agent project-init
    ```
  </Step>

  <Step title="Create your first intent">
    ```
    /specsmd-inception-agent intent-create
    ```
  </Step>
</Steps>

<Card title="Quick Start Guide" icon="rocket" href="/agents/quick-start">
  Step-by-step guide to building with AI-DLC
</Card>


# Choose Your Flow
Source: https://specs.md/architecture/choose-flow

Compare Ideation, Simple, FIRE, and AI-DLC flows to find the right fit for your project

## Four Flows, Every Use Case

specs.md offers four flows, each designed for a different stage and context. Choose the one that matches your current need.

<CardGroup>
  <Card title="Ideation Flow" icon="lightbulb" href="/ideation-flow/overview">
    **Creative brainstorming**

    Spark → Flame → Forge. Diverse ideas to polished concept briefs before you commit to building.
  </Card>

  <Card title="Simple Flow" icon="feather" href="/simple-flow/overview">
    **Spec generation only**

    Quick requirements, design, and task documents without execution tracking.
  </Card>

  <Card title="FIRE Flow" icon="bolt" href="/fire-flow/overview">
    **Rapid execution**

    Ship in hours with adaptive checkpoints and first-class brownfield support.
  </Card>

  <Card title="AI-DLC Flow" icon="building" href="/core-concepts/intents">
    **Full methodology**

    Complete lifecycle with DDD, 4 agents, and comprehensive traceability.
  </Card>
</CardGroup>

## Quick Decision Guide

<Steps>
  <Step title="Do you have a clear feature idea yet?">
    * **No, I'm still exploring** → Use **Ideation Flow** (brainstorm → evaluate → shape a concept brief)
    * **Yes, I know what I want to build** → Continue to Step 2
  </Step>

  <Step title="Do you need execution tracking?">
    * **No** → Use **Simple Flow** (spec generation only, like Kiro)
    * **Yes** → Continue to Step 3
  </Step>

  <Step title="Do you want adaptive or fixed ceremony?">
    * **Adaptive** (right-size rigor based on task complexity) → **FIRE Flow**
    * **Fixed** (predictable checkpoints every time) → **AI-DLC Flow**
  </Step>

  <Step title="Do you hate unnecessary friction?">
    * **Yes** (check when necessary, not everything) → **FIRE Flow**
    * **No** (prefer comprehensive documentation always) → **AI-DLC Flow**
  </Step>
</Steps>

## Detailed Comparison

| Aspect                 | Ideation             | Simple                      | FIRE                           | AI-DLC                        |
| ---------------------- | -------------------- | --------------------------- | ------------------------------ | ----------------------------- |
| **Optimized For**      | Creative exploration | Spec generation, prototypes | Teams who hate friction        | Full traceability needs       |
| **Output**             | Concept briefs       | Specs (req/design/tasks)    | Working code + walkthroughs    | Working code + full artifacts |
| **Execution Planning** | N/A                  | N/A                         | Dynamic (recommends next run)  | Pre-planned (bolts)           |
| **Checkpoints**        | 0 (non-blocking)     | 3 (phase gates)             | Adaptive (complexity + config) | Comprehensive (fixed)         |
| **Agents**             | 1                    | 1                           | 3                              | 4                             |
| **Execution Tracking** | No                   | No                          | Yes (runs, walkthroughs)       | Yes (bolts, stages)           |
| **Design Docs**        | Concept briefs       | Basic specs                 | When complexity warrants       | Always (DDD integral)         |
| **Monorepo Support**   | No                   | No                          | First-class                    | Limited                       |
| **Brownfield Support** | No                   | Basic                       | First-class                    | Alpha                         |
| **Output Structure**   | `.specs-ideation/`   | `specs/{feature}/`          | `.specs-fire/`                 | `memory-bank/`                |
| **Ceremony Style**     | Zero friction        | Minimal                     | Adaptive                       | Comprehensive                 |

## When to Use Each Flow

### Ideation Flow

<Info>
  **Choose Ideation when**: You haven't committed to a specific feature yet—or you want to stress-test your current idea against alternatives you haven't considered.
</Info>

* Early-stage product discovery
* Finding novel angles before writing a spec
* Brainstorming sessions (solo or team)
* Evaluating multiple feature directions before committing resources
* When your first idea might not be the best idea

**Output**: `spark-bank.md` (ideas), `flame-report.md` (evaluations), `concept-brief.md` (shaped concepts)

### Simple Flow

<Info>
  **Choose Simple when**: You need quick specs without the overhead of execution tracking.
</Info>

* Building prototypes or MVPs
* Generating specs for handoff to another team
* Small features in established projects
* Solo developers wanting structured documentation
* Projects that don't need AI-assisted execution

**Output**: `requirements.md`, `design.md`, `tasks.md`

### FIRE Flow

<Info>
  **Choose FIRE when**: You want adaptive execution that right-sizes the rigor.
</Info>

FIRE is **Adaptive Spec-Driven Development**—it analyzes work complexity and your config to decide when to ask and when to burn through.

* Teams who hate unnecessary friction
* Brownfield projects with existing code
* Monorepo architectures
* Projects where implementation plan is often enough, but design docs when needed
* Anyone wanting to ship fast without reckless code generation

**Key Features**:

* **Dynamic execution**: No pre-planned runs—Builder scans work items and recommends what to run next
* **Change-friendly**: Requirements changed? Just update specs, next run adapts automatically
* **Adaptive checkpoints**: Based on work complexity + your autonomy preference
* **Walkthrough generation**: AI documents every change for review
* **Hierarchical standards**: Module-specific overrides in monorepos
* **Brownfield-first**: Analyzes your existing structure and respects your patterns

### AI-DLC Flow

<Info>
  **Choose AI-DLC when**: You need full traceability, DDD, and multi-team coordination.
</Info>

* Teams with multiple developers
* Complex domain logic requiring DDD
* Projects needing comprehensive documentation
* Regulated environments requiring audit trails
* Multi-stakeholder initiatives

**Key Features**:

* **Four specialized agents**: Master, Inception, Construction, Operations
* **Domain-Driven Design**: Full DDD stages in Construction
* **Complete traceability**: Every decision documented
* **Mob rituals**: Mob Elaboration, Mob Construction

## Flow Comparison Matrix

```mermaid actions={false} theme={null}
flowchart TD
    subgraph "Phase vs Complexity"
        I(Ideation Flow):::check
        S(Simple Flow):::plan
        F(FIRE Flow):::warn
        A(AI-DLC Flow):::design
    end

    I -->|"Pre-feature"| Explore(Creative Exploration):::done
    S -->|"Low complexity"| Quick(Quick Specs):::done
    F -->|"Medium complexity"| Rapid(Rapid Execution):::done
    A -->|"High complexity"| Complete(Complete Lifecycle):::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

## Switching Between Flows

Flows are independent—they're not an upgrade path. Choose based on your project needs:

<Warning>
  **Flows are not progressive**: Simple doesn't upgrade to FIRE, FIRE doesn't upgrade to AI-DLC. Each flow is designed for different use cases. Choose the right flow upfront.
</Warning>

However, you can:

* Use **Simple Flow** to generate initial specs, then implement manually
* Use **FIRE Flow** for rapid feature development within a project
* Use **AI-DLC Flow** for major initiatives requiring full planning

## Getting Started

<CardGroup>
  <Card title="Start with Ideation" icon="play" href="/ideation-flow/quick-start">
    Generate ideas and shape a concept brief
  </Card>

  <Card title="Start with Simple" icon="play" href="/simple-flow/quick-start">
    Generate specs in minutes
  </Card>

  <Card title="Start with FIRE" icon="play" href="/fire-flow/quick-start">
    Ship your first feature fast
  </Card>

  <Card title="Start with AI-DLC" icon="play" href="/getting-started/quick-start">
    Full methodology walkthrough
  </Card>
</CardGroup>


# Pluggable Flows
Source: https://specs.md/architecture/flows

Understanding the specs.md flow architecture

## Framework Architecture

specs.md is built as a **pluggable framework** where development methodologies are implemented as **flows**. Choose the flow that matches your project needs.

```mermaid actions={false} theme={null}
flowchart TB
    subgraph Framework[specs.md Framework]
        subgraph Flows[Available Flows]
            Ideation(Ideation Flow):::done
            Simple(Simple Flow):::plan
            FIRE(FIRE Flow):::warn
            AIDLC(AI-DLC Flow):::design
        end
    end
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

## What is a Flow?

A **flow** is a complete development methodology implementation that includes:

<CardGroup>
  <Card title="Agents" icon="robot">
    Specialized AI agents that guide development
  </Card>

  <Card title="Artifacts" icon="file-code">
    Structured outputs for each phase
  </Card>

  <Card title="State Management" icon="database">
    Tracking progress and context
  </Card>

  <Card title="Standards" icon="ruler">
    Project guidelines and conventions
  </Card>
</CardGroup>

## Available Flows

| Flow                                    | Checkpoints      | Agents | Optimized For                           |
| --------------------------------------- | ---------------- | ------ | --------------------------------------- |
| **[Ideation](/ideation-flow/overview)** | 0 (non-blocking) | 1      | Creative brainstorming, concept shaping |
| **[Simple](/simple-flow/overview)**     | 3 (phase gates)  | 1      | Spec generation only                    |
| **[FIRE](/fire-flow/overview)**         | Adaptive         | 3      | Adaptive execution, brownfield          |
| **[AI-DLC](/core-concepts/intents)**    | Comprehensive    | 4      | Full traceability                       |

<Info>
  **Not sure which flow?** Check out our [Choose Your Flow](/architecture/choose-flow) guide.
</Info>

## Ideation Flow

**Ideation Flow** transforms AI into a creative partner through three sequential skills: Spark (generate), Flame (evaluate), Forge (shape). Research-backed methods run invisibly—you get diverse ideas, not methodology labels.

```mermaid actions={false} theme={null}
flowchart LR
    T(Topic):::plan --> S(Spark):::warn --> F(Flame):::check --> G(Forge):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Aspect       | Details                                                           |
| ------------ | ----------------------------------------------------------------- |
| **Agent**    | 1 (orchestrator with 3 skills)                                    |
| **Output**   | `spark-bank.md`, `flame-report.md`, `concept-brief.md`            |
| **Skills**   | Spark → Flame → Forge                                             |
| **Best For** | Product discovery, pre-feature brainstorming, concept development |

<Card title="Ideation Flow Documentation" icon="lightbulb" href="/ideation-flow/overview">
  Learn more about Ideation Flow
</Card>

## Simple Flow

**Simple Flow** generates structured specs without execution tracking—perfect for quick feature planning.

| Aspect       | Details                                    |
| ------------ | ------------------------------------------ |
| **Agent**    | 1 (specsmd-agent)                          |
| **Output**   | `requirements.md`, `design.md`, `tasks.md` |
| **Phases**   | Requirements → Design → Tasks              |
| **Best For** | Prototypes, MVPs, spec handoff             |

<Card title="Simple Flow Documentation" icon="feather" href="/simple-flow/overview">
  Learn more about Simple Flow
</Card>

## FIRE Flow

**FIRE (Fast Intent-Run Engineering)** is an Adaptive Spec-Driven Development flow. It right-sizes the rigor to complexity—design docs when needed, implementation plans otherwise.

```mermaid actions={false} theme={null}
flowchart LR
    O(Orchestrator):::design --> P(Planner):::plan
    O --> B(Builder):::build
    P --> S[(State)]:::warn
    B --> S
    B --> C[(Codebase)]:::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Aspect            | Details                                        |
| ----------------- | ---------------------------------------------- |
| **Agents**        | 3 (Orchestrator, Planner, Builder)             |
| **Checkpoints**   | Adaptive (based on complexity + config)        |
| **Optimized For** | Adaptive execution, brownfield, monorepos      |
| **Key Features**  | Walkthrough generation, hierarchical standards |

<Card title="FIRE Flow Documentation" icon="bolt" href="/fire-flow/overview">
  Learn more about FIRE Flow
</Card>

## AI-DLC Flow

**AI-DLC (AI-Driven Development Lifecycle)** is the full methodology with DDD and comprehensive traceability.

```mermaid actions={false} theme={null}
flowchart TB
    MA(Master Agent):::design --> IA(Inception):::plan
    MA --> CA(Construction):::build
    MA --> OA(Operations):::warn
    IA --> CA --> OA
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

| Aspect           | Details                                         |
| ---------------- | ----------------------------------------------- |
| **Agents**       | 4 (Master, Inception, Construction, Operations) |
| **Phases**       | Inception → Construction → Operations           |
| **Best For**     | Teams, complex domains, regulated environments  |
| **Key Features** | DDD integration, Mob rituals, full traceability |

### Bolt Types (AI-DLC)

| Type                    | Best For             | Stages                             |
| ----------------------- | -------------------- | ---------------------------------- |
| **DDD Construction**    | Complex domain logic | Model → Design → ADR → Code → Test |
| **Simple Construction** | UI, integrations     | Plan → Implement → Test            |

<Card title="AI-DLC Documentation" icon="building" href="/methodology/what-is-ai-dlc">
  Learn more about AI-DLC Flow
</Card>

## Tool Integration

All flows integrate with AI coding tools:

| Tool                   | Integration Method                    |
| ---------------------- | ------------------------------------- |
| **Claude Code**        | Slash commands in `.claude/commands/` |
| **Cursor**             | Rules in `.cursor/rules/`             |
| **GitHub Copilot**     | Agents in `.github/agents/`           |
| **Google Antigravity** | Agents in `.agent/agents/`            |

## Next Steps

<CardGroup>
  <Card title="Choose Your Flow" icon="compass" href="/architecture/choose-flow">
    Detailed comparison guide
  </Card>

  <Card title="Installation" icon="download" href="/getting-started/installation">
    Install and select your flow
  </Card>

  <Card title="VS Code Extension" icon="puzzle-piece" href="/getting-started/ide-extension">
    Track progress visually
  </Card>
</CardGroup>


# Changelog
Source: https://specs.md/changelog

Product updates and announcements

All notable changes to specs.md.

<Info>
  **Subscribe to updates:** [GitHub Releases](https://github.com/fabriqaai/specs.md/releases)
</Info>

<Update label="February 22, 2026" description="v0.1.49">
  ### Changed

  * Added CLI worktree support so you can monitor and switch between multiple branches/worktrees in one place (useful when parallel feature branches are active and you want to track progress without leaving the dashboard)
  * Added explicit command-log feedback after switching worktrees so the active context change is immediately visible (for example: `Switched to worktree: <name>`)
</Update>

<Update label="February 21, 2026" description="v0.1.26">
  ### Added

  * New FIRE CLI dashboard command: `npx specsmd@latest dashboard`
  * Tabbed terminal views: **Runs**, **Overview**, and **Health** (stats + warnings)
  * Keyboard shortcuts for quick navigation: `1/2/3`, `Tab`, `←/→`, and `f`
  * Current Run-first layout with phase track and run files panel

  ### Changed

  * Dashboard UX now targets CLI-first users and Codex desktop app workflows as a practical alternative to the VS Code extension
  * Reduced flicker by limiting unnecessary UI updates and using calmer fallback refresh behavior
  * Compact rendering for smaller terminal windows with tighter spacing and stricter height budgeting
  * Nerd Font icon auto-detection (with override via `SPECSMD_ICON_SET=auto|nerd|ascii`)

  <Frame>
    <img alt="FIRE dashboard in compact terminal mode" />
  </Frame>

  <Frame>
    <img alt="FIRE dashboard in Codex desktop with no active run" />
  </Frame>
</Update>

<Update label="February 13, 2026" description="v0.1.23">
  ### Fixed

  * Codex installer now creates proper skills instead of flat `.md` files that Codex cannot read
  * Commands are transformed into `.codex/skills/<name>/SKILL.md` with proper YAML frontmatter
</Update>

<Update label="January 25, 2026" description="v0.1.11">
  ### Per-Work-Item Phase Tracking

  The VS Code extension now shows real-time phase progress for each work item in FIRE runs. Track exactly where your AI agent is in the Plan → Execute → Test → Review pipeline.

  <Frame>
    <img alt="Work item showing Test phase in progress" />
  </Frame>

  **First work item in Test phase** - completed Plan and Execute, now running tests.

  <Frame>
    <img alt="Multiple work items with phase tracking" />
  </Frame>

  **Progress through multiple work items** - first item completed all phases, second item now in Test phase.

  ### Added

  * Per-work-item phase tracking in FIRE flow (Plan → Execute → Test → Review)
  * Real-time phase progress indicator showing which phase each work item is currently in
  * Visual distinction between completed phases (green checkmarks) and active phase (orange highlight)

  ### Changed

  * Phase tracking now updates at work item level instead of run level for better granularity
</Update>

<Update label="January 24, 2026" description="v0.1.10">
  ### Added

  * FIRE: Status skill now includes comprehensive integrity validation with 14 issue types
  * FIRE: Code verification option to check codebase when work item status is ambiguous
  * FIRE: Maintenance log (`maintenance-log.md`) for tracking all automated fixes
  * FIRE: Support for multiple parallel active runs in state schema

  ### Changed

  * FIRE: Status skill bumped to v2.0.0 with full validation workflow
  * FIRE: All command references now use `/specsmd-fire` prefix consistently
  * FIRE: Config references updated from `fire-config.yaml` to `memory-bank.yaml`

  ### Fixed

  * FIRE: Added missing `review-report.md` to run artifacts schema
  * FIRE: Added missing `design-doc` path to schema
  * FIRE: Added `blocked` status to work item status values
  * FIRE: Added `mode` and `depends_on` fields to work item schema
  * FIRE: Orchestrator agent state example now matches actual schema structure
</Update>

<Update label="January 23, 2026" description="v0.1.9">
  ### Added

  * FIRE Flow: New flow type with 17 Lit web components for VS Code extension
  * VS Code: Flow switcher in toolbar for switching between AI-DLC and FIRE flows
  * VS Code: FIRE Runs tab with active run display and completed runs history
  * VS Code: FIRE Intents tab with expandable intent cards and progress tracking
  * VS Code: Pending work items grouped by intent with dependency visualization
  * VS Code: File watcher for `.specs-fire` directory to auto-refresh on state changes
  * VS Code: Expandable completed runs showing all markdown files with click-to-open

  ### Changed

  * File watcher now monitors both `memory-bank` and `.specs-fire` directories

  ### Fixed

  * YAML parsing now supports both snake\_case and camelCase field names
  * Intent expansion state persisted correctly across view refreshes
</Update>

<Update label="January 13, 2026" description="v0.1.8">
  ### Added

  * Simple Flow: Lightweight 3-phase workflow (Requirements → Design → Tasks)
  * Simple Flow documentation pages
  * Changelog page in documentation
  * Kiro installer with specs symlink support for Simple Flow

  ### Changed

  * Clarified Simple Flow and AI-DLC as independent flows (not an upgrade path)

  ### Fixed

  * Markdown lint errors in DDD construction bolt template
</Update>

<Update label="January 10, 2026" description="v0.1.7">
  ### Fixed

  * OpenCode installer now uses correct command directory and frontmatter
</Update>

<Update label="January 10, 2026" description="v0.1.6">
  ### Added

  * VS Code: Markdown editor selection setting
  * VS Code: Clickable stories in bolt widget
  * ADR (Architecture Decision Record) tracking with decision index across bolts

  ### Fixed

  * Markdown lint errors in DDD construction bolt template
  * Security vulnerabilities in dependencies
</Update>

<Update label="January 9, 2026" description="v0.1.5">
  ### Added

  * VS Code: Construction log display for completed bolts
  * VS Code: Analytics module with lifecycle, engagement, and project metrics tracking
  * VS Code: Open VSX marketplace publishing (works with Cursor, Windsurf, etc.)
  * VS Code: Enhanced logs inception artifacts

  ### Changed

  * Moved scripts into aidlc flow folder for better organization

  ### Fixed

  * Test paths after scripts reorganization
</Update>

<Update label="January 6, 2026" description="v0.1.4">
  ### Added

  * Contextual options menu (copy, AI tools, feature request)
  * DeepWiki integration for codebase exploration
  * Workflow descriptions for Google Antigravity navigation
  * SEO metadata and social sharing tags to docs
  * Product Hunt launch integration
</Update>

<Update label="December 30, 2025" description="v0.1.3">
  ### Added

  * Artifacts display in active bolt view
  * Manual workflow dispatch trigger for releases
  * Dev branch auto-publish workflow

  ### Fixed

  * Bolt-start guardrails to prevent skipping story updates
  * Active bolt UI improvements and IDE-agnostic messages
  * Frontmatter validation for bolt creation
  * Geolocation in Mixpanel analytics tracker
</Update>

<Update label="December 28, 2025" description="v0.1.2">
  ### Fixed

  * Analytics events now properly sent before process exit
</Update>

<Update label="December 27, 2025" description="v0.1.1">
  ### Added

  * Mixpanel analytics for installer events
  * VS Code extension with bolt visualization and progress tracking
  * Dynamic status discovery for specs filter
  * Extension marketplace publishing workflow

  ### Fixed

  * Intent matching by combined format in selector
  * Markdown lint errors in bolt-plan skill
</Update>

<Update label="December 27, 2025" description="v0.1.0">
  ### Initial Release

  * AI-DLC Flow with 4 agents (Master, Inception, Construction, Operations)
  * Memory Bank for persistent project context
  * Support for Claude Code, Cursor, GitHub Copilot, and other AI coding tools
  * DDD construction bolt type
  * Installer with automatic tool detection
</Update>


# Community
Source: https://specs.md/community

Join the specs.md community - Connect with developers building AI-native software

# Community

Join our growing community of developers building AI-native software with specs.md.

<CardGroup>
  <Card title="Discord" icon="discord" href="http://discord.specs.md/">
    Join our Discord server to chat with the community, get help, and share your experiences.
  </Card>

  <Card title="Zulip" icon="comments" href="https://fabriqa.zulipchat.com/">
    Connect with the team on Zulip for discussions and collaboration.
  </Card>

  <Card title="X (Twitter)" icon="x-twitter" href="https://x.com/specsmd">
    Follow us on X for updates, tips, and announcements.
  </Card>

  <Card title="Product Hunt" icon="rocket" href="https://www.producthunt.com/products/specs-md">
    Check out our Product Hunt page and leave a review.
  </Card>
</CardGroup>

## Featured on Product Hunt

<div>
  <div>
    <img alt="specs.md" />

    <div>
      <h3>specs.md</h3>
      <p>framework for spec-driven AI development with pluggable flow</p>
    </div>
  </div>

  <a href="https://www.producthunt.com/products/specs-md?embed=true&utm_source=embed&utm_medium=post_embed">Check it out on Product Hunt →</a>
</div>

## Get Involved

<CardGroup>
  <Card title="GitHub" icon="github" href="https://github.com/fabriqaai/specs.md">
    Star the repo, report issues, or contribute to the project.
  </Card>

  <Card title="Feedback" icon="comment" href="/feedback">
    Share your thoughts and help us improve specs.md.
  </Card>
</CardGroup>

## Why Join?

* **Get Help**: Ask questions and get answers from the community and maintainers
* **Share Knowledge**: Help others and share your AI-DLC experiences
* **Stay Updated**: Be the first to know about new features and releases
* **Shape the Future**: Your feedback directly influences the roadmap

## Community Guidelines

We're committed to providing a welcoming and inclusive environment. Please:

* Be respectful and constructive
* Help others when you can
* Share your learnings and experiences
* Report any issues or concerns

<Info>
  We're just getting started! Join early and help shape the community.
</Info>


# Compare Spec-Driven Tools
Source: https://specs.md/compare/overview

How specs.md compares to Spec Kit, BMAD, Kiro, and OpenSpec

## specs.md: One Framework, Three Flows

<Info>
  **Choose Your Level of Ceremony**: specs.md offers three flows from lightweight spec generation to full methodology. Pick the one that matches your project needs.
</Info>

## Three Flows Available

| Flow                                           | Checkpoints     | Optimized For                             |
| ---------------------------------------------- | --------------- | ----------------------------------------- |
| **[Simple Flow](/simple-flow/overview)**       | 3 (phase gates) | Spec generation only, quick prototypes    |
| **[FIRE Flow](/fire-flow/overview)**           | Adaptive        | Adaptive execution, brownfield, monorepos |
| **[AI-DLC Flow](/methodology/what-is-ai-dlc)** | Comprehensive   | Full traceability, regulated environments |

<CardGroup>
  <Card title="Simple" icon="feather" href="/simple-flow/overview">
    Quick specs without execution tracking
  </Card>

  <Card title="FIRE" icon="bolt" href="/fire-flow/overview">
    Rapid execution with adaptive checkpoints
  </Card>

  <Card title="AI-DLC" icon="building" href="/methodology/what-is-ai-dlc">
    Full methodology with DDD
  </Card>
</CardGroup>

[Choose your flow →](/architecture/choose-flow)

***

## Comparison Matrix

| Feature                | specs.md                                                    | Spec Kit                   | BMAD                  | OpenSpec               | Kiro                                          |
| ---------------------- | ----------------------------------------------------------- | -------------------------- | --------------------- | ---------------------- | --------------------------------------------- |
| **Target Complexity**  | Complex systems                                             | Small-medium               | Complex/Enterprise    | Any (brownfield-first) | Any                                           |
| **Type**               | Methodology + Framework                                     | Toolkit + Agent Prompts    | Multi-agent Framework | Lightweight Framework  | Full IDE                                      |
| **Methodology**        | AWS AI-DLC (formal)                                         | Spec Kit SDD               | Agentic Agile         | OpenSpec SDD           | Kiro SDD                                      |
| **Design Integration** | DDD default (extensible via bolt types)                     | Constitution file          | Optional              | Design-agnostic        | Design-agnostic                               |
| **Rituals**            | Mob Elaboration, Mob Construction                           | None                       | None                  | None                   | None                                          |
| **Phases**             | 3 sequential                                                | 6 sequential               | 4 phases              | Change-centric         | Requirements→Design→Tasks                     |
| **Agent Model**        | 3 phase-based agents                                        | Prompts for 15+ assistants | 19 role-based agents  | AGENTS.md compatible   | Built-in + Subagents                          |
| **Iteration Cycles**   | "Hours or days" (Bolts)                                     | Variable                   | Variable              | Variable               | Variable                                      |
| **Brownfield Support** | Yes (with model elevation)                                  | Yes                        | Yes                   | Yes (primary focus)    | Yes                                           |
| **IDE Lock-in**        | None (any IDE)                                              | None                       | None                  | None                   | Kiro IDE only                                 |
| **VS Code Extension**  | Yes ([visual dashboard](/getting-started/vscode-extension)) | No                         | No                    | CLI dashboard          | Built into IDE                                |
| **Open Source**        | Yes                                                         | Yes                        | Yes                   | Yes                    | Partial (Code OSS base, proprietary features) |
| **Pricing**            | Free (OSS)                                                  | Free (OSS)                 | Free (OSS)            | Free (OSS)             | Free preview → \$20-200/mo                    |

***

## Quick Comparisons

<CardGroup>
  <Card title="vs GitHub Spec Kit" icon="github" href="/compare/vs-speckit">
    Lightweight toolkit vs full methodology. Learn when to choose each.
  </Card>

  <Card title="vs BMAD-Method" icon="users" href="/compare/vs-bmad">
    Both target complex projects. Compare phase-based vs role-based agents.
  </Card>

  <Card title="vs Kiro (AWS)" icon="window" href="/compare/vs-kiro">
    IDE-integrated vs IDE-agnostic. Compare automation approaches.
  </Card>

  <Card title="vs OpenSpec" icon="code-branch" href="/compare/vs-openspec">
    Full lifecycle vs change-centric. Compare brownfield strategies.
  </Card>
</CardGroup>

***

## Key Differentiators

### 1. AI-DLC is a Formal AWS Methodology

Unlike generic "spec-driven development," AI-DLC is defined by AWS with specific phases, rituals, and artifacts. specs.md is a faithful implementation—not an interpretation.

### 2. DDD as Default, Extensible via Bolt Types

Agile frameworks leave design techniques optional. AI-DLC integrates Domain-Driven Design as its default—AI applies DDD principles during decomposition, developers validate.

**Extensible**: Use bolt types to add other methodologies like BDD, TDD, or model your own construction flow. DDD is the default, not a limitation.

### 3. Bolts: Batched Stories with Full Traceability

Unlike other tools with variable iteration cycles, specs.md uses **Bolts**—planned batches of related stories executed together by an agent. Each Bolt follows DDD steps during execution, and artifacts created during construction provide full traceability of what was built and how.

```
Intent → Units → Stories → Bolt (batched stories)
                              ↓
                    DDD Construction Steps
                              ↓
                    Traceable Artifacts
```

### 4. Reversed Conversation Direction

In AI-DLC, **AI initiates and directs conversations**. AI proposes breakdown, trade-offs, designs. Humans validate and approve. This is the opposite of most tools where humans prompt AI.

### 5. Mob Rituals for Team Alignment

Mob Elaboration (Inception) and Mob Construction condense weeks of sequential work into hours while achieving deep alignment between team and AI.

### 6. Built for Complex Systems

<Warning>
  AI-DLC explicitly targets systems with "continuous functional adaptability, high architectural complexity, numerous trade-offs management, scalability, integration and customization requirements."

  Simpler projects → [specs.md (Simple Flow)](/simple-flow/overview).
</Warning>

***

## Vendor Lock-in

| Tool     | Lock-in Risk                              |
| -------- | ----------------------------------------- |
| specs.md | None - works with any IDE/AI              |
| Spec Kit | None - works with 15+ AI assistants       |
| BMAD     | None - works with any IDE/AI              |
| OpenSpec | None - AGENTS.md compatible with any tool |
| Kiro     | **High** - Kiro IDE + Claude Sonnet only  |

***

## Cost Comparison

| Tool       | Cost                                     |
| ---------- | ---------------------------------------- |
| specs.md   | \$0 + API tokens                         |
| Spec Kit   | \$0 + API tokens                         |
| BMAD       | \$0 + API tokens                         |
| OpenSpec   | \$0 + API tokens                         |
| Kiro Pro   | \$20/month (225 vibe + 125 spec/mo)      |
| Kiro Pro+  | \$39/month (450 vibe + 250 spec/mo)      |
| Kiro Power | \$200/month (2,250 vibe + 1,250 spec/mo) |

***

## Roadmap

| Feature                | Status    | Description                                                        |
| ---------------------- | --------- | ------------------------------------------------------------------ |
| **AI-DLC Flow**        | Available | Full methodology with DDD, 4 agents                                |
| **Simple Flow**        | Available | Spec generation (requirements, design, tasks)                      |
| **FIRE Flow**          | Available | Rapid execution with adaptive checkpoints                          |
| **Brownfield Support** | Available | First-class in [FIRE Flow](/fire-flow/monorepo-support)            |
| **Monorepo Support**   | Available | Hierarchical standards in [FIRE Flow](/fire-flow/monorepo-support) |
| **VS Code Extension**  | Available | Visual dashboard for all flows                                     |

<Info>
  **Start where you are**: Use Simple for quick specs, FIRE for rapid execution, or AI-DLC for full methodology. No upgrade path required—each flow is designed for different needs.
</Info>

<Card title="Request a Feature" icon="message" href="/feedback">
  Have a feature request or feedback? Let us know what you'd like to see in specs.md.
</Card>

***

## Further Reading

<CardGroup>
  <Card title="The AI-Native SDLC: Reimagined" icon="bolt" href="/methodology/sdlc-reimagined">
    Why the Agentic Age demands a new methodology
  </Card>

  <Card title="What is AI-DLC?" icon="circle-question" href="/methodology/what-is-ai-dlc">
    Deep dive into AI-DLC methodology
  </Card>
</CardGroup>


# specs.md vs BMAD-Method
Source: https://specs.md/compare/vs-bmad

Compare specs.md with BMAD's multi-agent framework

## Overview

Both **specs.md (AI-DLC)** and **BMAD-Method** target complex systems and enterprise-scale development. The key difference is their approach to agent organization.

**BMAD-Method** uses 19+ role-based agents that simulate a full development team (Analyst, PM, Architect, Developer, QA, etc.).

**specs.md (AI-DLC)** uses 3 phase-based agents aligned to AI-DLC's methodology (Inception, Construction, Operations).

***

## Side-by-Side Comparison

| Aspect                | specs.md                                                    | BMAD                                      |
| --------------------- | ----------------------------------------------------------- | ----------------------------------------- |
| **Target Complexity** | Complex systems (same tier)                                 | Complex/Enterprise systems (same tier)    |
| **Origin**            | AWS formal methodology                                      | Community-driven framework                |
| **Agent Philosophy**  | 3 phase-based agents                                        | 19+ role-based agents                     |
| **Agents**            | Master, Inception, Construction, Operations                 | Analyst, PM, Architect, Dev, QA, UX, etc. |
| **Methodology**       | AI-DLC (AWS standard)                                       | Agentic Agile (open source)               |
| **Design Technique**  | DDD integrated as core                                      | Optional, team choice                     |
| **Rituals**           | Mob Elaboration, Mob Construction (collocated)              | Agent handoffs (async)                    |
| **Iteration**         | Bolts ("hours or days")                                     | Epics/Stories                             |
| **Complexity**        | Moderate                                                    | High                                      |
| **Customization**     | Skills + Templates                                          | Full persona customization via YAML       |
| **Community**         | Just born (December 2025)                                   | 26k+ GitHub stars                         |
| **VS Code Extension** | Yes ([visual dashboard](/getting-started/vscode-extension)) | No                                        |

***

## When to Choose Each

<CardGroup>
  <Card title="Choose specs.md (AI-DLC) if:" icon="check">
    * You want a formal AWS methodology
    * You prefer fewer, phase-aligned agents
    * You want DDD as an integral part (not optional)
    * You value collocated Mob rituals
    * You want to avoid managing 19 agents
    * You want a [VS Code extension](/getting-started/vscode-extension) to track progress visually
  </Card>

  <Card title="Choose BMAD if:" icon="check">
    * You want maximum agent customization
    * You prefer role-based agent simulation
    * You're comfortable with higher complexity
    * You want 19+ specialized personas
    * You prefer async agent handoffs
    * You have time to invest in learning
  </Card>
</CardGroup>

***

## Key Differences

### 1. Agent Organization

**BMAD**: Focuses on traditional Agile roles—19+ agents mimicking a full development team with familiar titles.

```
Analyst Agent → PM Agent → Architect Agent →
Product Owner Agent → Scrum Master Agent →
Developer Agent → QA Agent → ...
```

**specs.md (AI-DLC)**: Focuses on AI development lifecycle phases with shorter iterations (Bolts, not sprints). 3 agents aligned to process phases.

```
Inception Agent → Construction Agent → Operations Agent
```

### 2. Methodology Foundation

**BMAD**: "Breakthrough Method for Agile AI-Driven Development" - an open source framework built on agile principles with AI agents replacing human roles.

**specs.md**: AWS's formally defined AI-DLC methodology with specific phases, rituals, and artifacts documented in a whitepaper.

### 3. Design Technique Integration

**BMAD**: Design techniques are optional. Teams can choose their own approach.

**specs.md**: DDD is integrated as core. AI applies domain-driven design principles during decomposition—it's not optional.

### 4. Rituals and Collaboration

**BMAD**: Agents hand off documents to each other asynchronously.

**specs.md**: Mob Elaboration and Mob Construction are collocated rituals where teams work together with AI in real-time.

***

## Agent Mapping

If you're familiar with BMAD agents, here's how they map to AI-DLC:

| BMAD Agents                 | specs.md Phase                                                 |
| --------------------------- | -------------------------------------------------------------- |
| Analyst, PM                 | **Inception Agent** - requirements elaboration                 |
| Architect                   | **Inception Agent** + **Construction Agent** - domain modeling |
| Product Owner, Scrum Master | **Master Agent** - orchestration                               |
| Developer, QA               | **Construction Agent** - code generation, testing              |
| DevOps                      | **Operations Agent** - deployment                              |

***

## Complexity vs Control Trade-off

```mermaid actions={false} theme={null}
flowchart LR
    SM(specs.md<br/>3 agents):::done --> |"More agents<br/>More control"| BM(BMAD<br/>19+ agents):::design
    BM --> |"Fewer agents<br/>Simpler mental model"| SM
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

***

## Migration Path

If you're currently using BMAD and want to try AI-DLC:

<Steps>
  <Step title="Map Your Agents">
    Understand how your 19 agents map to 3 AI-DLC phases
  </Step>

  <Step title="Adopt Mob Rituals">
    Replace async handoffs with collocated Mob Elaboration and Mob Construction
  </Step>

  <Step title="Integrate DDD">
    Move from optional design techniques to DDD as core
  </Step>

  <Step title="Use Phase-Based Thinking">
    Organize work by phase (Inception → Construction → Operations) rather than role
  </Step>
</Steps>

***

## Summary

| For This Need                      | Use This |
| ---------------------------------- | -------- |
| Formal AWS methodology             | specs.md |
| Maximum agent customization        | BMAD     |
| Simpler mental model (3 agents)    | specs.md |
| Role-based simulation (19+ agents) | BMAD     |
| DDD as core requirement            | specs.md |
| Collocated Mob rituals             | specs.md |
| Async agent handoffs               | BMAD     |

<Info>
  **Bottom Line**: Both target complex systems. specs.md offers a formal methodology with 3 phase-based agents. BMAD offers maximum customization with 19+ role-based agents.

  *Choose based on whether you prefer methodology-driven simplicity or agent-driven flexibility.*
</Info>


# specs.md vs Kiro (AWS)
Source: https://specs.md/compare/vs-kiro

Compare specs.md with AWS Kiro IDE

## Overview

**Kiro** is AWS's agentic IDE built on Code OSS (VS Code foundation) with integrated spec-driven development, agent hooks, and deep AWS integration. **To use Kiro's spec-driven features, you must use their paid IDE**—there's no way to use the methodology with your preferred tools.

**specs.md** is an IDE-agnostic framework implementing AWS's AI-DLC methodology. It works with 11+ AI coding tools including Claude Code, Cursor, GitHub Copilot, Windsurf, and more. Your specs and agents are portable markdown files—no vendor lock-in.

<Info>
  **Available Now**: [specs.md (Simple Flow)](/simple-flow/overview) provides Kiro-style Requirements → Design → Tasks workflow.
</Info>

***

## Side-by-Side Comparison

| Aspect                | specs.md                                                    | Kiro                                                         |
| --------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
| **Type**              | Framework/CLI                                               | Full IDE                                                     |
| **IDE**               | Works with any (Cursor, VS Code, Claude Code, etc.)         | Kiro IDE only                                                |
| **Workflow**          | AI-DLC: Inception → Construction → Operations               | Requirements → Design → Tasks                                |
| **Methodology**       | Formal AI-DLC phases and rituals                            | Kiro SDD workflow                                            |
| **Automation**        | Skills + Templates                                          | Agent Hooks + Steering                                       |
| **Context**           | Memory Bank (persistent project knowledge)                  | requirements.md, design.md, tasks.md + steering files        |
| **AI Model**          | Any (Claude, GPT, Gemini, etc.)                             | Claude Sonnet 4.5 + Auto mode                                |
| **Pricing**           | Free (open source)                                          | Free preview → $20/mo (Pro), $39/mo (Pro+), \$200/mo (Power) |
| **Spec Format**       | Markdown + YAML                                             | EARS notation for requirements                               |
| **Lock-in**           | None                                                        | Kiro IDE + Claude only                                       |
| **VS Code Extension** | Yes ([visual dashboard](/getting-started/vscode-extension)) | Built into IDE (limited)                                     |
| **Maturity**          | Production-ready                                            | Preview (July 2025)                                          |

***

## When to Choose Each

<CardGroup>
  <Card title="Choose specs.md (AI-DLC) if:" icon="check">
    * You want IDE flexibility (not locked to Kiro)
    * You prefer AI-DLC's formal 3-phase methodology
    * You want to use your preferred AI model
    * You want to use free AI tools (Copilot, Cline, Kilo Code, etc.)
    * You need Mob rituals for team collaboration
    * You want DDD as an integral part
    * You want a [VS Code extension](/getting-started/vscode-extension) to track progress visually
  </Card>

  <Card title="Choose Kiro if:" icon="check">
    * You want an all-in-one IDE experience
    * You're heavily invested in AWS ecosystem
    * You want built-in agent hooks for automation
    * You prefer visual spec generation
    * You're okay with Claude Sonnet only
    * You're okay with subscription pricing
  </Card>
</CardGroup>

***

## Key Differences

### 1. IDE Lock-in (Paid)

**Kiro**: Requires Kiro IDE subscription (\$19-39/month) to use spec-driven features. You cannot use Kiro's methodology in VS Code, Cursor, or other editors.

**specs.md**: Works with **11+ tools** including Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Roo, Gemini CLI, Codex CLI, OpenCode, and more. Your specs are portable markdown files—switch tools anytime.

### 2. AI Model Flexibility

**Kiro**: Uses Claude Sonnet 4.5 with an "Auto" mode that mixes frontier models. No option to use GPT, Gemini, or bring your own API key.

**specs.md**: Works with any AI model. Use whichever model works best for your use case.

### 3. Pricing Model

**Kiro** (revised August 2025):

* Free: 50 vibe requests (no spec requests)
* Pro: \$20/month (225 vibe, 125 spec requests)
* Pro+: \$39/month (450 vibe, 250 spec requests)
* Power: \$200/month (2,250 vibe, 1,250 spec requests)

**specs.md**:

* Free (open source)
* Pay only for your AI API tokens

### 4. Context Management

**Kiro** uses simple spec files + steering:

```
.kiro/
├── requirements.md   # Requirements spec
├── design.md         # Design spec
├── tasks.md          # Task breakdown
└── steering/         # Agent steering files
```

**specs.md** uses Memory Bank:

```
memory-bank/
├── context-config.yaml    # Phase-aware context
├── artifacts/             # Persistent artifacts
└── standards/             # Project standards
```

### 5. Automation Approach

**Kiro** uses Agent Hooks (event-driven):

```yaml theme={null}
# .kiro/hooks/update-tests.yaml
trigger: on_save
pattern: "**/*.tsx"
action: "Update related test file"
```

**specs.md** uses Skills and Templates:

```yaml theme={null}
# skills/construction/domain-modeling.yaml
name: Domain Modeling
triggers:
  - bolt-start
  - domain-design
actions:
  - Apply DDD principles
  - Generate component model
```

<Info>
  **Available Now**: [specs.md (Simple Flow)](/simple-flow/overview) provides Kiro-style Requirements → Design → Tasks workflow.
</Info>

***

## Feature Comparison

### Kiro's Unique Features

| Feature             | Description                                       |
| ------------------- | ------------------------------------------------- |
| **EARS Notation**   | Structured requirements format                    |
| **Agent Hooks**     | Event-driven automations on file save/create      |
| **MCP Integration** | Connect external tools via Model Context Protocol |
| **Autopilot Mode**  | AI works autonomously on foundational tasks       |
| **AWS Powers**      | One-click AWS service integrations                |

### specs.md Unique Features

| Feature                                                    | Description                                              |
| ---------------------------------------------------------- | -------------------------------------------------------- |
| **Mob Rituals**                                            | Collocated team collaboration with AI                    |
| **DDD as Core**                                            | Domain-driven design integrated, not optional            |
| **Phase-Based Agents**                                     | 3 agents aligned to AI-DLC phases                        |
| **Bolts**                                                  | Rapid iteration cycles (hours/days, not weeks)           |
| **IDE Freedom**                                            | Works with any IDE and AI model                          |
| **[VS Code Extension](/getting-started/vscode-extension)** | Visual dashboard for tracking bolts, specs, and progress |

***

## Cost Comparison

| Tool       | Cost                                     |
| ---------- | ---------------------------------------- |
| specs.md   | \$0 + API tokens                         |
| Kiro Pro   | \$20/month (225 vibe + 125 spec/mo)      |
| Kiro Pro+  | \$39/month (450 vibe + 250 spec/mo)      |
| Kiro Power | \$200/month (2,250 vibe + 1,250 spec/mo) |

***

## Migration Path

If you're using Kiro and want more methodology structure:

<Steps>
  <Step title="Export Kiro Specs">
    Convert Kiro's requirements.md, design.md, tasks.md to specs.md Memory Bank format
  </Step>

  <Step title="Map Hooks to Skills">
    Convert agent hooks to specs.md skills (or wait for Simple Flow with hook support)
  </Step>

  <Step title="Adopt AI-DLC Phases">
    Organize work into Inception, Construction, Operations
  </Step>

  <Step title="Add Mob Rituals">
    Introduce Mob Elaboration and Mob Construction for team alignment
  </Step>
</Steps>

***

## Summary

| For This Need        | Use This                                |
| -------------------- | --------------------------------------- |
| IDE flexibility      | specs.md                                |
| All-in-one IDE       | Kiro                                    |
| AI model choice      | specs.md                                |
| AWS deep integration | Kiro                                    |
| Free/open source     | specs.md                                |
| Built-in agent hooks | Kiro (or wait for specs.md Simple Flow) |
| Formal methodology   | specs.md                                |
| Mob rituals          | specs.md                                |

<Info>
  **Bottom Line**: Kiro offers a polished, all-in-one experience with AWS integration. specs.md offers methodology depth, IDE freedom, and no subscription costs.

  *Want Kiro's simplicity with AI-DLC's methodology? Try [specs.md (Simple Flow)](/simple-flow/overview).*
</Info>


# specs.md vs OpenSpec
Source: https://specs.md/compare/vs-openspec

Compare specs.md with OpenSpec's change-centric approach

## Overview

**OpenSpec** is a lightweight, brownfield-first CLI tool focused on change management. It separates current truth (`specs/`) from proposed changes (`changes/`).

**specs.md** is a full lifecycle methodology covering Inception through Operations, with support for both greenfield and brownfield development.

***

## Side-by-Side Comparison

| Aspect                 | specs.md                                                    | OpenSpec                                     |
| ---------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| **Primary Focus**      | Full lifecycle (Inception → Operations)                     | Change management                            |
| **Best For**           | Greenfield + brownfield                                     | Greenfield + brownfield (brownfield-focused) |
| **Philosophy**         | Complete methodology                                        | Lightweight, change-centric                  |
| **Structure**          | Intents → Units → Stories                                   | Specs + Changes separation                   |
| **Brownfield Support** | Supported (with model elevation)                            | Excellent (primary design focus)             |
| **Token Efficiency**   | Both (Units scope context)                                  | Both (spec deltas)                           |
| **Design Integration** | DDD as core                                                 | Design-agnostic (your choice)                |
| **Rituals**            | Mob Elaboration, Mob Construction                           | None                                         |
| **Learning Curve**     | Moderate                                                    | Low                                          |
| **VS Code Extension**  | Yes ([visual dashboard](/getting-started/vscode-extension)) | CLI dashboard                                |

***

## When to Choose Each

<CardGroup>
  <Card title="Choose specs.md (AI-DLC) if:" icon="check">
    * You need full project lifecycle support
    * You're building new features (greenfield)
    * You want DDD integration
    * You need Mob rituals for team alignment
    * You want formal methodology structure
    * You want a [VS Code extension](/getting-started/vscode-extension) to track progress visually
  </Card>

  <Card title="Choose OpenSpec if:" icon="check">
    * You primarily make incremental changes
    * You're working with existing codebases
    * You want maximum token efficiency
    * You prefer minimal overhead
    * You want the simplest possible setup
    * You make high-volume, small-scope changes
  </Card>
</CardGroup>

***

## Key Differences

### 1. Design Philosophy

**OpenSpec**: Brownfield-first. Designed for modifying existing systems with a clear separation between current state and proposed changes.

```
openspec/
├── specs/      # Current truth (what exists)
└── changes/    # Proposed updates (what's changing)
```

**specs.md**: Full lifecycle. Designed for complex systems from inception through operations.

```
memory-bank/
├── intents/           # High-level goals
├── units/             # Decomposed work
├── construction/      # Domain models, code
└── operations/        # Deployment, monitoring
```

### 2. Token Efficiency

**OpenSpec**: Excellent token efficiency. Only sends "spec deltas" (proposed changes) to the LLM, not the full codebase context.

**specs.md**: Memory Bank provides structured context. You can achieve similar change-focused efficiency by creating Units specifically for changes—keeping context scoped to what matters.

| Approach | Token Usage | Best For                                 |
| -------- | ----------- | ---------------------------------------- |
| OpenSpec | Lower       | High-volume small changes                |
| specs.md | Higher      | Complex decisions requiring full context |

### 3. Brownfield Handling

**OpenSpec**: Primary design focus. Every change is explicit with clear before/after separation.

**specs.md**: Supported via "model elevation" - AI first converts existing code to semantic models (domain components, relationships) before making changes. *More advanced brownfield process coming soon.*

```
AI-DLC Brownfield Flow:
Existing Code → Semantic Models → Changes → Updated Code
```

### 4. Methodology vs Tool

**OpenSpec**: A tool for managing specs and changes. No prescribed methodology.

**specs.md**: A complete methodology with:

* Defined phases (Inception → Construction → Operations)
* Rituals (Mob Elaboration, Mob Construction)
* Design integration (DDD as core)
* Role definitions (AI drives, human validates)

***

## Use Case Comparison

| Use Case                        | OpenSpec  | specs.md  |
| ------------------------------- | --------- | --------- |
| Small bug fix                   | Excellent | Overkill  |
| Feature tweak                   | Excellent | Good      |
| New feature (existing codebase) | Good      | Excellent |
| New system (greenfield)         | Limited   | Excellent |
| Complex refactoring             | Good      | Excellent |
| Multi-team coordination         | Limited   | Excellent |

***

## Summary

| For This Need             | Use This                                |
| ------------------------- | --------------------------------------- |
| Brownfield changes        | OpenSpec (excellent) or specs.md (good) |
| Greenfield development    | specs.md                                |
| Token efficiency          | Both                                    |
| Full lifecycle            | specs.md                                |
| Minimal setup             | OpenSpec                                |
| DDD integration           | specs.md                                |
| Team rituals              | specs.md                                |
| High-volume small changes | OpenSpec                                |

<Info>
  **Bottom Line**: OpenSpec excels at brownfield changes with minimal overhead. specs.md provides full lifecycle support for complex systems.

  *For brownfield work within a larger project, consider using both together.*
</Info>


# specs.md vs GitHub Spec Kit
Source: https://specs.md/compare/vs-speckit

Compare specs.md with GitHub's Spec Kit toolkit

## Overview

**GitHub Spec Kit** is a toolkit that provides agent prompts and 7 slash commands (`/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.analyze`, `/speckit.implement`, `/speckit.clarify`) for 15+ AI coding assistants including Claude Code, Cursor, GitHub Copilot, and Gemini CLI.

**specs.md** is a full methodology implementation with phase-based agents, Mob rituals, and DDD integration.

<Info>
  **Available Now**: [specs.md (Simple Flow)](/simple-flow/overview) provides Spec Kit-like simple flows for teams wanting a lighter entry point.
</Info>

***

## Side-by-Side Comparison

| Aspect                 | specs.md                                                    | Spec Kit                                                    |
| ---------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| **Type**               | Full methodology                                            | Toolkit + Agent Prompts                                     |
| **Target**             | Complex systems requiring trade-offs                        | Small-medium projects                                       |
| **Approach**           | Structured AI-DLC phases with methodology                   | 6-phase workflow with agent prompts                         |
| **Structure**          | Intents → Units → Stories                                   | Constitution → Specify → Plan → Tasks → Analyze → Implement |
| **Agent Model**        | 3 phase-based agents                                        | Prompts for 15+ AI assistants                               |
| **Design Integration** | DDD default (extensible via bolt types)                     | Constitution file                                           |
| **Rituals**            | Mob Elaboration, Mob Construction                           | None                                                        |
| **Memory**             | Memory Bank (persistent context)                            | Constitution file + .specify folder                         |
| **Customization**      | Skills, templates, memory bank                              | Constitution file, scripts, templates                       |
| **Learning Curve**     | Moderate                                                    | Low                                                         |
| **VS Code Extension**  | Yes ([visual dashboard](/getting-started/vscode-extension)) | No                                                          |

***

## When to Choose Each

<CardGroup>
  <Card title="Choose specs.md (AI-DLC) if:" icon="check">
    * You're building complex systems with architectural trade-offs
    * You need DDD integration and domain modeling
    * You want Mob rituals for team alignment
    * You have multiple teams needing coordination
    * You want a proven AWS methodology
    * You want a [VS Code extension](/getting-started/vscode-extension) to track progress visually
  </Card>

  <Card title="Choose Spec Kit if:" icon="check">
    * You want minimal workflow change
    * You're working on simpler projects
    * You prefer command-driven interaction
    * You want the lowest learning curve
    * You want minimal ceremony
  </Card>
</CardGroup>

***

## Key Differences

### 1. Methodology vs Toolkit

**Spec Kit** is a toolkit—a set of commands that structure your prompts. It doesn't prescribe how you work, just helps you write better specs.

**specs.md** is a full methodology with:

* Defined phases (Inception → Construction → Operations)
* Rituals (Mob Elaboration, Mob Construction)
* Role definitions (AI drives, human validates)
* Artifact specifications (Intents, Units, Bolts)

### 2. Conversation Direction

**Spec Kit**: Agent-driven via structured prompts

```
Human: /speckit.specify [high-level description]
AI: [generates detailed specification with user journeys]
AI: [asks clarifying questions via /speckit.clarify]
Human: [validates and refines]
```

**specs.md**: AI drives with Mob rituals

```
Human: [provides intent]
AI: "I've analyzed your intent. Here are 3 Units I propose.
     I have 5 clarifying questions before we proceed..."
Human: [validates, approves, or redirects in Mob session]
```

### 3. Design Integration

**Spec Kit**: Constitution file sets project principles and constraints. Technical plan phase handles architecture decisions.

**specs.md**: DDD is the default methodology. AI applies domain-driven design principles during decomposition, creating bounded contexts, aggregates, and domain models. Extensible via bolt types for BDD, TDD, or custom flows.

***

## AI-DLC's Opinionated Approach

Unlike toolkit-based approaches, AI-DLC is an opinionated methodology with specific patterns:

**Bolts, Not Sprints**: Instead of 2-week sprints with variable scope, AI-DLC uses Bolts—focused execution units measured in hours or days. Each Bolt batches related stories together and executes them with full DDD construction steps.

**DDD Baked In**: Domain-Driven Design isn't optional—it's integral. Every Bolt follows DDD patterns: domain modeling, bounded contexts, aggregates, and entities. This creates consistent, high-quality designs regardless of who's working.

**Agent Drives, Human Validates**: In AI-DLC, the AI proposes breakdown, trade-offs, and designs. Humans validate and approve. This reversed conversation direction keeps humans in control while leveraging AI's synthesis capabilities.

**Full Traceability**: Artifacts created during construction show exactly what was built and how—from Intent to Unit to Story to Bolt execution.

***

## Migration Path

If you're currently using Spec Kit and want more structure:

<Steps>
  <Step title="Start with Simple Flow">
    [specs.md (Simple Flow)](/simple-flow/overview) provides Kiro-style Requirements → Design → Tasks workflow
  </Step>

  <Step title="Add Memory Bank">
    Enable persistent context across sessions
  </Step>

  <Step title="Adopt Phase Structure">
    Organize work into Inception, Construction, Operations
  </Step>

  <Step title="Graduate to Full AI-DLC">
    When complexity demands it, adopt full Mob rituals and DDD integration
  </Step>
</Steps>

***

## Summary

| For This Need                     | Use This                           |
| --------------------------------- | ---------------------------------- |
| Quick spec generation             | Spec Kit or specs.md (Simple Flow) |
| Minimal learning curve            | Spec Kit                           |
| Complex system development        | specs.md                           |
| Team coordination                 | specs.md                           |
| Enterprise/regulated environments | specs.md                           |
| DDD integration                   | specs.md                           |

<Info>
  **Bottom Line**: Spec Kit is great for adding light structure. specs.md is for when you need a complete methodology for complex systems.

  *Can't decide? Try [specs.md (Simple Flow)](/simple-flow/overview)—start simple, graduate when needed.*
</Info>


# Bolts
Source: https://specs.md/core-concepts/bolts

Time-boxed execution sessions for rapid implementation

## What is a Bolt?

A **Bolt** is a time-boxed execution session in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are completed in **hours to days**. Each bolt encapsulates a well-defined scope of work scoped to a Unit.

<Info>
  The term "Bolt" emphasizes speed and precision - like a bolt of lightning, work happens fast but with focused energy. Bolts are analogous to Sprints in Scrum, but optimized for AI-driven development.
</Info>

## Bolt Characteristics

<CardGroup>
  <Card title="Rapid" icon="bolt">
    Hours to days, not weeks
  </Card>

  <Card title="Focused" icon="bullseye">
    One story or small set of related stories
  </Card>

  <Card title="Stage-Gated" icon="door-open">
    Validated checkpoints prevent errors
  </Card>

  <Card title="Complete" icon="check-double">
    Produces working, tested code
  </Card>
</CardGroup>

## Bolt Types

specs.md currently supports two bolt types:

| Type                    | Best For                                | Stages                                  |
| ----------------------- | --------------------------------------- | --------------------------------------- |
| **DDD Construction**    | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
| **Simple Construction** | UI, integrations, utilities             | Plan → Implement → Test                 |

### Choosing a Bolt Type

<AccordionGroup>
  <Accordion title="Use DDD Construction Bolt when...">
    * Building complex domain logic with business rules
    * Creating bounded contexts with rich domain models
    * Implementing services that require domain expertise
    * Working on core business functionality
  </Accordion>

  <Accordion title="Use Simple Construction Bolt when...">
    * Building frontend pages and components
    * Creating simple CRUD endpoints
    * Integrating with external APIs
    * Writing utilities and helper modules
    * Building CLI commands or scripts
  </Accordion>
</AccordionGroup>

## DDD Construction Bolt

The most comprehensive bolt type, used for complex domain logic:

<Steps>
  <Step title="Domain Model">
    Model business logic using DDD principles:

    * Identify aggregates, entities, value objects
    * Define domain events and commands
    * Establish ubiquitous language
  </Step>

  <Step title="Technical Design">
    Apply patterns and make architecture decisions:

    * Choose implementation patterns
    * Define interfaces and contracts
    * Plan data structures and APIs
  </Step>

  <Step title="ADR Analysis">
    Document significant decisions:

    * Context and problem
    * Options considered
    * Decision and rationale
  </Step>

  <Step title="Implement">
    Generate production code:

    * Follow coding standards
    * Apply design patterns
    * Write clean, documented code
  </Step>

  <Step title="Test">
    Verify correctness:

    * Unit tests
    * Integration tests
    * Acceptance tests
  </Step>
</Steps>

## Simple Construction Bolt

A lightweight bolt for UI, integrations, and utilities:

<Steps>
  <Step title="Plan">
    Define what to build:

    * Review stories and requirements
    * List specific deliverables
    * Identify dependencies
    * Define acceptance criteria
  </Step>

  <Step title="Implement">
    Write the code:

    * Setup file structure
    * Implement core functionality
    * Handle edge cases
    * Add documentation
  </Step>

  <Step title="Test">
    Verify the implementation:

    * Write unit tests
    * Run test suite
    * Verify acceptance criteria
    * Document results
  </Step>
</Steps>

## Human Checkpoints

<Warning>
  Human validation happens at each checkpoint. You cannot proceed to the next stage without approval. This is the "Human Oversight as Loss Function" principle - catching errors early before they cascade.
</Warning>

### DDD Construction Checkpoints

```mermaid actions={false} theme={null}
flowchart LR
    M(Model):::plan --> G1{{"✋"}}:::check --> D(Design):::plan --> G2{{"✋"}}:::check --> A(ADR):::plan --> G3{{"✋"}}:::check --> I(Implement):::build --> G4{{"✋"}}:::check --> T(Test):::done --> G5{{"✋"}}:::check
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

### Simple Construction Checkpoints

```mermaid actions={false} theme={null}
flowchart LR
    P(Plan):::plan --> G1{{"✋"}}:::check --> I(Implement):::build --> G2{{"✋"}}:::check --> T(Test):::done --> G3{{"✋"}}:::check
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

## Executing Bolts

Start a bolt with the Construction Agent:

```bash theme={null}
/specsmd-construction-agent --unit="my-unit"
```

The agent will:

1. Show available bolts for the unit
2. Ask which bolt to work on
3. Guide you through each stage
4. Generate artifacts at each step
5. Wait for your approval at gates
6. Record progress in the Memory Bank

## Bolt Artifacts

Each bolt produces artifacts stored in the Memory Bank:

<Tabs>
  <Tab title="DDD Construction">
    ```
    memory-bank/bolts/{bolt-id}/
    ├── bolt.md                    # Bolt metadata and state
    ├── ddd-01-domain-model.md     # Domain model
    ├── ddd-02-technical-design.md # Technical design
    ├── adr-*.md                   # Architecture Decision Records (optional)
    └── ddd-03-test-report.md      # Test results
    ```
  </Tab>

  <Tab title="Simple Construction">
    ```
    memory-bank/bolts/{bolt-id}/
    ├── bolt.md                    # Bolt metadata and state
    ├── implementation-plan.md     # Plan from Stage 1
    ├── implementation-walkthrough.md # Developer notes from Stage 2
    └── test-walkthrough.md        # Test results from Stage 3
    ```
  </Tab>
</Tabs>

## Bolt Commands

| Command       | Purpose                  |
| ------------- | ------------------------ |
| `bolt-list`   | List all bolts in unit   |
| `bolt-start`  | Start or continue a bolt |
| `bolt-status` | Check current progress   |
| `bolt-replan` | Replan if scope changed  |

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Bolts Small">
    A bolt should complete in hours to a few days. If it's taking longer, the scope is too big - split it into multiple bolts.
  </Accordion>

  <Accordion title="Choose the Right Bolt Type">
    Use DDD for complex domain logic, Simple for UI/utilities. Don't over-engineer simple tasks.
  </Accordion>

  <Accordion title="Don't Skip Stages">
    Each stage builds on the previous. Skipping creates technical debt and increases risk.
  </Accordion>

  <Accordion title="Validate Thoroughly">
    Use gate reviews to catch issues early. It's cheaper to fix problems in design than in code.
  </Accordion>

  <Accordion title="Document Decisions">
    ADRs capture the "why" behind decisions. Future you will thank present you.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Memory Bank" icon="arrow-right" href="/core-concepts/memory-bank">
    Learn how artifacts are persisted and connected
  </Card>

  <Card title="Bolt Types Guide" icon="book" href="/guides/bolt-types">
    Detailed guide on choosing and using bolt types
  </Card>
</CardGroup>


# Intents
Source: https://specs.md/core-concepts/intents

High-level statements of purpose that drive development

## What is an Intent?

An **Intent** is a high-level statement of purpose that encapsulates what needs to be achieved - whether a business goal, feature, or technical outcome. It serves as the starting point for AI-driven decomposition.

<Info>
  Think of an Intent as the answer to "What do we want to build?" without getting into the details of "How do we build it?"
</Info>

## Examples of Intents

Good intents are clear, outcome-focused, and appropriately scoped:

<CardGroup>
  <Card title="User Authentication System" icon="lock">
    Enable users to securely register, login, and manage their accounts
  </Card>

  <Card title="Product Catalog with Search" icon="magnifying-glass">
    Allow customers to browse and search products with filters
  </Card>

  <Card title="Payment Processing" icon="credit-card">
    Integrate payment gateway for secure transactions
  </Card>

  <Card title="Real-time Notifications" icon="bell">
    Push notifications to users for important events
  </Card>
</CardGroup>

## Intent Structure

When captured, an Intent becomes a directory in your Memory Bank:

```
memory-bank/intents/{intent-name}/
├── requirements.md      # User stories, acceptance criteria, NFRs
├── system-context.md    # Boundaries, interfaces, constraints
└── units/               # Decomposed units
    ├── {unit-1}/
    └── {unit-2}/
```

## Creating an Intent

Use the Inception Agent to create intents:

```bash theme={null}
/specsmd-inception-agent intent-create
```

The agent will guide you through:

<Steps>
  <Step title="Describe Your Goal">
    Explain what you want to achieve in plain language
  </Step>

  <Step title="Answer Clarifying Questions">
    The AI asks questions to minimize ambiguity
  </Step>

  <Step title="Review Requirements">
    Validate the generated user stories and NFRs
  </Step>

  <Step title="Define Context">
    Establish system boundaries and constraints
  </Step>
</Steps>

## Intent vs Epic

| Aspect            | Agile Epic         | AI-DLC Intent            |
| ----------------- | ------------------ | ------------------------ |
| **Definition**    | Large body of work | Statement of purpose     |
| **Decomposition** | Manual by team     | AI-powered               |
| **Output**        | User stories       | Units with stories       |
| **Context**       | Lost over time     | Persisted in Memory Bank |

## Requirements Document

The `requirements.md` file contains:

```markdown theme={null}
# Intent: User Authentication System

## User Stories

### US-001: User Registration
As a new user, I want to register with email and password
so that I can create an account.

**Acceptance Criteria:**
- [ ] Email validation
- [ ] Password strength requirements
- [ ] Confirmation email sent

### US-002: User Login
...

## Non-Functional Requirements

### NFR-001: Security
- Passwords must be hashed with bcrypt
- Sessions expire after 24 hours
- Rate limiting on login attempts

### NFR-002: Performance
- Login response time < 500ms
- Support 1000 concurrent users
```

## System Context

The `system-context.md` defines boundaries:

```markdown theme={null}
# System Context: User Authentication

## In Scope
- User registration and login
- Password reset flow
- Session management

## Out of Scope
- Social login (OAuth) - future intent
- Multi-factor authentication - future intent

## Interfaces
- REST API for frontend
- Database for user storage
- Email service for notifications

## Constraints
- Must use existing PostgreSQL database
- Must integrate with current session store
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Intents Focused">
    One intent should represent one cohesive goal. If you find yourself saying "and also...", consider splitting into multiple intents.
  </Accordion>

  <Accordion title="Be Outcome-Oriented">
    Focus on what users will be able to do, not on technical implementation details.
  </Accordion>

  <Accordion title="Include Context">
    Provide relevant business context, constraints, and dependencies upfront.
  </Accordion>

  <Accordion title="Iterate on Requirements">
    Requirements will evolve. Use the agent to refine and clarify as you learn more.
  </Accordion>
</AccordionGroup>

## Next Steps

<Card title="Units" icon="arrow-right" href="/core-concepts/units">
  Learn how Intents are decomposed into Units
</Card>


# Memory Bank
Source: https://specs.md/core-concepts/memory-bank

File-based storage for all project artifacts with full traceability

## What is the Memory Bank?

The **Memory Bank** is a file-based storage system for all project artifacts. It maintains context across agent sessions and provides traceability between artifacts.

<Info>
  Unlike traditional documentation that gets stale, the Memory Bank is actively used by agents. It's the source of truth that agents read and write.
</Info>

## Why Memory Bank?

<CardGroup>
  <Card title="Context Engineering" icon="database">
    Agents reload context from Memory Bank each session. No more lost knowledge.
  </Card>

  <Card title="Traceability" icon="link">
    Every artifact links to its source. Inception and construction logs provide full traceability after completion.
  </Card>

  <Card title="Human Readable" icon="file-lines">
    All files are Markdown. Review, edit, and version control with Git.
  </Card>

  <Card title="AI Accessible" icon="robot">
    Structured format that agents can parse and update.
  </Card>
</CardGroup>

## Structure

After project initialization:

```
memory-bank/
├── intents/                   # Your captured intents
│   └── {intent-name}/
│       ├── requirements.md
│       ├── system-context.md
│       └── units/
│           └── {unit-name}/
│               ├── unit-brief.md
│               ├── stories/
│               └── bolts/
├── bolts/                     # Bolt execution records
│   └── {bolt-id}/
│       ├── domain-model.md
│       ├── technical-design.md
│       └── implementation/
├── standards/                 # Project standards
│   ├── tech-stack.md
│   ├── coding-standards.md
│   ├── architecture.md
│   └── ux-guide.md
└── operations/                # Deployment context
    ├── environments.md
    └── runbooks/
```

## Artifact Types

### Standards

Project-wide decisions that inform AI code generation:

| File                  | Purpose                          |
| --------------------- | -------------------------------- |
| `tech-stack.md`       | Languages, frameworks, databases |
| `coding-standards.md` | Formatting, naming, patterns     |
| `architecture.md`     | System architecture decisions    |
| `ux-guide.md`         | Design system, styling           |
| `api-conventions.md`  | API style, versioning            |

### Intent Artifacts

Captured requirements and context:

| File                | Purpose                                 |
| ------------------- | --------------------------------------- |
| `requirements.md`   | User stories, acceptance criteria, NFRs |
| `system-context.md` | Boundaries, interfaces, constraints     |
| `units.md`          | Unit decomposition overview             |

### Unit Artifacts

Work breakdown within an intent:

| File            | Purpose                         |
| --------------- | ------------------------------- |
| `unit-brief.md` | Scope, interfaces, dependencies |
| `stories/*.md`  | Individual user stories         |
| `bolts/*/`      | Bolt execution records          |

### Bolt Artifacts

Implementation records:

| File                  | Purpose                        |
| --------------------- | ------------------------------ |
| `domain-model.md`     | DDD artifacts                  |
| `technical-design.md` | Architecture decisions         |
| `adr-*.md`            | Architectural Decision Records |
| `implementation/`     | Generated code                 |
| `tests/`              | Test files                     |

## Traceability

Artifacts link to each other using references:

```markdown theme={null}
# Technical Design: User Registration

## Source
- Intent: user-authentication
- Unit: user-registration  
- Story: US-001

## Related ADRs
- [ADR-001: Password Hashing Algorithm](./adr-001.md)

## Implementation
- [src/auth/registration.ts](../../src/auth/registration.ts)
```

## Agent Interaction

Agents read and write to the Memory Bank:

<Steps>
  <Step title="Context Loading">
    Agent reads relevant artifacts at session start
  </Step>

  <Step title="Work Execution">
    Agent generates new artifacts during work
  </Step>

  <Step title="Artifact Storage">
    Agent writes artifacts to Memory Bank
  </Step>

  <Step title="Reference Linking">
    Agent updates cross-references
  </Step>
</Steps>

## Version Control

The Memory Bank is designed for Git:

```bash theme={null}
# Track all artifacts
git add memory-bank/

# Meaningful commit messages
git commit -m "feat(auth): Complete user registration bolt"

# Review changes in PRs
git diff memory-bank/intents/auth/
```

<Warning>
  Commit Memory Bank changes along with code changes. This maintains the connection between decisions and implementation.
</Warning>

## Schema

The Memory Bank follows a schema defined in `.specsmd/aidlc/memory-bank.yaml`:

```yaml theme={null}
version: "1.0"
structure:
  intents:
    pattern: "{intent-name}/"
    required:
      - requirements.md
      - system-context.md
    optional:
      - units/
  standards:
    required:
      - tech-stack.md
      - coding-standards.md
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Artifacts Current">
    Update artifacts when decisions change. Stale documentation is worse than no documentation.
  </Accordion>

  <Accordion title="Use Consistent Formatting">
    Follow the templates. Consistent structure helps agents parse content.
  </Accordion>

  <Accordion title="Link Generously">
    Cross-reference related artifacts. Traceability prevents knowledge silos.
  </Accordion>

  <Accordion title="Version with Code">
    Commit Memory Bank changes with related code. They belong together.
  </Accordion>
</AccordionGroup>

## Next Steps

<Card title="Standards" icon="arrow-right" href="/core-concepts/standards">
  Learn about project standards that guide AI generation
</Card>


# Standards
Source: https://specs.md/core-concepts/standards

Project decisions that inform AI code generation

## What are Standards?

**Standards** are project decisions that inform AI code generation. They ensure consistency across all generated code and documentation.

<Info>
  Standards are established during project initialization and guide every agent interaction. They're the "rules of the road" for your project.
</Info>

## Standard Types

<CardGroup>
  <Card title="Tech Stack" icon="layer-group">
    Languages, frameworks, databases, infrastructure
  </Card>

  <Card title="Coding Standards" icon="code">
    Formatting, linting, naming, testing strategy
  </Card>

  <Card title="Architecture" icon="sitemap">
    Architecture style, API design, state management
  </Card>

  <Card title="UX Guide" icon="palette">
    Design system, styling, accessibility
  </Card>
</CardGroup>

## Establishing Standards

During project initialization:

```bash theme={null}
/specsmd-master-agent
> project-init
```

The Master Agent guides you through each standard category with facilitation guides.

## Tech Stack Standard

Defines your technology choices:

```markdown theme={null}
# Tech Stack

## Languages
- **Primary**: TypeScript 5.x
- **Secondary**: Python 3.11+ (for ML pipelines)

## Frontend
- **Framework**: React 18 with Next.js 14
- **Styling**: Tailwind CSS
- **State**: Zustand

## Backend
- **Runtime**: Node.js 20 LTS
- **Framework**: Express.js
- **ORM**: Prisma

## Database
- **Primary**: PostgreSQL 15
- **Cache**: Redis 7
- **Search**: Elasticsearch 8

## Infrastructure
- **Cloud**: AWS
- **Containers**: Docker
- **Orchestration**: ECS Fargate
- **CI/CD**: GitHub Actions
```

## Coding Standards

Defines how code should be written:

```markdown theme={null}
# Coding Standards

## Formatting
- Use Prettier with default config
- 2-space indentation
- Single quotes for strings
- Trailing commas in multiline

## Naming Conventions
- **Files**: kebab-case (user-service.ts)
- **Classes**: PascalCase (UserService)
- **Functions**: camelCase (getUserById)
- **Constants**: SCREAMING_SNAKE_CASE (MAX_RETRIES)

## Testing Strategy
- **Unit Tests**: Vitest for business logic
- **Integration Tests**: Supertest for APIs
- **E2E Tests**: Playwright for critical paths
- **Coverage Target**: 80% minimum

## Error Handling
- Use custom error classes extending BaseError
- Always include error codes
- Log errors with structured logging
- Never expose internal errors to clients
```

## Architecture Standard

Defines system design decisions:

```markdown theme={null}
# Architecture

## Style
- **Pattern**: Clean Architecture
- **API**: REST with OpenAPI 3.0
- **Communication**: Synchronous HTTP, async via SQS

## Layers
1. **Presentation**: Controllers, DTOs
2. **Application**: Use cases, services
3. **Domain**: Entities, value objects, events
4. **Infrastructure**: Repositories, external services

## API Design
- Resource-based URLs
- HTTP methods for actions
- JSON request/response bodies
- Pagination with cursor-based approach

## State Management
- Server state: React Query
- Client state: Zustand
- Form state: React Hook Form
```

## UX Guide (Optional)

Defines design system and styling:

```markdown theme={null}
# UX Guide

## Design System
- Based on custom design tokens
- Component library: shadcn/ui

## Colors
- Primary: #2563eb
- Secondary: #64748b
- Success: #10b981
- Error: #ef4444

## Typography
- Headings: Inter, sans-serif
- Body: Inter, sans-serif
- Mono: JetBrains Mono

## Spacing
- Base unit: 4px
- Scale: 4, 8, 12, 16, 24, 32, 48, 64

## Accessibility
- WCAG 2.1 AA compliance
- Keyboard navigation required
- Screen reader support
- Color contrast 4.5:1 minimum
```

## How Standards Are Used

Agents reference standards when generating code:

<Steps>
  <Step title="Context Loading">
    Agent reads all standards from Memory Bank
  </Step>

  <Step title="Decision Making">
    Standards inform architecture and design choices
  </Step>

  <Step title="Code Generation">
    Generated code follows coding standards
  </Step>

  <Step title="Validation">
    Output is checked against standards
  </Step>
</Steps>

## Updating Standards

Standards can evolve. To update:

1. Edit the relevant file in `memory-bank/standards/`
2. Commit the change with clear rationale
3. Consider an ADR for significant changes
4. Inform the team

<Warning>
  Changing standards affects all future code generation. Major changes should be documented in an ADR and reviewed by the team.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Be Specific">
    Vague standards lead to inconsistent code. "Use good naming" is useless. "Use camelCase for functions" is clear.
  </Accordion>

  <Accordion title="Document Rationale">
    Explain why, not just what. Future team members will thank you.
  </Accordion>

  <Accordion title="Keep Current">
    Update standards when the team adopts new practices. Outdated standards are ignored.
  </Accordion>

  <Accordion title="Start Simple">
    You don't need every detail on day one. Add specifics as patterns emerge.
  </Accordion>
</AccordionGroup>

## Standards Catalog

Standards are defined in `.specsmd/aidlc/templates/standards/catalog.yaml`. This catalog controls:

* Which standards exist and their importance
* Decisions within each standard
* Dependencies between standards
* Project type presets

```yaml theme={null}
standards:
  tech-stack:
    description: Core technology choices
    facilitation: templates/standards/tech-stack.guide.md
    importance: critical
    decisions:
      - id: languages
        display_name: Languages
        importance: critical
      - id: framework
        display_name: Framework
        depends_on: [languages]
      # ...

  coding-standards:
    depends_on_standards: [tech-stack]
    decisions:
      - id: formatting
      - id: testing_strategy
      # ...

project_types:
  full-stack-web:
    required_standards: [tech-stack, data-stack, coding-standards]
    recommended_standards: [system-architecture, ux-guide]
```

### Extensibility

The catalog is designed for extensibility:

<CardGroup>
  <Card title="Add New Standards" icon="plus">
    Add entries to `standards:` with facilitation guides
  </Card>

  <Card title="Custom Decisions" icon="sliders">
    Add decisions to existing standards
  </Card>

  <Card title="Project Types" icon="folder-tree">
    Define custom project type presets
  </Card>

  <Card title="Dependencies" icon="link">
    Control order via `depends_on_standards`
  </Card>
</CardGroup>

<Info>
  Each standard has a facilitation guide (`.guide.md`) that defines the questions asked during `project-init`. Customize these to match your team's decision-making process.
</Info>


# Units
Source: https://specs.md/core-concepts/units

Cohesive, self-contained work elements derived from Intents

## What is a Unit?

A **Unit** is a cohesive, self-contained work element derived from an Intent. Units are loosely coupled and can be developed independently.

<Info>
  A Unit is analogous to a **Subdomain** in DDD or an **Epic** in Scrum, but with clearer boundaries and AI-assisted decomposition.
</Info>

## Unit Characteristics

<CardGroup>
  <Card title="Cohesive" icon="object-group">
    All elements within a unit serve a single, focused purpose
  </Card>

  <Card title="Self-Contained" icon="box">
    Can be developed and tested independently
  </Card>

  <Card title="Loosely Coupled" icon="link-slash">
    Minimal dependencies on other units
  </Card>

  <Card title="Well-Bounded" icon="border-all">
    Clear interfaces with the rest of the system
  </Card>
</CardGroup>

## Example: Authentication Intent → Units

An "User Authentication System" intent might decompose into:

```
Intent: User Authentication System
├── Unit: User Registration
│   ├── Registration form
│   ├── Email validation
│   └── Account creation
├── Unit: User Login
│   ├── Login form
│   ├── Session management
│   └── Remember me
├── Unit: Password Management
│   ├── Password reset
│   ├── Password change
│   └── Password policies
└── Unit: Session Management
    ├── Token handling
    ├── Session expiry
    └── Logout
```

## Unit Structure

Each unit lives in its own directory:

```
memory-bank/intents/{intent}/units/{unit-name}/
├── unit-brief.md        # Unit definition and scope
├── stories/             # User stories for this unit
│   ├── story-001.md
│   └── story-002.md
└── bolts/               # Bolt execution records
    ├── bolt-001/
    └── bolt-002/
```

## Unit Brief

The `unit-brief.md` defines the unit:

```markdown theme={null}
# Unit: User Registration

## Purpose
Enable new users to create accounts in the system.

## Scope

### In Scope
- Email/password registration
- Email validation
- Account creation in database
- Welcome email

### Out of Scope
- Social login (separate unit)
- Profile management (separate unit)

## Dependencies
- Email Service (external)
- User Database (shared)

## Interfaces

### Inputs
- Registration form data (email, password)

### Outputs
- User account created
- Confirmation email sent

## Stories
- US-001: User Registration Form
- US-002: Email Validation
- US-003: Welcome Email
```

## Decomposing into Units

The Inception Agent helps decompose intents:

```bash theme={null}
/specsmd-inception-agent units
```

The agent will:

<Steps>
  <Step title="Analyze Requirements">
    Review user stories and NFRs from the intent
  </Step>

  <Step title="Identify Boundaries">
    Find natural groupings based on cohesion
  </Step>

  <Step title="Propose Units">
    Suggest unit structure with rationale
  </Step>

  <Step title="Define Interfaces">
    Establish how units communicate
  </Step>

  <Step title="Map Dependencies">
    Identify unit interdependencies
  </Step>
</Steps>

## Unit Dependencies

Units should be loosely coupled, but some dependencies are natural:

```mermaid actions={false} theme={null}
flowchart TB
    REG(Registration):::plan -->|creates| SESSION(Session Mgmt):::design
    LOGIN(Login):::done --> SESSION
    PWD(Password Mgmt):::warn -->|uses| SESSION
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

<Warning>
  Circular dependencies between units indicate poor decomposition. If Unit A depends on Unit B and Unit B depends on Unit A, consider merging them or extracting the shared concern.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Single Responsibility">
    Each unit should have one clear purpose. If a unit is doing too many things, split it.
  </Accordion>

  <Accordion title="Clear Boundaries">
    Define explicit interfaces. Other units should only interact through these interfaces.
  </Accordion>

  <Accordion title="Independent Development">
    You should be able to work on a unit without constantly coordinating with other units.
  </Accordion>

  <Accordion title="Testable in Isolation">
    A unit should be testable without requiring the full system.
  </Accordion>
</AccordionGroup>

## Next Steps

<Card title="Bolts" icon="arrow-right" href="/core-concepts/bolts">
  Learn how Units are implemented through Bolts
</Card>


# DeepWiki
Source: https://specs.md/deepwiki

Explore specs.md documentation with AI-powered DeepWiki

# DeepWiki

Explore the specs.md codebase and documentation using DeepWiki's AI-powered interface.

<Card title="Open DeepWiki" icon="book-open" href="https://deepwiki.com/fabriqaai/specs.md">
  Ask questions, explore the codebase, and get AI-powered answers about specs.md
</Card>

## What is DeepWiki?

DeepWiki provides an AI-powered interface to explore GitHub repositories. It allows you to:

* **Ask questions** about the codebase in natural language
* **Understand architecture** and how different parts connect
* **Find code examples** and usage patterns
* **Learn concepts** with AI-generated explanations

## Why Use DeepWiki for specs.md?

* Get instant answers about AI-DLC methodology
* Understand how agents work together
* Explore implementation details
* Find specific code patterns and examples


# FAQ
Source: https://specs.md/faq

Frequently asked questions about specs.md

## General

<AccordionGroup>
  <Accordion title="What is specs.md?">
    specs.md is an AI-native development framework with pluggable flows for every use case. It provides markdown-based agents that work with your favorite AI coding tools (Claude Code, Cursor, GitHub Copilot) to guide software development.

    We offer three flows:

    * **Simple Flow** - Spec generation only (requirements, design, tasks)
    * **FIRE Flow** - Adaptive execution with brownfield & monorepo support
    * **AI-DLC Flow** - Full methodology with comprehensive traceability

    [Choose your flow →](/architecture/choose-flow)
  </Accordion>

  <Accordion title="Which flow should I choose?">
    | Flow       | Optimized For                                   | Checkpoints     |
    | ---------- | ----------------------------------------------- | --------------- |
    | **Simple** | Quick specs, prototypes, handoff to other teams | 3 (phase gates) |
    | **FIRE**   | Adaptive execution, brownfield, monorepos       | Adaptive        |
    | **AI-DLC** | Full traceability, comprehensive documentation  | Comprehensive   |

    **Quick decision:**

    * Just need specs without execution tracking? → **Simple**
    * Want adaptive rigor that right-sizes to complexity? → **FIRE**
    * Need comprehensive documentation and fixed workflows? → **AI-DLC**

    [Detailed comparison →](/architecture/choose-flow)
  </Accordion>

  <Accordion title="What is FIRE flow?">
    FIRE (Fast Intent-Run Engineering) is an **Adaptive Spec-Driven Development** flow. It analyzes work complexity and your config preference to decide when to ask and when to burn through.

    * **Adaptive checkpoints**: Based on work complexity + your autonomy preference
    * **Brownfield-first**: Analyzes your existing structure and respects your patterns
    * **Monorepo support**: Hierarchical standards with module-specific overrides
    * **Walkthrough generation**: Every change documented automatically
    * **Design docs when needed**: Implementation plan for simple tasks, design docs for complex ones

    [Learn more about FIRE →](/fire-flow/overview)
  </Accordion>

  <Accordion title="What is AI-DLC?">
    AI-DLC is a software development methodology developed by AWS where AI drives the conversation and humans validate. Unlike traditional Agile with week-long sprints, AI-DLC operates in "Bolts" - rapid iterations measured in hours or days.

    Key principles:

    * **Reimagine, don't retrofit** - AI-DLC is built from first principles, not AI bolted onto Agile
    * **Reversed conversation** - AI proposes, humans validate (not vice versa)
    * **DDD as core** - Domain-Driven Design is integral, not optional

    [Learn more about AI-DLC →](/methodology/what-is-ai-dlc)
  </Accordion>

  <Accordion title="What AI coding tools are supported?">
    specs.md supports:

    * **Claude Code** - Full support with slash commands
    * **Cursor** - Full support with rules
    * **GitHub Copilot** - Full support with agents
    * **Google Antigravity** - Full support with agents
    * **Any AI assistant** - Works with any tool that can read markdown prompts
  </Accordion>

  <Accordion title="Is specs.md free?">
    Yes, specs.md is open source under the MIT license. You can use it freely in personal and commercial projects. You only pay for your AI API tokens.
  </Accordion>
</AccordionGroup>

## FIRE Flow

<AccordionGroup>
  <Accordion title="What are FIRE's execution modes?">
    FIRE adapts oversight to complexity with three modes:

    | Mode          | Checkpoints | Use For                                        |
    | ------------- | ----------- | ---------------------------------------------- |
    | **Autopilot** | 0           | Bug fixes, minor updates, well-defined changes |
    | **Confirm**   | 1           | Standard features, moderate complexity         |
    | **Validate**  | 2           | Security, payments, core architecture          |

    [Learn more about execution modes →](/fire-flow/execution-modes)
  </Accordion>

  <Accordion title="How does FIRE handle brownfield projects?">
    FIRE treats existing codebases as first-class citizens:

    * **Auto-detection**: Scans your codebase to infer tech stack and conventions
    * **Search before create**: Extends existing modules rather than duplicating
    * **Respect patterns**: Follows existing naming and folder structures
    * **Minimal changes**: Targeted edits, no unnecessary rewrites

    [Learn more about brownfield support →](/fire-flow/monorepo-support)
  </Accordion>

  <Accordion title="How does FIRE support monorepos?">
    FIRE has first-class monorepo support with hierarchical standards:

    * **Root standards**: Project-wide defaults
    * **Module overrides**: Per-module tech stack and conventions
    * **Constitution**: Universal policies (always inherited, never overridden)
    * **AI detection**: Automatically detects language/framework per module

    [Learn more about monorepo support →](/fire-flow/monorepo-support)
  </Accordion>

  <Accordion title="What are walkthroughs in FIRE?">
    Walkthroughs are generated documentation after each work item completes:

    * Summary of what changed
    * Files created/modified/deleted
    * Key decisions made
    * Verification steps
    * Test coverage

    They enable async review—you don't need to watch AI code in real-time.
  </Accordion>

  <Accordion title="When should I NOT use FIRE?">
    Consider AI-DLC instead if:

    * You have a large team requiring coordination
    * Your domain logic is complex and needs DDD
    * You're in a regulated environment requiring extensive documentation
    * Multiple stakeholders need to review and approve changes

    [Flow comparison →](/architecture/choose-flow)
  </Accordion>
</AccordionGroup>

## Why AI-DLC? (The Agentic Age)

<AccordionGroup>
  <Accordion title="Why do we need a new methodology? What's wrong with Agile?">
    Traditional methods were built for longer iteration durations (months and weeks), leading to rituals like daily standups and retrospectives. With AI, iteration cycles are measured in hours or days.

    Retrofitting AI into Agile limits its potential and reinforces outdated inefficiencies. We need automobiles, not faster horse chariots.

    [Read: The AI-Native SDLC: Reimagined →](/methodology/sdlc-reimagined)
  </Accordion>

  <Accordion title="Why are sprints becoming obsolete?">
    * **Two weeks is no longer fast** - AI produces working prototypes in hours
    * **Story points are meaningless** - AI execution time bears no relation to human effort
    * **Sprint boundaries create artificial delays** - Completed work waits for ceremonies
    * **Velocity fluctuates wildly** - Based on AI tool usage, not team capability

    AI-DLC replaces sprints with "Bolts" - hours or days, not weeks.
  </Accordion>

  <Accordion title="What is V-Bounce?">
    V-Bounce is a model from the [Crowdbotics research paper](https://arxiv.org/abs/2408.03416) that introduced a key insight: humans shift from primary implementers to validators and verifiers.

    AI handles planning, coding, and testing. Humans focus on requirements, architecture, and continuous validation.
  </Accordion>

  <Accordion title="What does 'AI drives, human validates' mean?">
    In traditional development, humans prompt AI to complete tasks. In AI-DLC, the conversation is reversed:

    **Traditional**: Human asks → AI responds

    **AI-DLC**: AI proposes breakdown, trade-offs, designs → Human validates, approves, redirects

    Think of it like Google Maps: you set the destination, AI provides step-by-step directions, you maintain oversight.
  </Accordion>

  <Accordion title="What are Mob Elaboration and Mob Construction?">
    These are AI-DLC's collaborative rituals:

    * **Mob Elaboration** (Inception): Product managers, developers, QA collaborate with AI to refine requirements into user stories. What took months now takes hours.

    * **Mob Construction** (Construction): Teams work in parallel after domain modeling, with AI generating component models while team provides real-time clarification.

    Both happen in a single room with shared screen for deep alignment.
  </Accordion>
</AccordionGroup>

## Comparisons

<AccordionGroup>
  <Accordion title="How does specs.md compare to GitHub Spec Kit?">
    **Spec Kit** is a toolkit with agent prompts (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) for 15+ AI assistants.

    **specs.md** is a full methodology with phase-based agents, Mob rituals, and DDD integration.

    Choose Spec Kit for a 4-phase workflow with minimal learning curve. Choose specs.md for complex systems needing formal methodology structure.

    [specs.md (Simple Flow)](/simple-flow/overview) provides Kiro-style Requirements → Design → Tasks workflow.

    [Full comparison →](/compare/vs-speckit)
  </Accordion>

  <Accordion title="How does specs.md compare to BMAD-Method?">
    Both target complex systems:

    * **BMAD**: 19+ role-based agents (Analyst, PM, Architect, Dev, QA...)
    * **specs.md**: 3 phase-based agents (Master, Inception, Construction, Operations)

    Choose BMAD for maximum agent customization. Choose specs.md for formal AWS methodology with simpler agent model.

    [Full comparison →](/compare/vs-bmad)
  </Accordion>

  <Accordion title="How does specs.md compare to Kiro (AWS)?">
    **Kiro** is a full IDE with built-in spec-driven development and agent hooks.

    **specs.md** is IDE-agnostic—works with any editor and AI model.

    | Aspect   | specs.md          | Kiro               |
    | -------- | ----------------- | ------------------ |
    | IDE      | Any               | Kiro only          |
    | AI Model | Any               | Claude Sonnet only |
    | Pricing  | Free + API tokens | \$19-39/month      |

    [specs.md (Simple Flow)](/simple-flow/overview) provides a Kiro-style workflow that works with any IDE.

    [Full comparison →](/compare/vs-kiro)
  </Accordion>

  <Accordion title="How does specs.md compare to OpenSpec?">
    **OpenSpec** is brownfield-first, focused on change management with excellent token efficiency.

    **specs.md** provides full lifecycle support (Inception → Operations) for both greenfield and brownfield.

    Choose OpenSpec for high-volume small changes. Choose specs.md for full lifecycle complex systems.

    [Full comparison →](/compare/vs-openspec)
  </Accordion>

  <Accordion title="Do I need other spec-driven tools if I use specs.md?">
    No. specs.md is a complete methodology that includes everything you need:

    * Formal phases (Inception → Construction → Operations)
    * Defined rituals (Mob Elaboration, Mob Construction)
    * Design integration (DDD as core)
    * Memory Bank for persistent context
    * Phase-based agents

    Other tools focus on specifications only. AI-DLC is a full methodology.
  </Accordion>
</AccordionGroup>

## Installation

<AccordionGroup>
  <Accordion title="How do I install specs.md?">
    ```bash theme={null}
    npx specsmd@latest install
    ```

    The installer automatically detects your AI coding tools and sets up the appropriate agents.

    [Full installation guide →](/getting-started/installation)
  </Accordion>

  <Accordion title="Should I install globally with npm?">
    No. Always use `npx specsmd@latest install` to ensure you get the latest version. Global installation may result in using an outdated version.
  </Accordion>

  <Accordion title="What gets installed?">
    specs.md creates a `.specsmd/` directory with:

    * Agent definitions
    * Skills and capabilities
    * Templates for artifacts
    * Memory bank schema

    It also creates tool-specific files (e.g., `.claude/commands/` for Claude Code).
  </Accordion>
</AccordionGroup>

## Usage

<AccordionGroup>
  <Accordion title="Agents don't seem to remember previous context?">
    Each agent invocation starts fresh. Agents read context from the Memory Bank at startup.

    **Solution**: Ensure artifacts are saved after each step. The Memory Bank is how context persists between sessions.
  </Accordion>

  <Accordion title="How do I reset project state?">
    To reset all artifacts, clear the `memory-bank/` directory:

    ```bash theme={null}
    rm -rf memory-bank/
    ```

    To remove specs.md entirely:

    ```bash theme={null}
    rm -rf .specsmd/
    rm -rf .claude/commands/specsmd-*  # For Claude Code
    ```
  </Accordion>

  <Accordion title="Can I use specs.md with existing Agile workflows?">
    AI-DLC is designed as a reimagination of development methodology, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.

    You can use specs.md alongside existing Agile processes, treating Intents as Epics and Bolts as focused work items within sprints.
  </Accordion>

  <Accordion title="Can I use specs.md on existing codebases (brownfield)?">
    Yes. AI-DLC supports brownfield development through "model elevation" - AI first converts existing code to semantic models (domain components, responsibilities, relationships) before making changes.

    This ensures AI understands the existing system before proposing modifications.
  </Accordion>
</AccordionGroup>

## Methodology

<AccordionGroup>
  <Accordion title="What's the difference between Intents, Units, and Bolts?">
    * **Intent**: High-level goal ("Build user authentication")
    * **Unit**: Cohesive work element derived from Intent ("User Registration")
    * **Bolt**: Smallest iteration, hours to days ("Registration Domain Model")

    [Learn more about core concepts →](/core-concepts/intents)
  </Accordion>

  <Accordion title="What are the three phases?">
    1. **Inception**: Mob Elaboration ritual - capture intents, decompose into units and stories
    2. **Construction**: Mob Construction ritual - domain modeling, code generation, testing
    3. **Operations**: Deployment, monitoring, maintenance

    [Learn more about phases →](/methodology/three-phases)
  </Accordion>

  <Accordion title="What are human checkpoints?">
    Human checkpoints are validation points within a bolt. You must approve each stage before proceeding to the next:

    1. Domain Model → **CHECKPOINT** → Technical Design → **CHECKPOINT** → etc.

    This catches errors early before they cascade downstream.
  </Accordion>

  <Accordion title="What bolt types are available?">
    | Type                    | Use Case                                |
    | ----------------------- | --------------------------------------- |
    | **DDD Construction**    | Complex business logic, domain modeling |
    | **Simple Construction** | UI, integrations, utilities             |
  </Accordion>

  <Accordion title="What is the Memory Bank?">
    The Memory Bank is a file-based storage system for all project artifacts. It maintains context across agent sessions and provides traceability between requirements, designs, code, and tests.

    [Learn more about Memory Bank →](/core-concepts/memory-bank)
  </Accordion>

  <Accordion title="Why is DDD (Domain-Driven Design) required?">
    Unlike Agile frameworks that leave design techniques optional, AI-DLC integrates DDD as its core. AI applies domain-driven design principles during decomposition:

    * Bounded contexts
    * Aggregates and entities
    * Domain events
    * Repositories and factories

    This ensures consistent, high-quality domain models regardless of which team member is working.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent commands not recognized">
    Ensure specs.md is installed correctly:

    ```bash theme={null}
    ls .specsmd/aidlc/agents/
    ```

    If the directory is empty or missing, reinstall:

    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Accordion>

  <Accordion title="Memory Bank artifacts missing">
    Check if the memory-bank directory exists:

    ```bash theme={null}
    ls memory-bank/
    ```

    If missing, run project initialization:

    ```bash theme={null}
    /specsmd-master-agent
    > project-init
    ```
  </Accordion>

  <Accordion title="Standards not being followed in generated code">
    Ensure standards are defined in `memory-bank/standards/`:

    * `tech-stack.md`
    * `coding-standards.md`
    * `architecture.md`

    If missing or incomplete, use the Master Agent to define them:

    ```bash theme={null}
    /specsmd-master-agent
    > project-init
    ```
  </Accordion>

  <Accordion title="AI not following the spec properly">
    This is a known limitation of all spec-driven tools. Even with comprehensive specs, AI agents don't always follow every instruction.

    **Solutions**:

    * Use checkpoints to catch errors early
    * Break work into smaller, clearer units
    * Ensure Memory Bank has complete context
    * Validate each step before proceeding
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup>
  <Card title="AI-DLC Whitepaper (AWS)" icon="file-pdf" href="https://github.com/fabriqaai/specsmd/blob/main/resources/aidlc.pdf">
    Original AWS whitepaper defining AI-DLC methodology
  </Card>

  <Card title="V-Bounce Paper (arXiv)" icon="book" href="https://arxiv.org/abs/2408.03416">
    AI-Native Software Development Lifecycle research
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/fabriqaai/specsmd">
    Source code, issues, and contributions
  </Card>

  <Card title="Compare Tools" icon="scale-balanced" href="/compare/overview">
    See how specs.md compares to alternatives
  </Card>
</CardGroup>


# Provide Feedback
Source: https://specs.md/feedback

Help us improve specs.md with your valuable feedback

## Your Feedback Matters

specs.md is an open-source project built for the community, and **your feedback is essential** to making it better. Whether you've encountered a bug, have a feature idea, or simply want to share your experience, we want to hear from you.

<Info>
  As an early-stage project, your input directly shapes the direction of specs.md. Every piece of feedback helps us understand real-world use cases and prioritize what matters most.
</Info>

## How You Can Help

<CardGroup>
  <Card title="Report Issues" icon="bug" href="https://github.com/fabriqaai/specsmd/issues/new?template=bug_report.md">
    Found a bug? Let us know so we can fix it quickly.
  </Card>

  <Card title="Request Features" icon="lightbulb" href="https://github.com/fabriqaai/specsmd/issues/new?template=feature_request.md">
    Have an idea that would make specs.md better? We'd love to hear it.
  </Card>

  <Card title="Ask Questions" icon="circle-question" href="https://github.com/fabriqaai/specsmd/issues/new">
    Confused about something? Open an issue and we'll help clarify.
  </Card>

  <Card title="Share Experience" icon="comment" href="https://github.com/fabriqaai/specsmd/issues/new">
    Tell us how you're using specs.md and what's working (or not).
  </Card>
</CardGroup>

## What Makes Great Feedback

When sharing feedback, consider including:

* **Context**: What were you trying to accomplish?
* **Steps**: What did you do? (Be specific)
* **Expected vs Actual**: What did you expect to happen? What actually happened?
* **Environment**: Which AI tool are you using? (Claude Code, Cursor, Copilot)
* **Ideas**: Any thoughts on how it could be improved?

## Submit Feedback

<Card title="Open a GitHub Issue" icon="github" href="https://github.com/fabriqaai/specsmd/issues">
  Visit our GitHub Issues page to submit feedback, report bugs, or request features. We review every submission and respond as quickly as possible.
</Card>

***

<Note>
  We genuinely appreciate every piece of feedback. It takes time to write up issues and suggestions, and we don't take that for granted. Thank you for helping make specs.md better for everyone.
</Note>


# FIRE Agents
Source: https://specs.md/fire-flow/agents

Orchestrator, Planner, and Builder - the three agents powering FIRE

## Three-Agent Architecture

FIRE uses three specialized agents, each with a focused responsibility:

```mermaid actions={false} theme={null}
flowchart TD
    U(User):::build --> O(Orchestrator):::design
    O --> P(Planner):::plan
    O --> B(Builder):::build
    P --> S[(State)]:::warn
    B --> S
    B --> C[(Codebase)]:::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Agent            | Role                                     | Invocation              |
| ---------------- | ---------------------------------------- | ----------------------- |
| **Orchestrator** | Entry point, routing, session management | `/specsmd-fire`         |
| **Planner**      | Intent capture, work item decomposition  | `/specsmd-fire-planner` |
| **Builder**      | Run execution, walkthrough generation    | `/specsmd-fire-builder` |

## Orchestrator Agent

The **Orchestrator** is the entry point for all FIRE interactions.

### Responsibilities

* Read `state.yaml` to understand current phase
* Route to appropriate agent based on context
* Handle session resume and continuity
* Suggest next actions based on state

### When Orchestrator Routes

```mermaid actions={false} theme={null}
flowchart TD
    O(Orchestrator):::design --> Q{{"What's needed?"}}:::check
    Q -->|No intents| P1(Planner: Capture):::plan
    Q -->|Has pending| B1(Builder: Execute):::build
    Q -->|Complete| P2(Planner: Next?):::plan
    Q -->|Explicit| R(Route):::warn
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

### Usage

```
/specsmd-fire

---
Reading project state...

Current State:
- Intent: User Authentication (in_progress)
- Work Items: 1/3 complete
- Next: login-endpoint (mode: Confirm)

Routing to Builder for next work item execution.
```

### Session Resume

Orchestrator maintains context across sessions:

```
/specsmd-fire

---
Resuming previous session...

Last session ended with:
- Run 2 in progress: login-endpoint
- Status: Awaiting confirmation

Would you like to:
[c] Continue with login-endpoint
[s] Skip to next work item
[p] Return to Planner
```

## Planner Agent

The **Planner** handles all planning activities.

### Responsibilities

* Capture intents through guided conversation
* Decompose intents into work items
* Assign complexity and execution modes
* Generate design documents (Validate mode)
* Initialize and update project standards

### Skills

| Skill                 | Purpose                                   |
| --------------------- | ----------------------------------------- |
| `intent-capture`      | Guide user through intent definition      |
| `work-item-decompose` | Break intents into executable work items  |
| `design-doc-generate` | Create design documents for Validate mode |
| `standards-init`      | Initialize or update project standards    |
| `workspace-detect`    | Analyze project structure (shared)        |

### Intent Capture Flow

```mermaid actions={false} theme={null}
sequenceDiagram
    participant U as User
    participant P as Planner

    U->>P: /specsmd-fire-planner
    P->>U: What do you want to build?
    U->>P: User authentication system
    P->>U: Clarifying questions...
    U->>P: Answers
    P->>P: Create intent document
    P->>P: Decompose into work items
    P->>U: Present work items
    U->>P: Approve/modify
    P->>P: Save to state
```

### Example Session

```
/specsmd-fire-planner

---
What would you like to build?

> User authentication with email/password login

Got it. A few questions:

1. Do you need password reset functionality?
> Yes

2. Session management (JWT, sessions, or both)?
> JWT

3. Any social login requirements?
> Not for MVP

---

Intent captured: User Authentication System

Work Items:
1. user-schema (Low, Autopilot)
   - Create users table with auth fields

2. login-endpoint (Medium, Confirm)
   - POST /auth/login with JWT generation

3. password-reset (Medium, Confirm)
   - Reset flow with email tokens

4. session-middleware (High, Validate)
   - JWT validation middleware

[Approve work items? y/n]
```

### Design Document Generation

For Validate mode work items, Planner generates design docs:

```
Generating design document for: session-middleware

---
# Session Middleware Design

## Overview
JWT-based session validation middleware for protected routes.

## Architecture
- Middleware extracts JWT from Authorization header
- Validates signature and expiration
- Attaches user context to request
- Handles token refresh for near-expiry tokens

## Security Considerations
- Tokens signed with RS256
- 15-minute access token expiry
- Refresh tokens stored in httpOnly cookies

## Error Handling
- 401 for missing/invalid tokens
- 403 for expired tokens (with refresh hint)

---
[Save design document? y/n]
```

## Builder Agent

The **Builder** executes work items and generates walkthroughs.

### Responsibilities

* Select next work item based on dependencies
* Execute runs with appropriate mode (Autopilot/Confirm/Validate)
* Track file changes during execution
* Generate walkthroughs after completion
* Update state via scripts

### Skills

| Skill                  | Purpose                                    |
| ---------------------- | ------------------------------------------ |
| `run-execute`          | Execute work items with mode-specific flow |
| `walkthrough-generate` | Document changes after completion          |
| `state-management`     | Update state.yaml via scripts (shared)     |

### Execution Flow

```mermaid actions={false} theme={null}
stateDiagram-v2
    [*] --> SelectWorkItem
    SelectWorkItem --> LoadContext
    LoadContext --> CheckMode

    CheckMode --> Execute: Autopilot
    CheckMode --> Plan: Confirm/Validate

    Plan --> Checkpoint
    Checkpoint --> Execute: Approved
    Checkpoint --> Plan: Revise

    Execute --> TrackChanges
    TrackChanges --> GenerateWalkthrough
    GenerateWalkthrough --> UpdateState
    UpdateState --> [*]
```

### Brownfield Rules

Builder follows strict brownfield rules:

<CardGroup>
  <Card title="Search Before Create" icon="magnifying-glass">
    Check for existing similar code. Extend rather than duplicate.
  </Card>

  <Card title="Respect Patterns" icon="ruler-combined">
    Follow existing naming, structure, and conventions.
  </Card>

  <Card title="Minimal Changes" icon="scalpel">
    Targeted edits only. Don't rewrite files unnecessarily.
  </Card>

  <Card title="Preserve Tests" icon="vial">
    Never delete tests without explicit approval.
  </Card>
</CardGroup>

### Example Session

```
/specsmd-fire-builder

---
Selecting next work item...

Work Item: login-endpoint
Mode: Confirm
Dependencies: ✓ user-schema (complete)

---
## Plan

1. Create POST /auth/login endpoint
2. Validate email/password against users table
3. Generate JWT on successful auth
4. Return token with user profile
5. Add rate limiting (5 attempts/minute)
6. Add unit tests

Files to create/modify:
- src/routes/auth.ts (create)
- src/middleware/rateLimit.ts (create)
- tests/routes/auth.test.ts (create)
- src/routes/index.ts (modify)

[Confirm to proceed? y/n]
> y

Executing...

✓ Created src/routes/auth.ts
✓ Created src/middleware/rateLimit.ts
✓ Created tests/routes/auth.test.ts
✓ Modified src/routes/index.ts

Walkthrough generated: walkthroughs/run-fabriqa-2026-002-login-endpoint.md

---
Work item complete. Next: password-reset
```

## Agent Interaction Patterns

### Direct Invocation

Call agents directly when you know what you need:

```
/specsmd-fire-planner     # Capture new intent
/specsmd-fire-builder     # Execute work items
```

### Orchestrator Routing

Let Orchestrator decide based on state:

```
/specsmd-fire   # Routes to appropriate agent
```

### Mid-Session Switching

You can switch agents mid-session:

```
/specsmd-fire-builder

---
Executing login-endpoint...

> Actually, I want to add another work item first

Switching to Planner...

/specsmd-fire-planner
```

## Agent Communication

Agents communicate through **state.yaml**, not directly:

```mermaid actions={false} theme={null}
flowchart LR
    P(Planner):::plan -->|writes| S[(state.yaml)]:::warn
    B(Builder):::build -->|reads| S
    B -->|writes| S
    O(Orchestrator):::design -->|reads| S
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

### Why File-Based State?

* **Deterministic**: Scripts ensure consistent updates
* **Auditable**: Git tracks all state changes
* **Resumable**: State persists across sessions
* **Debuggable**: Human-readable YAML

## Command Reference

| Command                 | Agent        | Purpose                  |
| ----------------------- | ------------ | ------------------------ |
| `/specsmd-fire`         | Orchestrator | Entry point, routing     |
| `/specsmd-fire-planner` | Planner      | Intent capture, planning |
| `/specsmd-fire-builder` | Builder      | Execution, walkthroughs  |

<Info>
  For most workflows, start with `/specsmd-fire` and let it route you.
</Info>


# Execution Modes
Source: https://specs.md/fire-flow/execution-modes

Adaptive checkpoints (Autopilot, Confirm, Validate) and run scope (Single, Batch, Wide)

## Adaptive Checkpoints

FIRE's breakthrough is **adaptive checkpoints** that scale with complexity. Instead of a fixed number of gates, FIRE adjusts oversight based on two inputs:

1. **Work Complexity**: Low, Medium, or High
2. **Your Autonomy Config**: Set during project initialization

<Frame>
  <img alt="FIRE Autonomy Configuration" />
</Frame>

These combine to determine the execution mode:

```mermaid actions={false} theme={null}
flowchart LR
    WC(Work Complexity):::build --> E{{"Adaptive Engine"}}:::design
    AC(Autonomy Config):::build --> E
    E --> AP(Autopilot):::done
    E --> CO(Confirm):::plan
    E --> VA(Validate):::check
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

### Mode Comparison

<CardGroup>
  <Card title="Autopilot" icon="bolt">
    ```mermaid actions={false} theme={null}
    flowchart TB
        A1(Plan):::build --> A2(Execute):::build --> A3(Walkthrough):::build --> A4(Done):::done
        classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
        classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    ```

    **0 checkpoints** - AI executes directly
  </Card>

  <Card title="Confirm" icon="circle-check">
    ```mermaid actions={false} theme={null}
    flowchart TB
        C1(Plan):::plan --> C2{{"✋ Confirm"}}:::check --> C3(Execute):::build --> C4(Done):::done
        classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
        classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
        classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
        classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    ```

    **1 checkpoint** - Human confirms plan
  </Card>

  <Card title="Validate" icon="shield-check">
    ```mermaid actions={false} theme={null}
    flowchart TB
        V1(Design):::design --> V2{{"✋ Review"}}:::check --> V3(Plan):::plan --> V4{{"✋ Approve"}}:::check --> V5(Execute):::build --> V6(Done):::done
        classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
        classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
        classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
        classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
        classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    ```

    **2 checkpoints** - Design + plan review
  </Card>
</CardGroup>

## Autopilot Mode (0 Checkpoints)

**AI executes directly, generates walkthrough for review.**

### When to Use

* Bug fixes with clear reproduction steps
* Minor updates (text changes, config tweaks)
* Well-defined CRUD operations
* Adding tests for existing code
* Documentation updates

### Flow

**Start → AI Plans → AI Executes → Walkthrough**

No human checkpoints. AI loads context, executes changes directly, and generates a walkthrough for post-review.

### Example

```
Work Item: Fix typo in error message
Mode: Autopilot

Builder executing...
✓ Updated src/errors.ts line 42
✓ Walkthrough generated

---
# Walkthrough: fix-error-typo

## Summary
Fixed typo "recieved" → "received" in authentication error message.

## Files Changed
- src/errors.ts (1 line)

## Verification
Error message now displays correctly on failed login.
```

### Best Practices

<Info>
  Use Autopilot for **reversible** changes where the cost of a mistake is low.
</Info>

* Keep Autopilot tasks small and focused
* Always review walkthroughs after completion
* Upgrade to Confirm if you're unsure

## Confirm Mode (1 Checkpoint)

**AI presents plan, human confirms, AI executes.**

### When to Use

* Standard feature implementation
* API endpoint creation
* Component development
* Database queries (non-schema)
* Integration with external services

### Flow

**Start → AI Plans → ✋ Human Confirms → AI Executes → Walkthrough**

One checkpoint: you review the AI's plan before execution. Reject to provide feedback and get a revised plan.

### Example

```
Work Item: Add user profile endpoint
Mode: Confirm

---
## Plan

1. Create GET /api/users/:id endpoint
2. Add UserProfile response schema
3. Implement authorization check (user can only view own profile)
4. Add unit tests for endpoint
5. Update API documentation

**Estimated changes**: 4 files, ~80 lines

[Confirm to proceed? y/n]
```

### Providing Feedback

If the plan isn't right, reject and provide feedback:

```
[Confirm? n]

Feedback: Also include the user's recent activity in the response
```

The Builder will revise and present an updated plan.

## Validate Mode (2 Checkpoints)

**AI generates design doc, human reviews design, human approves implementation.**

### When to Use

* Security-sensitive features (auth, permissions)
* Payment and billing logic
* Core architecture changes
* Database schema modifications
* External API integrations with side effects
* Features affecting multiple modules

### Flow

**Start → AI Designs → ✋ Human Reviews → AI Plans → ✋ Human Approves → AI Executes → Walkthrough**

Two checkpoints: first review the design approach, then approve the implementation plan. This separates "is this the right approach?" from "is the plan complete?"

### Example

```
Work Item: Implement password reset flow
Mode: Validate

---
## Design Document

### Overview
Secure password reset using time-limited tokens sent via email.

### Security Considerations
- Tokens expire after 1 hour
- Tokens are single-use
- Rate limited to 3 requests per hour per email
- Token hashed in database (not stored plaintext)

### Architecture
```

User Request → Rate Limiter → Token Generator → Email Service
↓
Token Verification ← User Click ← Email
↓
Password Update → Session Invalidation

```

### Database Changes
- New table: password_reset_tokens
- Columns: id, user_id, token_hash, expires_at, used_at

[Design review complete? y/n]

---

## Implementation Plan

1. Create password_reset_tokens migration
2. Add PasswordResetService with generate/verify methods
3. Create POST /auth/forgot-password endpoint
4. Create POST /auth/reset-password endpoint
5. Add email template for reset link
6. Implement rate limiting middleware
7. Add comprehensive tests

**Estimated changes**: 8 files, ~200 lines

[Approve implementation? y/n]
```

### Two-Stage Review

<Info>
  Validate mode separates **design review** (is this the right approach?) from **implementation approval** (is this plan complete?).
</Info>

This prevents:

* Starting implementation on a flawed design
* Missing edge cases caught during design review
* Scope creep during implementation

## Choosing the Right Mode

### Decision Matrix

| Factor                | Autopilot | Confirm  | Validate  |
| --------------------- | --------- | -------- | --------- |
| **Complexity**        | Low       | Medium   | High      |
| **Reversibility**     | Easy      | Moderate | Difficult |
| **Security Impact**   | None      | Low      | High      |
| **User Data**         | No        | Read     | Write     |
| **External Services** | No        | Read     | Write     |
| **Schema Changes**    | No        | No       | Yes       |

### Quick Guide

<AccordionGroup>
  <Accordion title="Autopilot - Trust the AI">
    * Typo fixes
    * Log statement additions
    * Test additions for existing code
    * Config value changes
    * Comment updates
  </Accordion>

  <Accordion title="Confirm - Verify the Plan">
    * New API endpoints (GET, non-sensitive)
    * UI components
    * Utility functions
    * Query optimizations
    * Refactoring (behavior-preserving)
  </Accordion>

  <Accordion title="Validate - Full Review">
    * Authentication/authorization
    * Payment processing
    * Data migrations
    * Third-party integrations (with side effects)
    * Schema changes
    * Security-sensitive features
  </Accordion>
</AccordionGroup>

## Run Scope

Run scope determines how many work items execute in a single run. This is separate from execution mode—you can batch multiple Autopilot items together, or run Validate items one at a time.

### Scope Options

<CardGroup>
  <Card title="Single" icon="circle-1">
    **One work item per run**

    Most controlled. Each item gets its own run with dedicated walkthrough.

    Best for: Learning the codebase, high-stakes changes, detailed review needs
  </Card>

  <Card title="Batch" icon="layer-group">
    **Group by execution mode**

    Respects dependencies. Groups Autopilot items together, Confirm items together, etc.

    Best for: Balanced workflow, mixed complexity work
  </Card>

  <Card title="Wide" icon="arrows-maximize">
    **Maximum items per run**

    Minimal interruption. All compatible items execute together.

    Best for: Experienced users, rapid iteration, well-understood changes
  </Card>
</CardGroup>

### Scope Comparison

| Scope      | Items per Run  | Grouping Strategy                    | Interruptions  |
| ---------- | -------------- | ------------------------------------ | -------------- |
| **Single** | 1              | Each item isolated                   | Per item       |
| **Batch**  | By mode        | Autopilot, Confirm, Validate grouped | Per mode group |
| **Wide**   | All compatible | Maximum batching                     | Minimal        |

### How FIRE Learns Your Preference

FIRE tracks your scope choices and suggests your preferred pattern:

```yaml theme={null}
# In state.yaml
workspace:
  run_scope_preference: batch  # Learned from history
  run_scope_history:
    - choice: batch
      items_count: 3
      timestamp: 2024-01-15T10:30:00Z
    - choice: single
      items_count: 1
      timestamp: 2024-01-14T15:45:00Z
```

You can always override the suggestion for any individual run.


# Monorepo Support
Source: https://specs.md/fire-flow/monorepo-support

Hierarchical standards and brownfield detection for multi-module projects

## First-Class Monorepo Support

FIRE is designed from the ground up for real-world projects, including complex monorepo architectures with multiple tech stacks.

<Frame>
  <img alt="FIRE Monorepo Detection" />
</Frame>

```mermaid actions={false} theme={null}
flowchart TD
    subgraph "Project Root"
        R(.specs-fire/standards/):::build
        C(constitution.md):::design
        TS(tech-stack.md):::plan
    end

    subgraph "packages/api"
        A(.specs-fire/standards/):::build
        ATS(tech-stack.md - Go):::done
    end

    subgraph "packages/web"
        W(.specs-fire/standards/):::build
        WTS(tech-stack.md - React):::done
    end

    R --> C
    R --> TS
    C -.->|inherited| A
    C -.->|inherited| W
    TS -.->|overridden| ATS
    TS -.->|overridden| WTS
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

## Hierarchical Standards

### How It Works

Standards follow a **hierarchical inheritance** model:

1. **Root standards** define project-wide defaults
2. **Module standards** override specific files when needed
3. **Constitution** is special—always inherited, never overridden

### Project Structure

```
project/
├── .specs-fire/
│   ├── state.yaml                 # Single source of truth
│   └── standards/
│       ├── constitution.md        # Universal policies (ALWAYS inherited)
│       ├── tech-stack.md          # Default: Node.js, TypeScript
│       ├── coding-standards.md    # Default coding conventions
│       └── testing-standards.md   # Default test patterns
│
├── packages/api/
│   └── .specs-fire/
│       └── standards/
│           └── tech-stack.md      # Override: Go, Echo, golangci-lint
│
├── packages/web/
│   └── .specs-fire/
│       └── standards/
│           └── tech-stack.md      # Override: React, Vite, Tailwind
│
└── services/ml/
    └── .specs-fire/
        └── standards/
            └── tech-stack.md      # Override: Python, FastAPI, ruff
```

### Resolution Rules

<Steps>
  <Step title="Check Module">
    Does the target module have this standard file?
  </Step>

  <Step title="If Yes: Use Module">
    Use the module's version (override)
  </Step>

  <Step title="If No: Inherit">
    Walk up to parent, use ancestor's version
  </Step>

  <Step title="Exception: Constitution">
    Constitution is ALWAYS inherited from root, never overridden
  </Step>
</Steps>

## The Constitution

The **constitution** contains universal policies that apply everywhere:

```markdown theme={null}
# Project Constitution

## Git Workflow
- All changes via pull request
- Require 1 approval before merge
- Squash merge to main

## Security
- No secrets in code
- Environment variables for configuration
- Dependency scanning enabled

## CI/CD
- All PRs must pass CI
- Deploy to staging on merge to main
- Manual promotion to production

## Quality
- All new code must have tests
- Maintain >80% coverage on critical paths
```

<Info>
  Constitution is **always inherited**. If a module tries to have its own constitution.md, it's ignored.
</Info>

### Why Constitution is Special

* Ensures consistent policies across all modules
* Prevents "rogue" modules with different rules
* Simplifies onboarding—one place for universal rules
* AI always knows where to find project-wide policies

## Tech Stack Detection

FIRE doesn't hardcode tech stacks—it **detects** them:

### Quick Scan (2-5 minutes)

Pattern-based detection:

* Package files: `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`
* Lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Config files: `tsconfig.json`, `.eslintrc`, `pyproject.toml`
* Framework markers: `next.config.js`, `vite.config.ts`, `main.go`

### Deep Scan (10-30 minutes)

Code analysis:

* Import patterns and dependencies
* Folder structure conventions
* Test framework usage
* Build tool configuration
* Integration patterns (APIs, databases)

### Generated Tech Stack

After scanning, FIRE generates a `tech-stack.md`:

```markdown theme={null}
# Tech Stack

## Language
- TypeScript 5.x
- Node.js 20 LTS

## Framework
- Express.js for API
- React 18 for frontend

## Database
- PostgreSQL 15
- Prisma ORM

## Testing
- Vitest for unit tests
- Playwright for E2E

## Tooling
- ESLint + Prettier
- pnpm workspaces
- Turborepo for builds
```

## Brownfield Support

FIRE treats existing codebases as **first-class citizens**.

### Brownfield Rules

<CardGroup>
  <Card title="Search Before Create" icon="magnifying-glass">
    Always check if similar code exists before creating new modules.
  </Card>

  <Card title="Respect Patterns" icon="ruler-combined">
    Follow existing naming, folder structures, and conventions.
  </Card>

  <Card title="Minimal Changes" icon="scalpel">
    Make targeted edits. Don't rewrite files unnecessarily.
  </Card>

  <Card title="Preserve Tests" icon="vial">
    Never delete existing tests without explicit approval.
  </Card>
</CardGroup>

### Standards Inference

For brownfield projects, FIRE infers standards from existing code:

```mermaid actions={false} theme={null}
sequenceDiagram
    participant U as User
    participant P as Planner
    participant C as Codebase

    U->>P: Initialize FIRE
    P->>C: Analyze codebase
    C-->>P: Files, patterns, conventions
    P->>P: Infer tech stack
    P->>P: Infer coding standards
    P->>P: Infer folder structure
    P->>U: Present inferred standards
    U->>P: Approve/modify
    P->>P: Save standards
```

### Inferred vs Prescribed

| Aspect               | Greenfield                    | Brownfield                  |
| -------------------- | ----------------------------- | --------------------------- |
| **Tech Stack**       | AI suggests or user specifies | Detected from code          |
| **Coding Standards** | AI suggests or user specifies | Inferred from patterns      |
| **Folder Structure** | AI suggests or user specifies | Matches existing layout     |
| **Testing**          | AI suggests                   | Follows existing test setup |

## Monorepo Detection

FIRE automatically detects monorepo structures:

### Detection Signals

| Signal                  | Indicator                          |
| ----------------------- | ---------------------------------- |
| **pnpm**                | `pnpm-workspace.yaml`              |
| **Yarn**                | `package.json` with `workspaces`   |
| **Lerna**               | `lerna.json`                       |
| **Nx**                  | `nx.json`                          |
| **Turborepo**           | `turbo.json`                       |
| **Directory Structure** | `packages/` or `apps/` directories |

### Workspace Analysis

After detection, FIRE maps the workspace:

```yaml theme={null}
workspace:
  type: brownfield
  structure: monorepo
  parts:
    - name: packages/api
      tech: go
      framework: echo
    - name: packages/web
      tech: typescript
      framework: react
    - name: services/ml
      tech: python
      framework: fastapi
  integrations:
    - type: database
      provider: postgresql
    - type: cache
      provider: redis
  key_files:
    - packages/api/main.go
    - packages/web/src/App.tsx
    - services/ml/main.py
```

## Working with Modules

### Targeting a Module

When creating work items, specify the target module:

```yaml theme={null}
work_item:
  id: add-user-endpoint
  module: packages/api  # Target specific module
  title: Add user CRUD endpoint
```

FIRE will:

1. Load module-specific standards
2. Respect module's tech stack
3. Follow module's conventions

### Cross-Module Work

For work spanning multiple modules:

```yaml theme={null}
work_item:
  id: user-feature
  modules:
    - packages/api      # Backend changes
    - packages/web      # Frontend changes
  title: Add user management feature
  complexity: high      # Cross-module = higher complexity
  mode: validate        # Recommend Validate mode
```

<Warning>
  Cross-module work items are **automatically** set to higher complexity and typically use Validate mode.
</Warning>

## Best Practices

### When to Override Standards

<AccordionGroup>
  <Accordion title="Override tech-stack.md">
    * Module uses different language
    * Module has specific framework requirements
    * Module has unique tooling needs
  </Accordion>

  <Accordion title="Override coding-standards.md">
    * Module follows different conventions (e.g., Go vs TypeScript)
    * Module has special formatting rules
    * Module has unique linting configuration
  </Accordion>

  <Accordion title="Never Override constitution.md">
    * Constitution is always inherited
    * Project-wide policies must be consistent
    * Modify root constitution for changes
  </Accordion>
</AccordionGroup>

### Keeping Standards in Sync

* Review root standards periodically
* Update constitution when policies change
* Keep module overrides minimal
* Document why overrides exist

### Module-Specific Conventions

Add context to module standards:

```markdown theme={null}
# Tech Stack - packages/api

## Why Go?
Selected for API module due to:
- High performance requirements
- Strong typing for data validation
- Excellent concurrency support

## Migration from Node
Originally Node.js, migrated in Q3 2024 for performance.
Some utility code still in TypeScript during transition.
```

## Initialization Workflow

<Steps>
  <Step title="Run FIRE init">
    ```bash theme={null}
    npx specsmd@latest install
    ```

    Select FIRE flow
  </Step>

  <Step title="Monorepo Detection">
    FIRE detects monorepo structure and maps modules
  </Step>

  <Step title="Per-Module Scan">
    Each module analyzed for tech stack and patterns
  </Step>

  <Step title="Standards Generation">
    * Root standards created with defaults
    * Module standards created with overrides
    * Constitution created with universal policies
  </Step>

  <Step title="Review and Confirm">
    Review generated standards, adjust as needed
  </Step>
</Steps>


# FIRE Flow Overview
Source: https://specs.md/fire-flow/overview

Fast Intent-Run Engineering - Ship in hours with adaptive checkpoints

## What is FIRE?

**FIRE (Fast Intent-Run Engineering)** is an **Adaptive Spec-Driven Development** flow with first-class Monorepo and Brownfield support. It kills the ceremony and right-sizes the rigor—because fixing a UI bug isn't the same as refactoring your payment gateway.

<Info>
  **Check when necessary, not check everything.** FIRE dynamically decides when to ask for human input and when to burn through the task, saving your attention for moments that actually matter.
</Info>

```mermaid actions={false} theme={null}
flowchart LR
    I(Intent):::design --> W(Work Items):::plan --> R(Runs):::build --> D(Done):::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

## Key Differentiators

<CardGroup>
  <Card title="Dynamic Execution" icon="rotate">
    **No pre-planned execution.** Builder scans remaining work items and recommends what to run next based on dependencies and current state.
  </Card>

  <Card title="Adaptive Checkpoints" icon="sliders">
    **0-2 checkpoints per work item** based on complexity. Autopilot for simple tasks, Validate for critical changes.
  </Card>

  <Card title="First-Class Brownfield" icon="building">
    Auto-detects existing patterns, respects conventions, and extends rather than rewrites your codebase.
  </Card>

  <Card title="Monorepo Support" icon="folder-tree">
    Hierarchical standards with module-specific overrides. One project, multiple tech stacks.
  </Card>

  <Card title="Walkthrough Generation" icon="file-lines">
    Every change documented automatically. Review what AI did without digging through code.
  </Card>

  <Card title="Change-Friendly" icon="arrows-rotate">
    Requirements changed? Just update your specs. No execution plans to re-create—next run adapts automatically.
  </Card>
</CardGroup>

## FIRE vs AI-DLC (specs.md)

FIRE and specs.md's AI-DLC flow share intent-driven philosophy but are distinct flows. FIRE prioritizes adaptive execution; our AI-DLC implementation prioritizes comprehensive traceability.

| Aspect                  | FIRE                                        | specs.md AI-DLC                                    |
| ----------------------- | ------------------------------------------- | -------------------------------------------------- |
| **Philosophy**          | Intent-driven, AI proposes, human validates | Same                                               |
| **Hierarchy**           | Intent → Work Item → Run                    | Intent → Unit → Story → Bolt → Stages              |
| **Execution Planning**  | Dynamic—Builder recommends next run         | Pre-planned—Bolts created before execution         |
| **Requirement Changes** | Just update specs, next run adapts          | May require re-planning bolts                      |
| **Checkpoints**         | Adaptive (based on complexity + config)     | Comprehensive (fixed per bolt type)                |
| **Agents**              | 3 (Orchestrator, Planner, Builder)          | 4 (Master, Inception, Construction, Operations)    |
| **Artifacts**           | Adaptive (design docs when needed)          | Comprehensive (per bolt type)                      |
| **Phases**              | Plan → Execute (continuous)                 | Inception → Construction → Operations (sequential) |
| **Design Approach**     | Adaptive based on complexity                | DDD or Simple bolt types                           |
| **Optimized For**       | Teams who hate friction                     | Teams needing full traceability                    |

<Info>
  **Shared philosophy**: Both flows use intents, structured artifacts, and human validation. FIRE adapts the ceremony to the task; AI-DLC provides comprehensive ceremony always.
</Info>

### Dynamic vs Pre-Planned Execution

This is a fundamental difference in how the two flows handle execution:

**FIRE (Dynamic)**: When you invoke the Builder agent, it scans all remaining intents and work items, analyzes their dependencies, and recommends which work items can run together next. You approve or adjust, then it executes. No execution plans are created ahead of time.

**AI-DLC (Pre-Planned)**: During the Inception phase, you create "bolts"—pre-defined execution plans that bundle stories together with specific stages. Bolts are planned before construction begins.

<Warning>
  **Why this matters for changing requirements**: In AI-DLC, if you add new stories or modify units after bolt planning, you may need to re-plan your bolts. In FIRE, just update your specs—the Builder will see the changes and recommend accordingly on the next run.
</Warning>

## When to Use FIRE

<AccordionGroup>
  <Accordion title="You hate unnecessary friction">
    FIRE is built for collectives—tight-knit teams and solo devs who want to ship without bureaucracy getting in the way.
  </Accordion>

  <Accordion title="You're working in a brownfield codebase">
    FIRE analyzes your existing structure. It respects the patterns you already have and extends rather than rewrites.
  </Accordion>

  <Accordion title="You have a monorepo">
    Hierarchical standards support different tech stacks per module while sharing common policies.
  </Accordion>

  <Accordion title="You want adaptive rigor">
    Simple tasks burn through fast. Complex changes get the attention they deserve. FIRE right-sizes the ceremony.
  </Accordion>

  <Accordion title="Your project doesn't always need DDD">
    If your project doesn't need complex domain modeling, FIRE won't force it. Design docs appear when complexity warrants them.
  </Accordion>
</AccordionGroup>

## When to Consider specs.md AI-DLC Instead

<Info>
  **specs.md's AI-DLC flow may be a better fit if:**

  * You need comprehensive documentation for every change (regulatory/audit requirements)
  * Your organization mandates fixed approval workflows
  * You prefer predictable ceremony over adaptive execution

  Note: FIRE can handle complex domains—it will adapt with design documentation when needed. The choice is about workflow preference, not capability limits.
</Info>

## Core Concepts

### Intent

A high-level objective that delivers user value. Captured through guided conversation, not lengthy specs.

```yaml theme={null}
intent:
  id: auth-system
  title: User Authentication System
  status: in_progress
  priority: high
```

### Work Item

A discrete, executable unit of work derived from an Intent. Each work item completes in a single Run.

```yaml theme={null}
work_item:
  id: create-user-schema
  title: Create user database schema
  complexity: low
  mode: autopilot  # 0 checkpoints
```

### Run

A single execution cycle for a work item. Loads context, executes per mode, tracks changes, generates walkthrough.

### Walkthrough

Generated after each run. Documents what changed, why, and how to verify it.

## Adaptive Execution

FIRE doesn't guess—it analyzes two inputs to decide the execution path:

1. **Work Complexity**: Is this a simple tweak or a systemic change?
2. **Your Autonomy Config**: How much oversight do you want?

These combine to dynamically choose when to ask and when to burn through:

| Mode          | Checkpoints       | Use For                                        |
| ------------- | ----------------- | ---------------------------------------------- |
| **Autopilot** | 0                 | Bug fixes, minor updates, well-defined changes |
| **Confirm**   | 1 (plan)          | Standard features, moderate complexity         |
| **Validate**  | 2 (design + plan) | Security, payments, core architecture          |

You configure your autonomy preference during project initialization:

<Frame>
  <img alt="FIRE Autonomy Configuration" />
</Frame>

<Card title="Execution Modes" icon="sliders" href="/fire-flow/execution-modes">
  Learn how Autopilot, Confirm, and Validate modes work with detailed flow diagrams
</Card>

## Project Structure

```
project/
├── .specsmd/
│   └── fire/                    # FIRE flow definition
│       └── agents/              # Agent definitions
│
└── .specs-fire/                 # Project artifacts
    ├── state.yaml               # Central state tracking
    ├── standards/               # Project standards
    │   ├── constitution.md      # Universal policies (always inherited)
    │   ├── tech-stack.md        # Technology choices
    │   ├── coding-standards.md  # Code conventions
    │   └── folder-structure.md  # Directory layout
    ├── intents/                 # Intent documentation
    │   └── {intent-id}/
    │       ├── brief.md
    │       └── work-items/
    ├── runs/                    # Run logs
    └── walkthroughs/            # Generated documentation
```

## Get Started

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Step>

  <Step title="Select FIRE during init">
    Choose "FIRE" when prompted for flow selection
  </Step>

  <Step title="Capture your first intent">
    ```
    /specsmd-fire-planner
    ```

    Describe what you want to build
  </Step>

  <Step title="Execute work items">
    ```
    /specsmd-fire-builder
    ```

    AI executes with appropriate checkpoints
  </Step>
</Steps>

<Card title="Quick Start Guide" icon="rocket" href="/fire-flow/quick-start">
  Step-by-step guide to shipping your first feature with FIRE
</Card>


# FIRE Quick Start
Source: https://specs.md/fire-flow/quick-start

Ship your first feature in under an hour with FIRE flow

## Prerequisites

* Node.js 18+ installed
* An AI coding tool (Claude Code, Cursor, GitHub Copilot, etc.)
* A project to work on (greenfield or brownfield)

## Installation

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Step>

  <Step title="Select FIRE flow">
    When prompted, select **FIRE** as your development flow:

    ```
    ? Select a development flow:
      AI-DLC - Full methodology with DDD
    ❯ FIRE - Adaptive execution, brownfield & monorepo ready
      Simple - Spec generation only
    ```
  </Step>

  <Step title="Choose your AI tool">
    Select your preferred AI coding tool for agent configuration
  </Step>
</Steps>

## Your First Intent

### 1. Start the Planner Agent

In your AI coding tool, invoke the FIRE Planner:

<Tabs>
  <Tab title="Claude Code">
    ```
    /specsmd-fire-planner
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-fire-planner
    ```

    Or use the `@` prefix:

    ```
    @fire-planner
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    @fire-planner
    ```
  </Tab>
</Tabs>

### 2. Describe Your Intent

Tell the Planner what you want to build:

```
I want to add user authentication with email/password login,
password reset, and session management.
```

The Planner will:

1. Ask clarifying questions if needed
2. Create an intent document
3. Decompose it into work items

### 3. Review Work Items

The Planner generates work items with recommended execution modes:

```yaml theme={null}
work_items:
  - id: user-schema
    title: Create user database schema
    complexity: low
    mode: autopilot      # AI executes directly

  - id: login-endpoint
    title: Implement login API endpoint
    complexity: medium
    mode: confirm        # Human confirms plan first

  - id: session-management
    title: Add session management
    complexity: high
    mode: validate       # Full review before execution
```

## Execute Work Items

### 1. Start the Builder Agent

<Tabs>
  <Tab title="Claude Code">
    ```
    /specsmd-fire-builder
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-fire-builder
    ```

    Or use the `@` prefix:

    ```
    @fire-builder
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    @fire-builder
    ```
  </Tab>
</Tabs>

### 2. Builder Picks Next Work Item

The Builder automatically selects the next work item based on dependencies:

```
Starting work item: user-schema
Mode: Autopilot (0 checkpoints)

Executing...
```

### 3. Execution by Mode

<AccordionGroup>
  <Accordion title="Autopilot Mode (0 checkpoints)">
    AI executes directly and generates a walkthrough:

    ```
    ✓ Created migration file: 20240115_create_users.sql
    ✓ Added User model: src/models/user.ts
    ✓ Updated schema exports

    Walkthrough generated: walkthroughs/run-fabriqa-2026-001-user-schema.md
    ```
  </Accordion>

  <Accordion title="Confirm Mode (1 checkpoint)">
    AI presents plan, waits for confirmation:

    ```
    Plan for: login-endpoint

    1. Create POST /auth/login endpoint
    2. Add password hashing with bcrypt
    3. Generate JWT tokens
    4. Add rate limiting

    [Confirm to proceed? y/n]
    ```
  </Accordion>

  <Accordion title="Validate Mode (2 checkpoints)">
    AI generates design doc, waits for review, then confirmation:

    ```
    Design document generated: intents/auth/work-items/session-management.md

    Please review the design before proceeding.
    [Review complete? y/n]

    ---

    Implementation plan:
    1. Add Redis session store
    2. Implement session middleware
    3. Add logout endpoint

    [Approve implementation? y/n]
    ```
  </Accordion>
</AccordionGroup>

### 4. Review Walkthroughs

After each run, review the generated walkthrough:

```markdown theme={null}
# Run 001: user-schema

## Summary
Created user database schema with email/password authentication fields.

## Files Changed
- `migrations/20240115_create_users.sql` (created)
- `src/models/user.ts` (created)
- `src/models/index.ts` (modified)

## Key Decisions
- Used UUID for user IDs (portable across databases)
- Added soft delete with deleted_at column
- Indexed email for fast lookups

## Verification Steps
1. Run `npm run migrate` to apply schema
2. Verify table created: `SELECT * FROM users LIMIT 1`

## Test Coverage
- Unit test added: `tests/models/user.test.ts`
```

## State Tracking

FIRE maintains state in `.specs-fire/state.yaml`:

```yaml theme={null}
project:
  name: my-project
  framework: fire-v1

workspace:
  type: brownfield
  structure: monolith
  default_mode: confirm

intents:
  - id: auth-system
    title: User Authentication
    status: in_progress
    work_items:
      - id: user-schema
        status: done
        completed_in_run: 1
      - id: login-endpoint
        status: in_progress
        started_in_run: 2
      - id: session-management
        status: pending

runs:
  last_completed: 1
  active: 2
```

## Brownfield Projects

For existing codebases, FIRE auto-detects:

<Steps>
  <Step title="Quick Scan (2-5 min)">
    Pattern-based detection of language, framework, and structure
  </Step>

  <Step title="Standards Generation">
    AI generates standards matching your existing patterns:

    * Tech stack (detected frameworks, libraries)
    * Coding standards (existing conventions)
    * Folder structure (current layout)
  </Step>

  <Step title="Review and Confirm">
    Review generated standards and adjust if needed
  </Step>
</Steps>

<Info>
  FIRE follows **brownfield rules**: search before create, respect patterns, minimal changes.
</Info>

## Monorepo Projects

For monorepos, FIRE supports hierarchical standards:

```
project/
├── .specs-fire/
│   └── standards/
│       ├── constitution.md      # Universal (always inherited)
│       └── tech-stack.md        # Default stack
│
├── packages/api/
│   └── .specs-fire/
│       └── standards/
│           └── tech-stack.md    # Override: Go, Echo
│
└── packages/web/
    └── .specs-fire/
        └── standards/
            └── tech-stack.md    # Override: React, TypeScript
```

<Info>
  Learn more in [Monorepo Support](/fire-flow/monorepo-support).
</Info>

## Command Reference

| Command                 | Description                               |
| ----------------------- | ----------------------------------------- |
| `/specsmd-fire`         | Entry point, routes to appropriate agent  |
| `/specsmd-fire-planner` | Capture intents, decompose work items     |
| `/specsmd-fire-builder` | Execute work items, generate walkthroughs |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent doesn't remember context">
    Agents are stateless—they read `state.yaml` and artifacts at startup. Ensure files are saved after each step.
  </Accordion>

  <Accordion title="Work item stuck">
    Check `.specs-fire/state.yaml` to see work item status. If blocked, the Builder will explain what's needed.
  </Accordion>

  <Accordion title="Want to change execution mode">
    You can override the suggested mode during execution. Say "Override to Confirm" or "Override to Validate".
  </Accordion>

  <Accordion title="Brownfield detection wrong">
    Review generated standards in `.specs-fire/standards/` and edit as needed. The Planner respects your overrides.
  </Accordion>

  <Accordion title="Multiple intents exist">
    Run `/specsmd-fire` to see all intents and their status, then specify which to work on.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Execution Modes" icon="sliders" href="/fire-flow/execution-modes">
    Master Autopilot, Confirm, and Validate modes
  </Card>

  <Card title="Work Items" icon="list-check" href="/fire-flow/work-items">
    Deep dive into work item structure
  </Card>

  <Card title="Monorepo Support" icon="folder-tree" href="/fire-flow/monorepo-support">
    Hierarchical standards for multi-module projects
  </Card>

  <Card title="FIRE Agents" icon="robot" href="/fire-flow/agents">
    Orchestrator, Planner, and Builder details
  </Card>
</CardGroup>


# Work Items & Runs
Source: https://specs.md/fire-flow/work-items

The core units of execution in FIRE flow

## FIRE Hierarchy

FIRE uses a streamlined hierarchy compared to AI-DLC:

```mermaid actions={false} theme={null}
flowchart TD
    I(Intent):::design --> W1(Work Item 1):::plan
    I --> W2(Work Item 2):::plan
    I --> W3(Work Item 3):::plan
    W1 --> R1(Run):::build
    W2 --> R2(Run):::build
    W3 --> R3(Run):::build
    R1 --> T1(Walkthrough):::done
    R2 --> T2(Walkthrough):::done
    R3 --> T3(Walkthrough):::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Level         | FIRE        | AI-DLC Equivalent |
| ------------- | ----------- | ----------------- |
| Goal          | Intent      | Intent            |
| Work Unit     | Work Item   | Unit + Story      |
| Execution     | Run         | Bolt              |
| Documentation | Walkthrough | Bolt artifacts    |

## Intents

An **Intent** is a high-level objective that delivers user value. It's the "what" and "why" of your feature.

### Structure

```yaml theme={null}
intent:
  id: auth-system
  title: User Authentication System
  description: |
    Enable users to create accounts, log in securely,
    and manage their sessions.
  status: in_progress
  priority: high
  created: 2024-01-15T10:00:00Z
```

### Intent Document

Intents are documented in `.specs-fire/intents/{id}/brief.md`:

```markdown theme={null}
# User Authentication System

## Objective
Enable users to create accounts, log in securely, and manage sessions.

## Context
- New greenfield project
- Expected 10k users at launch
- Must support social login in future (not MVP)

## Success Criteria
- Users can register with email/password
- Users can log in and receive session token
- Sessions expire after 24 hours
- Password reset via email works
```

### Intent States

| State         | Description                    |
| ------------- | ------------------------------ |
| `pending`     | Captured but not started       |
| `in_progress` | Work items being executed      |
| `blocked`     | Waiting on external dependency |
| `done`        | All work items completed       |

## Work Items

A **Work Item** is a discrete, executable unit of work. Each work item:

* Has a clear definition of done
* Completes in a single Run
* Has assigned complexity and execution mode
* Can depend on other work items

### Structure

```yaml theme={null}
work_item:
  id: user-schema
  intent_id: auth-system
  title: Create user database schema
  description: Set up the users table with authentication fields
  complexity: low
  mode: autopilot
  depends_on: []
  status: pending
```

### Work Item Document

Work items are documented in `.specs-fire/intents/{intent-id}/work-items/{id}.md`:

```markdown theme={null}
# Create User Database Schema

## Definition of Done
- [ ] Migration file created
- [ ] User model with typed fields
- [ ] Indexes on email field
- [ ] Tests for model validation

## Technical Notes
- Use UUID for primary key
- Add soft delete support
- Email must be unique and indexed

## Dependencies
None - first work item
```

### Complexity Levels

| Level    | Description                               | Typical Mode |
| -------- | ----------------------------------------- | ------------ |
| `low`    | \< 50 lines, single file, well-defined    | Autopilot    |
| `medium` | 50-200 lines, 2-5 files, some decisions   | Confirm      |
| `high`   | 200+ lines, 5+ files, architecture impact | Validate     |

### Work Item States

| State         | Description            |
| ------------- | ---------------------- |
| `pending`     | Not yet started        |
| `in_progress` | Currently executing    |
| `blocked`     | Dependency not met     |
| `done`        | Successfully completed |

### Dependencies

Work items can depend on each other:

```yaml theme={null}
work_items:
  - id: user-schema
    depends_on: []

  - id: login-endpoint
    depends_on: [user-schema]  # Must complete first

  - id: session-middleware
    depends_on: [login-endpoint]
```

The Builder respects dependencies when selecting the next work item.

## Runs

A **Run** is a single execution cycle for a work item. It's atomic: either completes successfully or rolls back.

### Run Lifecycle

```mermaid actions={false} theme={null}
stateDiagram-v2
    [*] --> Loading: Start Run
    Loading --> Planning: Context Loaded
    Planning --> Checkpoint: Mode Requires
    Planning --> Executing: Autopilot
    Checkpoint --> Executing: Approved
    Checkpoint --> Planning: Rejected (revise)
    Executing --> Documenting: Changes Applied
    Documenting --> Complete: Walkthrough Generated
    Complete --> [*]
    Executing --> Failed: Error
    Failed --> [*]

    note right of Checkpoint
        0, 1, or 2 checkpoints
        based on mode
    end note
```

### Run Phases

<Steps>
  <Step title="Loading">
    Load project context, standards, and work item details
  </Step>

  <Step title="Planning">
    Generate execution plan based on context
  </Step>

  <Step title="Checkpoint (if required)">
    Present plan/design for human review
  </Step>

  <Step title="Executing">
    Apply changes to codebase
  </Step>

  <Step title="Documenting">
    Generate walkthrough with all changes
  </Step>
</Steps>

### Run Tracking

Runs are logged in `.specs-fire/runs/{id}.yaml`:

```yaml theme={null}
run:
  id: 1
  work_item_id: user-schema
  intent_id: auth-system
  mode: autopilot
  started: 2024-01-15T10:30:00Z
  completed: 2024-01-15T10:32:00Z
  status: success
  files:
    created:
      - migrations/20240115_create_users.sql
      - src/models/user.ts
    modified:
      - src/models/index.ts
    deleted: []
  walkthrough: walkthroughs/run-fabriqa-2026-001-user-schema.md
```

## Walkthroughs

A **Walkthrough** is generated after each successful run. It documents what changed and why.

### Structure

```markdown theme={null}
# Run run-fabriqa-2026-001: user-schema

## Summary
Created user database schema with email/password authentication fields.

## Files Changed

### Created
- `migrations/20240115_create_users.sql`
  - Users table with id, email, password_hash, created_at, updated_at
  - Unique index on email
  - Soft delete with deleted_at column

- `src/models/user.ts`
  - User model class with TypeORM decorators
  - Password hashing on save
  - Email validation

### Modified
- `src/models/index.ts`
  - Added User export

## Key Decisions
- Used UUID for user IDs (portable across databases)
- Added soft delete for GDPR compliance
- bcrypt with cost factor 12 for password hashing

## Verification Steps
1. Run `npm run migrate` to apply schema
2. Verify table: `SELECT * FROM information_schema.tables WHERE table_name = 'users'`
3. Run tests: `npm test -- --grep "User model"`

## Test Coverage
- `tests/models/user.test.ts` - 4 tests added
  - Creates user with valid email
  - Rejects duplicate email
  - Hashes password on save
  - Supports soft delete
```

### Why Walkthroughs Matter

<Info>
  Walkthroughs enable **async review**. You don't need to watch AI code in real-time—review the walkthrough when convenient.
</Info>

Benefits:

* Complete audit trail of all changes
* Easy to review without reading every line
* Verification steps for QA
* Context for future developers

## State Management

All state is tracked in `.specs-fire/state.yaml`:

```yaml theme={null}
project:
  name: my-project
  created: 2024-01-15T09:00:00Z
  framework: fire-v1

workspace:
  type: brownfield
  structure: monolith
  default_mode: confirm

intents:
  - id: auth-system
    title: User Authentication
    status: in_progress
    priority: high
    work_items:
      - id: user-schema
        status: done
        complexity: low
        depends_on: []
        completed_in_run: 1
      - id: login-endpoint
        status: in_progress
        complexity: medium
        depends_on: [user-schema]
        started_in_run: 2
      - id: session-management
        status: pending
        complexity: high
        depends_on: [login-endpoint]

summary:
  total_intents: 1
  intents_done: 0
  total_work_items: 3
  work_items_done: 1

runs:
  last_completed: 1
  active: 2
```

### State Scripts

FIRE uses deterministic scripts for state management:

| Script                      | Purpose                  |
| --------------------------- | ------------------------ |
| `state-read`                | Parse state, return JSON |
| `state-update-intent`       | Add/update intent        |
| `state-update-work-item`    | Update work item status  |
| `state-recalculate-summary` | Refresh counts           |
| `state-set-active-run`      | Track active run         |

<Info>
  Scripts ensure deterministic state updates. AI calls scripts rather than editing YAML directly.
</Info>

## Best Practices

### Work Item Sizing

<AccordionGroup>
  <Accordion title="Too Small">
    ❌ "Add import statement"
    ❌ "Create empty file"
    ❌ "Add one test case"

    These are implementation details, not work items.
  </Accordion>

  <Accordion title="Just Right">
    ✅ "Create user database schema"
    ✅ "Implement login endpoint"
    ✅ "Add session management"

    Each delivers value and has clear completion criteria.
  </Accordion>

  <Accordion title="Too Large">
    ❌ "Build authentication system"
    ❌ "Implement entire API"

    These are Intents, not work items. Decompose them.
  </Accordion>
</AccordionGroup>

### Dependency Management

* Keep dependencies minimal
* Avoid circular dependencies
* Use `blocked` status when waiting
* Builder auto-selects based on dependencies

### Walkthrough Review

* Review walkthroughs after each run
* Flag issues before moving to next work item
* Use walkthroughs for code review context


# IDE Extension
Source: https://specs.md/getting-started/ide-extension

Track your AI-DLC progress with the specsmd sidebar extension for VS Code and compatible IDEs

## Overview

The specsmd IDE extension provides a visual dashboard for tracking your development progress across both **FIRE Flow** and **AI-DLC Flow**. Monitor runs/bolts, browse specs, and see project metrics—all from your IDE sidebar.

<img alt="VS Code Extension Preview" />

<Info>
  Works with VS Code-based IDEs including [Cursor](https://cursor.sh), [Google Antigravity](https://antigravity.google), [Windsurf](https://codeium.com/windsurf), [GitHub Codespaces](https://github.com/features/codespaces), [Gitpod](https://gitpod.io), and [Amazon Kiro](https://kiro.dev).
</Info>

## Installation

<Tabs>
  <Tab title="VS Code Marketplace">
    Install directly from the Microsoft VS Code Marketplace:

    1. Open VS Code (or Cursor, Windsurf, etc.)
    2. Go to Extensions (`Cmd+Shift+X` / `Ctrl+Shift+X`)
    3. Search for "specsmd"
    4. Click **Install**

    Or install via command line:

    ```bash theme={null}
    code --install-extension fabriqaai.specsmd
    ```

    <Card title="View on VS Code Marketplace" icon="microsoft" href="https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd">
      Install from the official VS Code Marketplace
    </Card>

    **Compatible IDEs:** VS Code, GitHub Codespaces
  </Tab>

  <Tab title="Open VSX Registry">
    Install from Open VSX for VS Code forks and open-source IDEs:

    1. Open your IDE (Cursor, Windsurf, Kiro, etc.)
    2. Go to Extensions
    3. Search for "specsmd"
    4. Click **Install**

    <Card title="View on Open VSX" icon="box" href="https://open-vsx.org/extension/fabriqaai/specsmd">
      Install from the Open VSX Registry
    </Card>

    **Compatible IDEs:** Cursor, Windsurf, Amazon Kiro, Google Antigravity, VSCodium, Gitpod, Google IDX, Eclipse Theia, Code-Server
  </Tab>

  <Tab title="Manual Install (VSIX)">
    Download and install the VSIX file manually:

    1. Go to [GitHub Releases](https://github.com/fabriqaai/specs.md/releases)
    2. Download the latest `.vsix` file
    3. In VS Code, open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
    4. Run "Extensions: Install from VSIX..."
    5. Select the downloaded file

    <Card title="GitHub Releases" icon="github" href="https://github.com/fabriqaai/specs.md/releases">
      Download VSIX for manual installation
    </Card>
  </Tab>
</Tabs>

## Features

The extension supports **both FIRE Flow and AI-DLC Flow**. It automatically detects which flow you're using and adapts the interface accordingly.

***

## FIRE Flow Views

If you're using FIRE Flow (`.specs-fire/` folder), the extension provides:

<Frame>
  <img alt="FIRE Flow - Runs Tab" />
</Frame>

* **Runs Tab** - Track active runs and completed runs with file listings
* **Intents Tab** - Browse intents and work items with progress indicators
* **Overview Tab** - Project-wide metrics and quick actions

<Frame>
  <img alt="FIRE Flow - Overview" />
</Frame>

***

## AI-DLC Flow Views

If you're using AI-DLC Flow (`memory-bank/` folder), the extension provides three main views:

### Bolts Tab

Track your bolt execution progress in real-time.

<Frame>
  <img alt="Bolts Tab" />
</Frame>

<AccordionGroup>
  <Accordion title="Current Focus">
    Shows active bolts being worked on with:

    * Bolt name and type (DDD, Simple)
    * Current stage progress
    * Stage pipeline with status indicators
    * Stories list with completion status
  </Accordion>

  <Accordion title="Up Next Queue">
    Shows pending bolts ready to be started:

    * Unblocked bolts first (higher priority)
    * Blocked bolts with dependency info
    * Quick start button for each bolt
  </Accordion>

  <Accordion title="Recent Activity">
    Timeline of bolt and stage completions:

    * Filterable by All, Stages, or Bolts
    * Relative timestamps
    * Click to navigate to files
  </Accordion>
</AccordionGroup>

### Specs Tab

Browse your project specifications hierarchically.

<Frame>
  <img alt="Specs Tab" />
</Frame>

* **Intents** - High-level goals with progress indicators
* **Units** - Cohesive work elements within intents
* **Stories** - Individual user stories with status

Click any item to open its markdown file.

### Overview Tab

High-level project metrics and quick actions.

<Frame>
  <img alt="Overview Tab" />
</Frame>

* **Progress** - Overall completion percentage
* **Stats** - Active, queued, done, and blocked bolts
* **Suggested Actions** - AI-recommended next steps
* **Standards** - Quick access to project standards

## Activation

The extension automatically activates when it detects:

* A `memory-bank/` folder in your workspace (AI-DLC Flow)
* A `.specs-fire/` folder in your workspace (FIRE Flow)
* A `.specsmd/` folder in your workspace

<Note>
  Make sure you've run `npx specsmd@latest install` first to set up your project structure.
</Note>

## Refreshing Data

The extension watches your memory-bank files for changes. To manually refresh:

* Click the refresh icon in the sidebar header
* Or use Command Palette: "specsmd: Refresh"

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension not showing in sidebar">
    Ensure your workspace has one of these folders:

    * `memory-bank/` (AI-DLC Flow)
    * `.specs-fire/` (FIRE Flow)
    * `.specsmd/` (Either flow)

    The extension only activates when these are present.

    ```bash theme={null}
    # Initialize specs.md first
    npx specsmd@latest install
    ```
  </Accordion>

  <Accordion title="Data not updating">
    Click the refresh icon in the sidebar header, or check that your memory-bank files are saved.
  </Accordion>

  <Accordion title="Extension not working in Cursor/Windsurf/other IDEs">
    The extension is compatible with VS Code-based IDEs. Install from the correct registry:

    * **VS Code Marketplace** — VS Code, GitHub Codespaces (Microsoft products only)
    * **Open VSX Registry** — Cursor, Windsurf, Amazon Kiro, Google Antigravity, VSCodium, Gitpod, Google IDX, Eclipse Theia, Code-Server
    * **VSIX file** — Manual installation for any compatible IDE
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Choose Your Flow" icon="compass" href="/architecture/choose-flow">
    Compare Simple, FIRE, and AI-DLC flows
  </Card>

  <Card title="FIRE Quick Start" icon="bolt" href="/fire-flow/quick-start">
    Ship your first feature with FIRE Flow
  </Card>
</CardGroup>


# Installation
Source: https://specs.md/getting-started/installation

Install specs.md and select your development flow

## Prerequisites

* Node.js 18 or higher
* An AI coding tool (Claude Code, Cursor, GitHub Copilot, or Google Antigravity)

## Install specs.md

<Note>
  Always use npx to get the latest version. Do not install globally with npm.
</Note>

```bash theme={null}
npx specsmd@latest install
```

## Select Your Flow

During installation, you'll be prompted to select a development flow:

```
? Select a development flow:
  Simple - Spec generation only (requirements, design, tasks)
❯ FIRE - Adaptive execution, brownfield & monorepo ready
  AI-DLC - Full methodology with DDD (comprehensive checkpoints)
```

| Flow       | Best For                                       | Agents |
| ---------- | ---------------------------------------------- | ------ |
| **Simple** | Quick specs, prototypes, handoff               | 1      |
| **FIRE**   | Adaptive execution, brownfield, monorepos      | 3      |
| **AI-DLC** | Full traceability, comprehensive documentation | 4      |

<Info>
  **Not sure which flow?** Check out our [Choose Your Flow](/architecture/choose-flow) guide.
</Info>

The installer automatically detects your AI coding tools and sets up:

<CardGroup>
  <Card title="Agent Definitions" icon="robot">
    Specialized agents for your selected flow
  </Card>

  <Card title="Standards" icon="ruler">
    Project guidelines and conventions
  </Card>

  <Card title="Slash Commands" icon="terminal">
    Easy agent invocation commands
  </Card>
</CardGroup>

## What Gets Installed

After installation, you'll see the following structure based on your selected flow:

<Tabs>
  <Tab title="Simple Flow">
    ```
    .specsmd/
    ├── manifest.yaml              # Installation manifest
    └── simple/                    # Simple flow
        └── agents/                # Single agent

    specs/                         # Your specs will go here
    └── (feature folders)
    ```
  </Tab>

  <Tab title="FIRE Flow">
    ```
    .specsmd/
    ├── manifest.yaml              # Installation manifest
    └── fire/                      # FIRE flow
        ├── agents/                # Orchestrator, Planner, Builder
        └── skills/                # Agent capabilities

    .specs-fire/                   # Project artifacts
    ├── state.yaml                 # Central state tracking
    ├── standards/                 # Project standards
    ├── intents/                   # Intent documentation
    ├── runs/                      # Run logs
    └── walkthroughs/              # Generated documentation
    ```
  </Tab>

  <Tab title="AI-DLC Flow">
    ```
    .specsmd/
    ├── manifest.yaml              # Installation manifest
    └── aidlc/                     # AI-DLC flow
        ├── agents/                # Master, Inception, Construction, Operations
        ├── skills/                # Agent capabilities
        ├── templates/             # Artifact templates
        └── memory-bank.yaml       # Memory bank schema

    memory-bank/                   # Project artifacts
    ├── standards/                 # Project standards
    ├── intents/                   # Intent documentation
    └── bolts/                     # Bolt tracking
    ```
  </Tab>
</Tabs>

## Tool-Specific Setup

<Tabs>
  <Tab title="Claude Code">
    Slash commands are installed in `.claude/commands/`. Type `/` to see available commands:

    <Frame>
      <img alt="Claude Code Commands" />
    </Frame>

    **Simple Flow:**

    * `/specsmd-agent`

    **FIRE Flow:**

    * `/specsmd-fire`
    * `/specsmd-fire-planner`
    * `/specsmd-fire-builder`

    **AI-DLC Flow:**

    * `/specsmd-master-agent`
    * `/specsmd-inception-agent`
    * `/specsmd-construction-agent`
    * `/specsmd-operations-agent`
  </Tab>

  <Tab title="Cursor">
    Commands are installed in `.cursor/commands/` as `.md` files. Invoke them by typing `/` followed by the command name:

    <Frame>
      <img alt="Cursor Commands" />
    </Frame>

    **Simple Flow:**

    * `/specsmd-agent`

    **FIRE Flow:**

    * `/specsmd-fire`
    * `/specsmd-fire-planner`
    * `/specsmd-fire-builder`

    **AI-DLC Flow:**

    * `/specsmd-master-agent`
    * `/specsmd-inception-agent`
    * `/specsmd-construction-agent`
    * `/specsmd-operations-agent`
  </Tab>

  <Tab title="GitHub Copilot">
    Agents are installed in `.github/agents/` using `.agent.md` format. Type `/` to see available commands:

    <Frame>
      <img alt="GitHub Copilot Commands" />
    </Frame>

    **Simple Flow:**

    * `/specsmd-agent`

    **FIRE Flow:**

    * `/specsmd-fire`
    * `/specsmd-fire-planner`
    * `/specsmd-fire-builder`

    **AI-DLC Flow:**

    * `/specsmd-master-agent`
    * `/specsmd-inception-agent`
    * `/specsmd-construction-agent`
    * `/specsmd-operations-agent`
  </Tab>

  <Tab title="Google Antigravity">
    Workflows are installed in `.agent/workflows/` as `.md` files. Type `/` to see available commands:

    <Frame>
      <img alt="Google Antigravity Commands" />
    </Frame>

    **Simple Flow:**

    * `/specsmd-agent`

    **FIRE Flow:**

    * `/specsmd-fire`
    * `/specsmd-fire-planner`
    * `/specsmd-fire-builder`

    **AI-DLC Flow:**

    * `/specsmd-master-agent`
    * `/specsmd-inception-agent`
    * `/specsmd-construction-agent`
    * `/specsmd-operations-agent`
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Simple Quick Start" icon="feather" href="/simple-flow/quick-start">
    Generate specs in minutes
  </Card>

  <Card title="FIRE Quick Start" icon="bolt" href="/fire-flow/quick-start">
    Ship your first feature fast
  </Card>

  <Card title="AI-DLC Quick Start" icon="building" href="/getting-started/quick-start">
    Full methodology walkthrough
  </Card>
</CardGroup>


# Quick Start
Source: https://specs.md/getting-started/quick-start

Choose your flow and get started with specs.md

## Choose Your Flow

specs.md offers three flows. Choose based on your project needs:

<CardGroup>
  <Card title="FIRE Flow" icon="bolt" href="/fire-flow/quick-start">
    **Adaptive execution** with right-sized checkpoints. Best for teams who hate friction.
  </Card>

  <Card title="AI-DLC Flow" icon="building" href="/agents/quick-start">
    **Full methodology** with DDD and comprehensive traceability. Best for complex domains.
  </Card>

  <Card title="Simple Flow" icon="feather" href="/simple-flow/quick-start">
    **Spec generation only**. Best for quick prototypes and documentation.
  </Card>
</CardGroup>

<Info>
  Not sure which to pick? See [Choose Your Flow](/architecture/choose-flow) for a detailed comparison.
</Info>

***

## Flow Comparison

| Flow       | Checkpoints    | Optimized For                                  |
| ---------- | -------------- | ---------------------------------------------- |
| **FIRE**   | Adaptive (0-2) | Teams who hate friction, brownfield, monorepos |
| **AI-DLC** | Comprehensive  | Full traceability, regulated environments, DDD |
| **Simple** | 3 phase gates  | Spec generation only, quick prototypes         |

### FIRE Flow

Adaptive Spec-Driven Development with first-class Monorepo and Brownfield support. FIRE dynamically decides when to ask for human input based on work complexity and your autonomy configuration.

<Card title="FIRE Quick Start" icon="bolt" href="/fire-flow/quick-start">
  Ship your first feature with FIRE
</Card>

### AI-DLC Flow

Full AI-Driven Development Lifecycle with 4 agents, Mob rituals, and DDD integration. Comprehensive traceability for every change.

<Card title="AI-DLC Quick Start" icon="building" href="/agents/quick-start">
  Build with full methodology
</Card>

### Simple Flow

Lightweight 3-phase workflow for generating requirements, design, and tasks. No execution tracking—just clean specs.

<Card title="Simple Quick Start" icon="feather" href="/simple-flow/quick-start">
  Generate specs in minutes
</Card>


# Dashboard
Source: https://specs.md/getting-started/specs-md-dashboard

Local web and terminal dashboards for tracking development progress across all specsmd flows

## Overview

The default dashboard is a local web app for monitoring your development progress in real time. It reuses the same dashboard UI components as the VS Code extension, runs against the current workspace, and watches for changes as your project state updates.

<Info>
  Use `dashboard` for the browser dashboard. Use `dashboard-cli` when you specifically want the interactive terminal UI.
</Info>

## Quick Start

```bash theme={null}
npx specsmd@latest dashboard
```

The dashboard auto-detects your flow, starts a local web server, and watches for changes. Press `Ctrl+C` in the terminal to stop it.

```bash theme={null}
npx specsmd@latest dashboard --no-open
```

## Web Dashboard

```bash theme={null}
npx specsmd@latest dashboard [options]
```

The web dashboard starts on `127.0.0.1` by default and opens your browser automatically. When you click a document, story, standard, or artifact, specsmd asks your operating system to open that local file from the current workspace.

Use it when you are working outside VS Code but still want the same visual planning surface:

* See the current AI-DLC bolt/run/spec state while coding in another editor or terminal-native agent
* Review specs, units, stories, standards, and recent completions without running the slower terminal dashboard
* Keep a browser tab open as a live status board while agents update the local `memory-bank`, `.specs-fire`, or `specs` folder
* Click through to local markdown documents and artifacts from the dashboard

| Option             | Default               | Description                                   |
| ------------------ | --------------------- | --------------------------------------------- |
| `--flow <flow>`    | auto-detect           | Flow to inspect: `fire`, `aidlc`, or `simple` |
| `--path <dir>`     | current directory     | Workspace path to analyze                     |
| `--host <host>`    | `127.0.0.1`           | Host for the local dashboard server           |
| `--port <n>`       | random available port | Port for the local dashboard server           |
| `--refresh-ms <n>` | `1000`                | Reserved compatibility refresh interval       |
| `--no-open`        | `false`               | Print the URL without opening a browser       |
| `--no-watch`       | `false`               | Disable live file watching                    |

### Web Examples

```bash theme={null}
# Auto-detect flow and open the browser
npx specsmd@latest dashboard

# Run without opening the browser
npx specsmd@latest dashboard --no-open

# Inspect another workspace
npx specsmd@latest dashboard --path ../my-project

# Use a fixed local port
npx specsmd@latest dashboard --port 4317
```

## Web Dashboard Screenshots

### Bolts View

<Frame>
  <img alt="SpecsMD web dashboard Bolts view showing current focus, completed bolts, and recent activity" />
</Frame>

### Specs View

<Frame>
  <img alt="SpecsMD web dashboard Specs view showing intents, units, and stories from the local memory bank" />
</Frame>

### Overview View

<Frame>
  <img alt="SpecsMD web dashboard Overview view showing overall progress, suggested actions, intents, and standards" />
</Frame>

## Terminal Dashboard

```bash theme={null}
npx specsmd@latest dashboard-cli
```

The terminal dashboard auto-detects your flow and starts watching for changes. Press `q` to quit.

## Terminal Dashboard Screenshots

### Git Changes Tab (Commit Diff Preview)

<Frame>
  <img alt="CLI Dashboard Git Changes tab with commit diff preview" />
</Frame>

### Active Tab (File Preview Pane)

<Frame>
  <img alt="CLI Dashboard Active tab with file preview pane" />
</Frame>

## Terminal Tabs

The terminal dashboard has five tabs, switched with number keys `1`–`5`:

<Steps>
  <Step title="Active Items (1)">
    Shows currently active runs (FIRE), bolts (AI-DLC), or specs (Simple) in the selected worktree. Includes a split preview pane for inspecting files and an "other worktrees" section showing activity across branches.
  </Step>

  <Step title="Intents (2)">
    Lists all intents in your project. Toggle between pending (`n`) and completed (`x`) intents.
  </Step>

  <Step title="Completed (3)">
    Historical view of finished runs, bolts, or specs with intent filtering.
  </Step>

  <Step title="Standards & Health (4)">
    Project standards files (constitution, tech-stack, coding-standards), progress stats, warnings, and error details.
  </Step>

  <Step title="Git Changes (5)">
    Git status with staged, unstaged, untracked, and conflicted files. Select a file to preview its diff in the split pane. Shows branch tracking info with ahead/behind counts.
  </Step>
</Steps>

## Terminal Keyboard Shortcuts

### Global

| Key            | Action                               |
| -------------- | ------------------------------------ |
| `1`–`5`        | Switch tab                           |
| `r`            | Refresh                              |
| `h` / `?`      | Toggle help overlay                  |
| `]` / `m`      | Switch flow (when multiple detected) |
| `[`            | Switch flow backward                 |
| `g` / `G`      | Next / previous section              |
| `q` / `Ctrl+C` | Quit                                 |

### Navigation & Preview

| Key               | Action                                |
| ----------------- | ------------------------------------- |
| `↑` `↓` / `j` `k` | Navigate rows                         |
| `Enter`           | Expand / collapse folder              |
| `v` / `Space`     | Preview file in split pane            |
| `v` `v`           | Fullscreen preview                    |
| `Tab`             | Switch focus between main and preview |
| `o`               | Open file in default app              |
| `Esc`             | Close overlay / preview               |

### Section Focus

| Key       | Tab | Jumps to                |
| --------- | --- | ----------------------- |
| `a`       | 1   | Active item             |
| `f`       | 1   | Files                   |
| `b`       | 1   | Worktree switcher       |
| `u`       | 1   | Other worktrees         |
| `i`       | 2   | Intents                 |
| `n` / `x` | 2   | Next / completed toggle |
| `c`       | 3   | Completed               |
| `s`       | 4   | Standards               |
| `t`       | 4   | Stats                   |
| `w`       | 4   | Warnings                |
| `e`       | 4   | Errors                  |
| `d`       | 5   | Git diff                |

## Terminal Git Worktree Support

The terminal dashboard auto-discovers git worktrees and shows activity across branches.

* **Worktree switcher** — press `b` on the Active tab to switch between worktrees
* **Cross-worktree view** — the "Other worktrees" section shows active runs/bolts in other branches
* **Auto-selection** — picks the current worktree by default, falling back to main

## Terminal Dashboard Options

```bash theme={null}
npx specsmd@latest dashboard-cli [options]
```

| Option              | Default           | Description                                   |
| ------------------- | ----------------- | --------------------------------------------- |
| `--flow <flow>`     | auto-detect       | Flow to inspect: `fire`, `aidlc`, or `simple` |
| `--path <dir>`      | current directory | Workspace path                                |
| `--worktree <name>` | auto-select       | Initial worktree (branch name, id, or path)   |
| `--refresh-ms <n>`  | `1000`            | File watch interval in ms (200–5000)          |
| `--no-watch`        | `false`           | Render once and exit (non-interactive)        |

### Terminal Examples

```bash theme={null}
# Terminal UI
npx specsmd@latest dashboard-cli

# Specific terminal flow
npx specsmd@latest dashboard-cli --flow fire

# Start on a feature branch worktree
npx specsmd@latest dashboard-cli --worktree feature-auth

# One-time snapshot (CI/non-TTY)
npx specsmd@latest dashboard-cli --no-watch
```

## Icon Sets

Configure icons via the `SPECSMD_ICON_SET` environment variable:

| Value     | Style                                                               |
| --------- | ------------------------------------------------------------------- |
| `ascii`   | Plain ASCII characters (default)                                    |
| `unicode` | Unicode symbols                                                     |
| `nerd`    | Nerd Font icons (requires a [Nerd Font](https://www.nerdfonts.com)) |

```bash theme={null}
SPECSMD_ICON_SET=nerd npx specsmd@latest dashboard-cli
```

## Video Tutorials

Watch both dashboard modes in action: the web dashboard from Chrome/Fabriqa.AI, and the terminal dashboard alongside Codex Desktop App.

<Card title="CLI and Web Dashboard Tutorials" icon="circle-play" href="/learn/specs-md-dashboard">
  Learn the browser dashboard and the terminal dashboard workflows
</Card>


# Choosing Bolt Types
Source: https://specs.md/guides/bolt-types

A practical guide to selecting the right bolt type for your work

## Overview

The AI-DLC flow in specs.md provides two bolt types, each optimized for different types of work. Choosing the right bolt type ensures you have the appropriate level of rigor and structure for your task.

```mermaid actions={false} theme={null}
flowchart LR
    DDD(DDD Construction<br/>Complex domain logic<br/>5 stages):::design --> Simple(Simple Construction<br/>UI, integrations<br/>3 stages):::done
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

## Quick Decision Guide

<Info>
  The Inception Agent automatically selects the appropriate bolt type based on your requirements. If you disagree with its choice, you can change it during the human checkpoint review.
</Info>

<Steps>
  <Step title="Does it involve complex business logic or domain rules?">
    **Yes** → Use **DDD Construction Bolt**

    **No** → Continue to next question
  </Step>

  <Step title="Is it UI, integration, utility, or straightforward CRUD?">
    **Yes** → Use **Simple Construction Bolt**
  </Step>
</Steps>

***

## DDD Construction Bolt

<Card title="When to Use" icon="bullseye">
  Complex domain logic requiring careful modeling and design decisions.
</Card>

### Best For

* Core business logic with complex rules
* Domain models with aggregates, entities, and value objects
* Services that encode business knowledge
* Features where incorrect logic has significant consequences
* Bounded contexts with rich domain models

### Stages

| Stage                   | Purpose                                   | Output                       |
| ----------------------- | ----------------------------------------- | ---------------------------- |
| **1. Domain Model**     | Model business logic using DDD principles | Domain model document        |
| **2. Technical Design** | Apply patterns, define interfaces         | Technical design document    |
| **3. ADR Analysis**     | Document significant decisions            | Architecture Decision Record |
| **4. Implement**        | Generate production code                  | Implementation               |
| **5. Test**             | Verify correctness                        | Test suite                   |

### Example Use Cases

<AccordionGroup>
  <Accordion title="E-commerce Order Processing">
    Orders involve complex state transitions, pricing rules, inventory checks, and payment processing. DDD helps model these business rules explicitly.
  </Accordion>

  <Accordion title="Financial Calculations">
    Interest calculations, fee structures, and compliance rules require careful domain modeling to ensure correctness.
  </Accordion>

  <Accordion title="Booking Systems">
    Availability rules, conflict detection, and reservation logic benefit from explicit domain modeling.
  </Accordion>

  <Accordion title="Workflow Engines">
    State machines, transition rules, and approval chains require careful design.
  </Accordion>
</AccordionGroup>

***

## Simple Construction Bolt

<Card title="When to Use" icon="feather">
  Straightforward implementations that don't require extensive domain modeling.
</Card>

### Best For

* Frontend pages and components
* Simple CRUD endpoints
* External API integrations
* Utilities and helper modules
* CLI commands and scripts
* Configuration and setup code

### Stages

| Stage            | Purpose                   | Output                                        |
| ---------------- | ------------------------- | --------------------------------------------- |
| **1. Plan**      | Define what to build      | `implementation-plan.md`                      |
| **2. Implement** | Write the code            | Source code + `implementation-walkthrough.md` |
| **3. Test**      | Verify the implementation | Tests + `test-walkthrough.md`                 |

### Example Use Cases

<AccordionGroup>
  <Accordion title="User Profile Page">
    A React component displaying user information with edit capabilities. Clear requirements, no complex business logic.
  </Accordion>

  <Accordion title="REST API Integration">
    Connecting to a third-party API with well-documented endpoints. Focus on correct integration, not domain modeling.
  </Accordion>

  <Accordion title="Admin Dashboard">
    Data display and basic filtering. CRUD operations with straightforward UI.
  </Accordion>

  <Accordion title="CLI Tool">
    A command-line utility for common operations. Clear inputs and outputs.
  </Accordion>
</AccordionGroup>

***

## Comparison Table

| Aspect            | DDD Construction            | Simple Construction  |
| ----------------- | --------------------------- | -------------------- |
| **Stages**        | 5                           | 3                    |
| **Duration**      | Hours to days               | Hours                |
| **Documentation** | Extensive                   | Light                |
| **Design Rigor**  | High                        | Low                  |
| **Output**        | Production code + artifacts | Production code      |
| **Human Reviews** | 5 checkpoint reviews        | 3 checkpoint reviews |

## Common Mistakes

<Warning>
  Choosing the wrong bolt type leads to either over-engineering simple tasks or under-designing complex ones.
</Warning>

### Over-Engineering (DDD for Simple Tasks)

**Symptom**: Using DDD Construction for a simple settings page.

**Problem**: Excessive ceremony for straightforward work. Domain modeling for CRUD operations wastes time without adding value.

**Solution**: Use Simple Construction for UI, utilities, and integrations.

### Under-Engineering (Simple for Complex Tasks)

**Symptom**: Using Simple Construction for complex pricing logic.

**Problem**: Skipping domain modeling leads to implicit business rules scattered in code. Bugs emerge as edge cases are missed.

**Solution**: Use DDD Construction when business logic is non-trivial.

## Next Steps

<CardGroup>
  <Card title="Bolts Overview" icon="arrow-right" href="/core-concepts/bolts">
    Core concepts and bolt mechanics
  </Card>

  <Card title="Construction Agent" icon="hammer" href="/agents/construction-agent">
    Learn how the agent executes bolts
  </Card>
</CardGroup>


# Ideation Flow Overview
Source: https://specs.md/ideation-flow/overview

Creative brainstorming with Spark → Flame → Forge — from topic to polished concept brief in minutes

## What is Ideation Flow?

**Ideation Flow** is a research-backed creative brainstorming system that turns AI into a genuine creative partner. Give it a topic and get genuinely diverse ideas in 30 seconds—no setup, no technique selection, no friction.

<Info>
  **Invisible techniques, visible results.** Ideation applies SCAMPER, Six Thinking Hats, the Disney Creative Strategy, and more—you never see the method names, only the output they produce.
</Info>

```mermaid actions={false} theme={null}
flowchart LR
    T(Topic):::plan --> S(Spark):::warn --> F(Flame):::check --> G(Forge):::done
    S --> SB[(spark-bank.md)]:::warn
    F --> FR[(flame-report.md)]:::check
    G --> CB[(concept-brief.md)]:::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

## Key Differentiators

<CardGroup>
  <Card title="Zero Friction" icon="bolt">
    Topic → first 5 ideas in under 30 seconds. No configuration, no setup questions, no technique selection.
  </Card>

  <Card title="Anti-Bias Engine" icon="shuffle">
    12-domain wheel (Technology, Psychology, Business, Nature, Art, Games...) ensures genuine diversity—not AI's usual tech-heavy clustering.
  </Card>

  <Card title="Deep Thinking Per Batch" icon="brain">
    6-step reasoning chain before each idea batch: domain check, raw concepts, novelty filter, cross-pollination, provocation, polish.
  </Card>

  <Card title="Research-Backed Methods" icon="book">
    Synthesizes Osborn-Parnes CPS, de Bono's Six Hats, and Dilts' Disney Strategy. Methods are invisible—you get results, not methodology.
  </Card>

  <Card title="Adaptive Interaction" icon="sliders">
    AI/user ratio shifts by phase: Spark (80% AI), Flame (60% AI), Forge (40% AI). More co-creation as ideas get specific.
  </Card>

  <Card title="Beautiful Output" icon="file-lines">
    Polished Spark Bank, Flame Report, and Concept Brief documents—shareable in a meeting without editing.
  </Card>
</CardGroup>

## Three Skills

### Spark — Generate

Rapid divergent idea generation. AI produces batches of 5 ideas spanning multiple domains, tags each with the technique used (e.g., *via Inversion*), collects your reactions, and adapts.

* **Anti-bias**: min 3 different domains per batch, provocation every 15 ideas
* **Deep thinking**: 6-step reasoning before every batch
* **Output**: `spark-bank.md` grouped by theme with favorites highlighted

### Flame — Evaluate

Multi-perspective convergence using Six Hats. AI runs White/Yellow/Black/Green/Blue analysis per idea, then elicits your gut-feeling (Red Hat). Scores ideas on Impact × Feasibility and produces a shortlist of 3–5.

* **Six Hats**: facts, benefits, risks, alternatives, process, gut-feeling
* **Scoring**: 1–5 Impact × 1–5 Feasibility with 2×2 matrix view
* **Output**: `flame-report.md` with full evaluations, matrix, and shortlist

### Forge — Shape

Concept development using Disney's Creative Strategy (Dreamer → Realist → Critic). Co-build ratio increases per pass so you're deeply involved by the Critic phase.

* **Dreamer pass**: expand vision without limits (80% AI / 20% user)
* **Realist pass**: ground into practical implementation (60% AI / 40% user)
* **Critic pass**: stress-test, surface risks, co-develop mitigations (40% AI / 60% user)
* **Output**: one `concept-brief.md` per shortlisted idea

## When to Use Ideation Flow

<AccordionGroup>
  <Accordion title="You're starting a new feature and want novel angles">
    Before writing specs, run Ideation to explore the space. You might discover an approach you wouldn't have considered—or confirm your first instinct is actually the best one.
  </Accordion>

  <Accordion title="You're stuck in an echo chamber">
    The anti-bias engine deliberately pulls ideas from domains far outside your immediate domain. Nature, Games, Social, and Space perspectives unlock angles that pure tech brainstorming misses.
  </Accordion>

  <Accordion title="You want to run a product discovery session">
    Ideation sessions are resumable and produce polished artifacts. Run Spark with your team, Flame solo, and Forge with a stakeholder—the session state tracks where you left off.
  </Accordion>

  <Accordion title="You need a concept brief for a meeting">
    Forge produces a fully-structured concept brief with vision, implementation plan, and risks. No editing needed before sharing.
  </Accordion>

  <Accordion title="You want to stress-test an idea before committing">
    The Flame phase's Black Hat and Critic pass in Forge surface hidden risks and objections early—before you're invested in implementation.
  </Accordion>
</AccordionGroup>

## Session Structure

Ideation sessions are automatically persisted so you can pause and resume:

```
.specs-ideation/
└── sessions/
    └── {topic-slug}-{YYYYMMDD}/
        ├── session.yaml          # Phase, favorites, scores (resumable)
        ├── spark-bank.md         # All generated ideas, grouped by theme
        ├── flame-report.md       # Six Hats evaluations + shortlist
        └── concept-briefs/
            └── {concept-name}.md # One per shortlisted concept
```

## Get Started

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```

    Select **Ideation** when prompted for flow selection.
  </Step>

  <Step title="Start with a topic">
    ```
    /specsmd-ideation
    ```

    Type your topic or challenge. Ideas appear in under 30 seconds—no questions asked first.
  </Step>

  <Step title="React and iterate in Spark">
    Pick favorites, say "more like #3", "wilder", or "try a business angle". AI adapts each batch.
  </Step>

  <Step title="Evaluate with Flame">
    When you have enough ideas (suggested at \~50), transition to Flame for structured evaluation.
  </Step>

  <Step title="Shape concepts with Forge">
    Develop your top 3–5 ideas into polished Concept Briefs through the Dreamer → Realist → Critic process.
  </Step>
</Steps>

<Card title="Quick Start Guide" icon="rocket" href="/ideation-flow/quick-start">
  Step-by-step walkthrough of a complete ideation session
</Card>


# Ideation Flow Quick Start
Source: https://specs.md/ideation-flow/quick-start

Run a complete Spark → Flame → Forge session and produce a concept brief in minutes

## Prerequisites

* Node.js 18 or higher
* An AI coding tool: Claude Code, Cursor, GitHub Copilot, or Google Antigravity

## Installation

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Step>

  <Step title="Select Ideation flow">
    When prompted, choose **Ideation - Creative ideation: Spark → Flame → Forge**.
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    ls .specsmd/ideation/agents/
    ```

    You should see the orchestrator agent installed.
  </Step>
</Steps>

## Start a Session

Invoke the orchestrator with a topic, or jump directly to a skill:

<Tabs>
  <Tab title="Claude Code">
    ```
    /specsmd-ideation
    ```

    Type your topic. Example: *"new features for our developer onboarding experience"*
  </Tab>

  <Tab title="Cursor">
    Open Cursor chat and type:

    ```
    /specsmd-ideation
    ```

    Then describe your topic.
  </Tab>

  <Tab title="GitHub Copilot">
    In Copilot chat:

    ```
    @specsmd-ideation
    ```

    Then describe your topic.
  </Tab>
</Tabs>

<Info>
  **Zero friction start**: The orchestrator generates your first 5 ideas immediately—no setup questions. If a session already exists for your topic, it offers to resume where you left off.
</Info>

## Phase 1: Spark

The AI generates batches of 5 ideas spanning multiple domains. Each idea is tagged with the technique that produced it (e.g., *via Inversion*, *via SCAMPER*).

**Example output:**

```
Batch 1 — Developer Onboarding

1. **Contextual Code Sandbox** — Runnable snippets embedded directly in docs, pre-loaded with your team's actual API keys in a safe scope. *via First Principles*
2. **Buddy Bot Assignment** — Auto-pair each new hire with a Slack bot that monitors their questions and surfaces relevant internal docs proactively. *via Analogy*
3. **Anti-Onboarding Audit** — Have the new hire document every blocker they hit in week one; the team uses the list to fix the onboarding. *via Inversion*
4. **Onboarding Sprint** — Compress the full setup experience into a single pair-programming session with a senior engineer. *via Exaggeration*
5. **Experience Replay** — Record senior engineers' first week screens; new hires watch them before they start. *via Time Shift*
```

**How to react:**

| What you say                          | What happens                                   |
| ------------------------------------- | ---------------------------------------------- |
| `"more"` or `"next batch"`            | 5 more ideas, different domains                |
| `"more like #3"`                      | Next batch emphasizes that direction           |
| `"wilder"` or `"more unconventional"` | Increased provocation in next batch            |
| `"more practical"`                    | Next batch focuses on feasibility              |
| `"try a [domain] angle"`              | Adds that domain to next batch                 |
| `"favorite: 1, 3"`                    | Marks ideas for Spark Bank; carries into Flame |

<Info>
  **When to move on**: The AI suggests transitioning to Flame after \~50 ideas. You can transition earlier with "let's evaluate" or continue generating.
</Info>

**Output artifact**: When you're ready, the AI generates your `spark-bank.md` grouped by theme, with your favorites highlighted.

## Phase 2: Flame

Flame evaluates your ideas through multiple lenses. The AI runs a Six Hats rapid analysis on each idea from your Spark Bank, then asks for your gut feeling.

```mermaid actions={false} theme={null}
flowchart LR
    W(White Hat):::plan --> Y(Yellow Hat):::done --> B(Black Hat):::check --> G(Green Hat):::warn --> BL(Blue Hat):::plan --> R{{Red Hat}}:::check
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

| Hat             | Lens         | What it surfaces                               |
| --------------- | ------------ | ---------------------------------------------- |
| **White**       | Facts        | What do we know? What data exists?             |
| **Yellow**      | Benefits     | What's the best case? Why could this work?     |
| **Black**       | Risks        | What could go wrong? What are the obstacles?   |
| **Green**       | Alternatives | What variations exist? What else could we try? |
| **Blue**        | Process      | What's the path to implementation?             |
| **Red** *(you)* | Gut feeling  | Your instinct—no justification needed          |

**Red Hat is critical**: The AI explicitly elicits your gut feeling before finalizing the shortlist. Your instinct is a data point.

After the Six Hats analysis, the AI scores each idea on **Impact (1–5)** × **Feasibility (1–5)** and shows a 2×2 matrix. The shortlist (3–5 ideas) is selected from the upper-right quadrant, adjusted by your Red Hat input.

**Output artifact**: `flame-report.md` with full evaluations, scoring matrix, and shortlist with rationale.

## Phase 3: Forge

Forge develops each shortlisted idea into a polished Concept Brief using the Disney Creative Strategy.

```mermaid actions={false} theme={null}
flowchart LR
    D(Dreamer):::warn --> R(Realist):::plan --> C(Critic):::check --> B(Brief):::done
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

| Pass        | AI/You           | Focus                                                                         |
| ----------- | ---------------- | ----------------------------------------------------------------------------- |
| **Dreamer** | 80% AI / 20% you | Expand the vision without constraints. What's the best possible version?      |
| **Realist** | 60% AI / 40% you | Ground it. Tech stack, timeline, team. What does v1 actually look like?       |
| **Critic**  | 40% AI / 60% you | Stress-test it. What breaks? What are the real risks? Co-develop mitigations. |

The Critic pass is where you're most involved—you know the hidden constraints and organizational context that the AI doesn't.

**Output artifact**: One `concept-brief.md` per idea, containing:

* **Vision** (Dreamer output): Full concept, user value, differentiation
* **Implementation Plan** (Realist output): Phases, tech choices, resource needs
* **Risk Assessment** (Critic output): Risks ranked by severity, mitigations for each

## Resuming a Session

Sessions are automatically saved. If you close and return to an active session:

```
/specsmd-ideation
```

The orchestrator detects the existing session for your topic and offers to resume. All favorites, scores, and progress are preserved.

To start a fresh session on the same topic, say "new session" or use a more specific topic slug.

## Direct Skill Access

Skip the orchestrator and go straight to a skill:

| Command          | When to use                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `/specsmd-spark` | Jump directly to idea generation with a topic                             |
| `/specsmd-flame` | Evaluate ideas you already have (paste them in or reference a Spark Bank) |
| `/specsmd-forge` | Develop a specific idea into a concept brief directly                     |

## Command Reference

| Command             | Purpose                                                |
| ------------------- | ------------------------------------------------------ |
| `/specsmd-ideation` | Full flow — orchestrator routes based on session state |
| `/specsmd-spark`    | Direct idea generation                                 |
| `/specsmd-flame`    | Direct idea evaluation                                 |
| `/specsmd-forge`    | Direct concept shaping                                 |

## Tips for Success

<AccordionGroup>
  <Accordion title="Be specific with your topic">
    "Mobile app features" produces generic ideas. "Ways to reduce developer onboarding time from 2 weeks to 2 days" produces specific, actionable ones. The more constraint you add, the more surprising the output.
  </Accordion>

  <Accordion title="React to ideas, don't just say 'more'">
    The AI adapts based on your reactions. "More like #3 but applied to the mobile experience" directs the next batch precisely. Vague reactions produce generic follow-ups.
  </Accordion>

  <Accordion title="Don't skip the Red Hat in Flame">
    Gut feeling matters. An idea that scores well on impact/feasibility but gives you a bad feeling is worth examining. The Red Hat makes your instinct an explicit input.
  </Accordion>

  <Accordion title="Let the Critic pass be uncomfortable">
    The Critic phase is designed to surface real problems. Don't try to defend the idea—let the AI find the cracks. That's where the best mitigations come from.
  </Accordion>

  <Accordion title="Use standards for context-aware ideation">
    If your project has standards in `.specs-ideation/standards/`, the orchestrator uses them for context. Tech-specific ideas will align with your actual stack.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Ideas feel too similar or too technical">
    The anti-bias engine enforces domain diversity, but if you're in a STEM-heavy session context it may lean technical. Say "try a social or psychological angle" to explicitly shift. Or "wilder"—the provocation engine kicks in and forces non-obvious directions.
  </Accordion>

  <Accordion title="Session didn't resume from where I left off">
    Check `.specs-ideation/sessions/` for your session folder. If `session.yaml` exists, the orchestrator should detect it. Try: `/specsmd-ideation` and explicitly mention your topic slug.
  </Accordion>

  <Accordion title="Concept brief feels too generic">
    The Forge pass quality scales with your involvement in the Critic phase. Push back, add organizational context, surface hidden constraints. The more specific your input, the more specific the brief.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Skills Deep Dive" icon="list-check" href="/ideation-flow/skills">
    Detailed configuration and behavior for Spark, Flame, and Forge
  </Card>

  <Card title="Flow Overview" icon="compass" href="/ideation-flow/overview">
    Architecture, key principles, and when to use Ideation
  </Card>

  <Card title="Compare Flows" icon="arrows-left-right" href="/architecture/choose-flow">
    When to use Ideation vs Simple vs FIRE vs AI-DLC
  </Card>

  <Card title="Installation" icon="download" href="/getting-started/installation">
    Full installation guide for all AI tools
  </Card>
</CardGroup>


# Ideation Skills: Spark, Flame, Forge
Source: https://specs.md/ideation-flow/skills

Deep dive into the three Ideation skills — configuration, behavior, and output artifacts

## Three Skills, One Flow

Ideation Flow has a single orchestrator agent that routes between three skills based on session state. Each skill can also be invoked directly.

```mermaid actions={false} theme={null}
flowchart TB
    O(Orchestrator):::plan --> S(Spark):::warn
    O --> F(Flame):::check
    O --> G(Forge):::done
    S --> SB[(spark-bank.md)]:::warn
    F --> FR[(flame-report.md)]:::check
    G --> CB[(concept-brief.md)]:::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

***

## Spark Skill

**Goal**: Generate genuinely diverse, surprising ideas through rapid batches with maximum divergence.

### How It Works

Before every batch, Spark executes a **6-step deep thinking chain**:

| Step    | Name            | What Happens                                            |
| ------- | --------------- | ------------------------------------------------------- |
| Think 1 | Domain Check    | Which domains haven't been used yet this session?       |
| Think 2 | Raw Concepts    | Generate 10–15 unfiltered raw concepts                  |
| Think 3 | Novelty Filter  | Remove ideas that are obvious or already covered        |
| Think 4 | Cross-Pollinate | Combine concepts from different domains                 |
| Think 5 | Provocation     | If due (every 15 ideas), force a deliberate provocation |
| Think 6 | Polish          | Refine to 5 ideas with clear technique tags             |

<Info>
  **Deep thinking is collapsed by default.** You see the final 5 ideas, not the reasoning chain. Set visibility to `visible` in `memory-bank.yaml` if you want to watch the reasoning.
</Info>

### Anti-Bias Engine

The **12-domain wheel** enforces cognitive diversity across every session:

<CardGroup>
  <Card title="Technology / Engineering" icon="microchip" />

  <Card title="Human Psychology / Behavior" icon="brain" />

  <Card title="Business / Economics" icon="chart-line" />

  <Card title="Nature / Biology" icon="leaf" />

  <Card title="Art / Design / Aesthetics" icon="palette" />

  <Card title="Games / Play" icon="gamepad" />

  <Card title="Social / Community" icon="people-group" />

  <Card title="Physical Space / Architecture" icon="building" />

  <Card title="Time / Temporal" icon="clock" />

  <Card title="Extreme / Edge Cases" icon="triangle-exclamation" />

  <Card title="Inversion / Opposite" icon="rotate" />

  <Card title="Random Cross-Pollination" icon="shuffle" />
</CardGroup>

**Diversity rules enforced per batch:**

* Minimum 3 different domains in every batch of 5
* No consecutive ideas from the same domain
* Session-level tracking prevents clustering around familiar themes

**Provocation cadence:**

* Every 15 ideas: a deliberate provocation (Inversion, Exaggeration, Elimination, Time Shift, Stakeholder Swap, or Random)
* Every 20 ideas: a full perspective shift to a distant domain

### Configuration (`memory-bank.yaml`)

```yaml theme={null}
spark:
  batch_size: 5          # Ideas per batch
  target_count: 50       # Suggested convergence threshold
  max_batches: 20        # Safety limit

anti_bias:
  domain_diversity_min: 3       # Minimum domains per batch
  provocation_frequency: 15     # Provocation every N ideas
  perspective_shift_frequency: 20

deep_thinking:
  prefer_mcp: true              # Use Sequential Thinking MCP if available
  fallback: built-in
  steps_per_batch: 6
  visibility: collapsed         # visible | collapsed | hidden
```

### Spark Bank Output

The Spark Bank is a structured markdown document grouping all ideas by theme, with favorites highlighted:

```
# Spark Bank: Developer Onboarding

## Summary
- Total ideas: 47
- Favorites: 8
- Domains covered: 9/12

## Theme: Friction Reduction
⭐ **Contextual Code Sandbox** — Runnable snippets in docs, pre-loaded with your API keys in a safe scope. *via First Principles*
**Onboarding Sprint** — Full setup compressed into one pair-programming session. *via Exaggeration*

## Theme: Knowledge Transfer
⭐ **Buddy Bot Assignment** — Slack bot that surfaces relevant internal docs as the new hire encounters gaps. *via Analogy*
...
```

***

## Flame Skill

**Goal**: Evaluate ideas fairly through multiple perspectives—surface hidden value, expose real risks, produce a ranked shortlist.

### Six Hats Analysis

For each idea, Flame runs all five objective hats automatically (no interruption), then explicitly elicits the Red Hat from you:

| Hat             | Color      | Lens                                              |
| --------------- | ---------- | ------------------------------------------------- |
| **White**       | Facts      | What data exists? What don't we know?             |
| **Yellow**      | Optimism   | What's the best case? Why could this succeed?     |
| **Black**       | Caution    | What could fail? What are the real obstacles?     |
| **Green**       | Creativity | What variations exist? What else could we do?     |
| **Blue**        | Process    | What's the implementation path? What comes first? |
| **Red** *(you)* | Intuition  | Your gut feeling — no justification required      |

<Info>
  **Red Hat is a deliberate pause.** Before producing the shortlist, Flame asks for your gut reaction on each idea. This captures organizational knowledge, personal context, and instinct that the objective hats can't surface.
</Info>

### Scoring

After the Six Hats analysis, each idea is scored:

| Axis            | Scale | What It Measures              |
| --------------- | ----- | ----------------------------- |
| **Impact**      | 1–5   | Potential value if it works   |
| **Feasibility** | 1–5   | Realistic chance of execution |

Ideas are plotted on a 2×2 matrix (Impact × Feasibility). The shortlist (3–5 ideas) defaults to the upper-right quadrant, adjusted by your Red Hat input.

### Configuration

```yaml theme={null}
flame:
  default_method: six-hats-rapid
  shortlist_size: 5
```

### Flame Report Output

```
# Flame Report: Developer Onboarding

## Evaluations

### Contextual Code Sandbox
- **White**: No direct competitor data; internal tooling exists
- **Yellow**: Eliminates "it works on my machine" problem permanently
- **Black**: API key management complexity; security review needed
- **Green**: Could extend to full environment snapshots
- **Blue**: Phase 1: static sandbox → Phase 2: live environment
- **Red** *(your input)*: "Strong gut feel — this is the one"
- **Score**: Impact 5, Feasibility 3

## Scoring Matrix
[2×2 matrix: Impact × Feasibility]

## Shortlist (Top 5)
1. Contextual Code Sandbox (I:5, F:3) ← your Red Hat favorite
2. Buddy Bot Assignment (I:4, F:4)
...
```

***

## Forge Skill

**Goal**: Develop shortlisted ideas into polished, actionable Concept Briefs using the Disney Creative Strategy.

### Disney Creative Strategy

Robert Dilts' model separates three distinct thinking modes that must not mix:

```mermaid actions={false} theme={null}
flowchart LR
    D("Dreamer\n(Vision)"):::warn --> R("Realist\n(Plan)"):::plan --> C("Critic\n(Risk)"):::check --> B("Concept Brief"):::done
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

<Warning>
  **Passes must not mix.** The Dreamer phase has no constraints—introducing feasibility concerns here kills creative thinking. The Realist phase grounds the vision—don't critique here. The Critic phase is where stress-testing happens.
</Warning>

### Pass Details

**Dreamer Pass (80% AI / 20% you)**

Expand the vision without limits. What is the best possible version of this idea?

* Full concept description
* User value proposition
* Differentiation angle
* The "dream" experience

**Realist Pass (60% AI / 40% you)**

Ground the vision in reality. What does v1 actually look like?

* Technology choices
* Implementation phases (v1, v2, v3)
* Team and time requirements
* Integration points

**Critic Pass (40% AI / 60% you)**

Stress-test the concept. This is where your organizational context matters most.

* Risks ranked by severity (Critical / High / Medium / Low)
* Mitigations for each risk
* Known organizational constraints
* "What would make this fail?"

<Info>
  **You are most involved in the Critic pass.** The AI surfaces generic risks; you add the real organizational blockers, political constraints, and hidden dependencies that only you know about.
</Info>

### Configuration

```yaml theme={null}
forge:
  default_method: disney-strategy
  include_pitch: true
  include_risks: true
```

### Concept Brief Output

```markdown theme={null}
# Concept Brief: Contextual Code Sandbox

## Vision (Dreamer)
A fully-functional development environment embedded in documentation.
New hires run real code against real APIs on day one—no local setup required.
The "first day works" experience becomes the default, not the exception.

## Implementation Plan (Realist)
**Phase 1 (2 weeks)**: Static sandbox with pre-loaded API credentials in isolated scope
**Phase 2 (4 weeks)**: Full environment snapshots tied to specific onboarding paths
**Phase 3 (ongoing)**: Self-updating sandboxes that mirror production changes

Tech: WebContainers (StackBlitz), credential vault integration, Markdown MDX

## Risk Assessment (Critic)
| Risk | Severity | Mitigation |
|------|----------|-----------|
| Security review for credential scoping | Critical | Dedicated security review sprint before Phase 1 |
| Engineering buy-in for maintenance | High | Async RFC + demo with early adopters |
| Browser compatibility for WebContainers | Medium | Fallback to static code blocks with copy button |
```

***

## Session State

All session data is persisted in `session.yaml`:

```yaml theme={null}
session:
  id: developer-onboarding-20260528
  topic: "Reduce developer onboarding from 2 weeks to 2 days"
  created: 2026-05-28T09:00:00Z
  updated: 2026-05-28T14:30:00Z
  phase: forge

spark:
  batches_generated: 9
  total_ideas: 47
  favorites: [S1-1, S2-3, S4-2, S5-1, S6-4, S7-2, S8-1, S8-5]
  domains_used: [Technology, Psychology, Business, Nature, Games, Social, Space, Inversion]
  domains_remaining: [Art, Time, Extreme, Random]

flame:
  ideas_evaluated: 12
  shortlist: [S1-1, S2-3, S4-2, S5-1, S7-2]
  scoring_method: six-hats-rapid

forge:
  concepts_shaped: 2
  briefs_generated: [contextual-code-sandbox.md, buddy-bot-assignment.md]
```

***

## Interaction Adaptation

The AI adjusts its interaction style based on the current skill phase:

| Phase     | Generate | Elicit | Co-Build |
| --------- | -------- | ------ | -------- |
| **Spark** | 80%      | 5%     | 15%      |
| **Flame** | 60%      | 15%    | 25%      |
| **Forge** | 40%      | 20%    | 40%      |

**Override signals:**

* `"you decide"` → shifts toward more generation
* `"ask me"` → shifts toward more elicitation

**Hard rule**: Never more than 2 questions before generating output. Flow never stalls.


# Introduction
Source: https://specs.md/index

AI-native development framework with four flows for every use case

<img alt="specs.md Framework Architecture" />

<img alt="specs.md Framework Architecture" />

## What is specs.md?

**specs.md** is an AI-native development framework with pluggable flows for every use case. Choose the flow that matches your project needs:

<CardGroup>
  <Card title="Ideation Flow" icon="lightbulb" href="/ideation-flow/overview">
    **Creative brainstorming**. Spark → Flame → Forge ideas into concept briefs.
  </Card>

  <Card title="Simple Flow" icon="feather" href="/simple-flow/overview">
    **Spec generation only**. Quick requirements, design, and task documents.
  </Card>

  <Card title="FIRE Flow" icon="bolt" href="/fire-flow/overview">
    **Adaptive execution**. Right-sizes the rigor, brownfield & monorepo ready.
  </Card>

  <Card title="AI-DLC Flow" icon="building" href="/core-concepts/intents">
    **Full methodology**. Complete lifecycle with DDD and 4 agents.
  </Card>
</CardGroup>

<Info>
  **Not sure which flow?** Check out our [Choose Your Flow](/architecture/choose-flow) guide for a detailed comparison.
</Info>

## Quick Start

<CardGroup>
  <Card title="Installation" icon="download" href="/getting-started/installation">
    Install specs.md and select your flow
  </Card>

  <Card title="IDE Extension" icon="puzzle-piece" href="/getting-started/ide-extension">
    Track progress with the VS Code extension
  </Card>
</CardGroup>

## Framework Architecture

specs.md is built as a **pluggable framework** where development methodologies are implemented as **flows**:

```
specs.md (Framework)
├── Core (Standards, Agents, State)
└── Flows/
    ├── ideation/   ← Creative brainstorming (Spark → Flame → Forge)
    ├── simple/     ← Spec generation only
    ├── fire/       ← Rapid execution (0-2 checkpoints)
    └── aidlc/      ← Full methodology with DDD
```

## Key Features

<AccordionGroup>
  <Accordion title="Four Flows for Every Use Case">
    **Ideation** for creative brainstorming, **Simple** for quick specs, **FIRE** for rapid execution, **AI-DLC** for full methodology. Choose based on your project needs.
  </Accordion>

  <Accordion title="Creative Ideation (Ideation Flow)">
    Spark → Flame → Forge. AI generates diverse ideas using 12 domains, evaluates them through multiple lenses, then shapes top picks into polished concept briefs—before you commit to writing specs.
  </Accordion>

  <Accordion title="Adaptive Checkpoints (FIRE)">
    FIRE flow adapts oversight to complexity: 0 checkpoints for simple tasks, 1 for standard features, 2 for critical changes.
  </Accordion>

  <Accordion title="First-Class Brownfield Support (FIRE)">
    Auto-detects existing patterns, respects conventions, and extends rather than rewrites your codebase.
  </Accordion>

  <Accordion title="Monorepo Support (FIRE)">
    Hierarchical standards with module-specific overrides. One project, multiple tech stacks.
  </Accordion>

  <Accordion title="Full DDD Methodology (AI-DLC)">
    Domain-Driven Design is integral to AI-DLC Construction phase for complex domains.
  </Accordion>

  <Accordion title="Tool Agnostic">
    Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
  </Accordion>

  <Accordion title="VS Code Extension">
    Track your progress with our [sidebar extension](/getting-started/ide-extension) for VS Code, Cursor, and Windsurf. Monitor progress, browse specs, and view project metrics visually.
  </Accordion>
</AccordionGroup>

## Flow Comparison

| Aspect                 | Ideation             | Simple          | FIRE                           | AI-DLC             |
| ---------------------- | -------------------- | --------------- | ------------------------------ | ------------------ |
| **Optimized For**      | Creative exploration | Spec generation | Adaptive execution             | Full traceability  |
| **Checkpoints**        | 0 (non-blocking)     | 3 (phase gates) | Adaptive (complexity + config) | Comprehensive      |
| **Agents**             | 1                    | 1               | 3                              | 4                  |
| **Execution Tracking** | No                   | No              | Yes                            | Yes                |
| **Design Docs**        | Concept briefs       | Basic           | When complexity warrants       | DDD or Simple bolt |
| **Monorepo**           | No                   | No              | First-class                    | Limited            |

## Supported Tools

specs.md is **IDE and AI-agnostic**—you choose your tools, no vendor lock-in.

<CardGroup>
  <Card title="Claude Code" icon="terminal">
    Slash commands
  </Card>

  <Card title="Cursor" icon="code">
    Rules integration
  </Card>

  <Card title="GitHub Copilot" icon="github">
    Agents support
  </Card>

  <Card title="Windsurf" icon="wind">
    Rules integration
  </Card>

  <Card title="Cline" icon="robot">
    Rules integration
  </Card>

  <Card title="Roo" icon="paw">
    Rules integration
  </Card>

  <Card title="Kiro" icon="aws">
    Agents support
  </Card>

  <Card title="Google Antigravity" icon="google">
    Agents support
  </Card>

  <Card title="Gemini CLI" icon="sparkles">
    Agents support
  </Card>

  <Card title="Codex CLI" icon="microchip">
    Agents support
  </Card>

  <Card title="OpenCode" icon="code-branch">
    Agents support
  </Card>
</CardGroup>

<Info>
  Unlike tools that lock you into a specific paid IDE, specs.md works with **any AI coding tool**. Your specs and agents are portable markdown files that work everywhere.
</Info>

## Get Started

<Steps>
  <Step title="Install specs.md">
    ```bash theme={null}
    npx specsmd@latest install
    ```
  </Step>

  <Step title="Select your flow">
    Choose **Ideation**, **Simple**, **FIRE**, or **AI-DLC** based on your project needs
  </Step>

  <Step title="Start building">
    Invoke your flow's agent and describe what you want to build
  </Step>
</Steps>

## Why specs.md?

Traditional development methods were built for human-driven, long-running processes. **specs.md reimagines the development lifecycle** with AI as a central collaborator:

* **Choose your overhead**: From creative brainstorming (Ideation) and no execution tracking (Simple) to full methodology (AI-DLC)
* **Start before specs**: Ideation explores the solution space and produces concept briefs—before you commit to writing requirements
* **Adaptive checkpoints**: FIRE adapts oversight to complexity—skip ceremony for simple tasks
* **Brownfield-first**: FIRE auto-detects existing patterns and conventions
* **Persistent context**: AI can reference across sessions with structured artifacts
* **Rapid cycles**: Ship features in hours, not weeks

<Info>
  **Featured on Product Hunt!** Check out our launch and leave a review: [specs.md on Product Hunt →](https://www.producthunt.com/products/specs-md)
</Info>


# AI-DLC Bolt Execution
Source: https://specs.md/learn/aidlc-bolt-execution

Watch how to execute bolts with AI-DLC agents

## AI-DLC: Bolt Execution

Interacting with AI-DLC agents to execute a bolt. Choose the speed-up version for a quick overview or the full-length version to follow along.

<Note>
  These videos currently have **no audio** - screen recording walkthroughs.
</Note>

<Tabs>
  <Tab title="Speed-up (3 min)">
    <iframe title="AI-DLC Bolt Execution (Speed-up)" />
  </Tab>

  <Tab title="Full-length">
    <iframe title="AI-DLC Bolt Execution (Full-length)" />
  </Tab>
</Tabs>

***

## What You'll See

* Starting a bolt with AI-DLC agents
* VS Code extension tracking bolt progress
* Stage progression and validation
* Agent interactions throughout execution

***

## Related Resources

<CardGroup>
  <Card title="AI-DLC Overview" icon="building" href="/aidlc/overview">
    Learn about AI-DLC methodology
  </Card>

  <Card title="Construction Agent" icon="hammer" href="/agents/construction-agent">
    Agent that executes bolts
  </Card>
</CardGroup>


# Getting Started with FIRE Flow
Source: https://specs.md/learn/fire-flow-intro

Watch how to set up a project with FIRE Flow and use the VS Code extension

## Getting Started with FIRE Flow

<Note>
  This video currently has **no audio** - it's a screen recording walkthrough. I'm working on adding narration in future updates.
</Note>

<iframe title="Getting Started with FIRE Flow" />

***

## What You'll See

* Setting up a new project with specsmd
* Creating intents and work items
* Running through the execution flow
* Using the VS Code extension sidebar

***

## Related Resources

<CardGroup>
  <Card title="FIRE Flow Overview" icon="bolt" href="/fire-flow/overview">
    Learn about FIRE Flow concepts
  </Card>

  <Card title="FIRE Flow Quick Start" icon="rocket" href="/fire-flow/quick-start">
    Written quick start guide
  </Card>
</CardGroup>


# FIRE Flow: Resume a Run
Source: https://specs.md/learn/fire-flow-resume-run

Resume a FIRE flow run and watch the VS Code extension update in real-time while building fabriqa.ai

## FIRE Flow: Resume a Run

Building [fabriqa.ai](https://fabriqa.ai) with specs.md — resume a run on specs.md FIRE flow and watch the VS Code extension get updated.

<Note>
  This video currently has **no audio** - it's a screen recording walkthrough.
</Note>

<iframe title="Resume a run on specs.md FIRE flow while building fabriqa.ai" />

***

## What You'll See

* Resuming a FIRE flow run mid-progress
* VS Code extension sidebar updating in real-time
* Work item phase tracking during execution
* Building a real project (fabriqa.ai) with specs.md

***

## Related Resources

<CardGroup>
  <Card title="FIRE Flow Overview" icon="bolt" href="/fire-flow/overview">
    Learn about FIRE Flow concepts
  </Card>

  <Card title="IDE Extension" icon="puzzle-piece" href="/getting-started/ide-extension">
    Set up the VS Code extension
  </Card>
</CardGroup>


# Video Tutorials
Source: https://specs.md/learn/index

Watch specsmd in action with step-by-step video walkthroughs

## Learn specsmd

Watch specsmd in action through our video tutorial series. These walkthroughs demonstrate real-world usage of the framework and IDE extension.

<Info>
  This is our growing video library. More tutorials are being added regularly. Subscribe to our [YouTube channel](https://www.youtube.com/@specs-md) to get notified when new videos are released.
</Info>

***

## Available Videos

<CardGroup>
  <Card title="Getting Started with FIRE Flow" icon="bolt" href="/learn/fire-flow-intro">
    Project setup, intents, work items, and VS Code extension
  </Card>

  <Card title="FIRE Flow: Resume a Run" icon="play" href="/learn/fire-flow-resume-run">
    Resume a FIRE flow run and watch the VS Code extension update live
  </Card>

  <Card title="AI-DLC: Bolt Execution" icon="hammer" href="/learn/aidlc-bolt-execution">
    Executing bolts with AI-DLC agents
  </Card>

  <Card title="CLI and Web Dashboard Tutorials" icon="chart-line" href="/learn/specs-md-dashboard">
    Track progress from Chrome, Fabriqa.AI, or the terminal beside Codex
  </Card>

  <Card title="Using specsmd in Fabriqa" icon="layer-group" href="/learn/specsmd-in-fabriqa">
    Set up and run specsmd workflows within the Fabriqa platform
  </Card>
</CardGroup>

***

## Coming Soon

We're working on more video content covering:

* **Full End-to-End Workflows** - Complete project lifecycle from intent to deployment
* **Monorepo Setup** - Managing multiple modules
* **Standards Configuration** - Setting up tech stack and coding standards
* **Advanced Workflows** - Dependencies, batch runs, and more

<CardGroup>
  <Card title="Request a Tutorial" icon="lightbulb" href="https://github.com/fabriqaai/specs.md/discussions">
    Have a topic you'd like covered? Let us know!
  </Card>

  <Card title="Documentation" icon="book" href="/getting-started/installation">
    Prefer reading? Check out our written guides
  </Card>
</CardGroup>


# CLI and Web Dashboard Tutorials
Source: https://specs.md/learn/specs-md-dashboard

Watch how to use the specs.md terminal dashboard with Codex Desktop App and the web dashboard from Chrome or Fabriqa.AI

## CLI and Web Dashboard Tutorials

Use the specs.md dashboards to monitor your local spec-driven work without living inside VS Code. The terminal dashboard is useful next to Codex Desktop App, while the web dashboard gives you the same visual planning surface from Chrome or a browser opened through Fabriqa.AI.

***

## Web Dashboard from Any Browser

Run the dashboard from your project folder, then open the local URL in Chrome, another browser, or from Fabriqa.AI when you want a browser-based view of the same local specs state.

```bash theme={null}
npx specsmd@latest dashboard
```

The web dashboard reads your local `memory-bank`, `.specs-fire`, or `specs` folder, opens on `127.0.0.1`, and updates while agents change the project state.

<iframe title="Using the specs.md web dashboard from Chrome and Fabriqa.AI" />

### What You'll See

* Starting the local web dashboard with `npx specsmd@latest dashboard`
* Opening the dashboard from Chrome or another browser
* Using the dashboard from Fabriqa.AI while your specs stay in the local project folder
* Browsing runs, specs, intents, and progress outside VS Code

***

## CLI Dashboard with Codex Desktop App

Use the specs.md terminal dashboard to track progress while building with Codex Desktop App.

<Note>
  This video currently has **no audio** - it's a screen recording walkthrough.
</Note>

<iframe title="using specs.md CLI Dashboard to track progress while building with Codex Desktop App" />

### What You'll See

* Using the specs.md CLI Dashboard to monitor build progress
* Tracking work items and execution status in real-time
* Building with the Codex Desktop App alongside specs.md

***

## Related Resources

<CardGroup>
  <Card title="Dashboard" icon="chart-line" href="/getting-started/specs-md-dashboard">
    Web and terminal dashboard commands, options, and screenshots
  </Card>

  <Card title="FIRE Flow Overview" icon="bolt" href="/fire-flow/overview">
    Learn about FIRE Flow concepts
  </Card>

  <Card title="Documentation" icon="book" href="/getting-started/installation">
    Written getting started guide
  </Card>
</CardGroup>


# Using specsmd in Fabriqa
Source: https://specs.md/learn/specsmd-in-fabriqa

Watch how to use specsmd within the Fabriqa orchestration platform

## Using specsmd in Fabriqa

<Note>
  This video currently has **no audio** - it's a screen recording walkthrough.
</Note>

<iframe title="Using specsmd in Fabriqa" />

***

## What You'll See

* Setting up specsmd within the Fabriqa platform
* Configuring and running spec-driven workflows
* Using Fabriqa to orchestrate specsmd with AI coding agents

***

## Related Resources

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/getting-started/installation">
    Install specsmd and set up your first project
  </Card>

  <Card title="Fabriqa" icon="layer-group" href="https://fabriqa.ai?utm_source=specsmd">
    Learn more about the Fabriqa orchestration platform
  </Card>
</CardGroup>


# AI-DLC vs Agile
Source: https://specs.md/methodology/ai-dlc-vs-agile

How AI-DLC compares to traditional Agile methods

## Side-by-Side Comparison

| Aspect                  | Agile/Scrum                    | AI-DLC                                 |
| ----------------------- | ------------------------------ | -------------------------------------- |
| **Iteration Duration**  | Weeks (Sprints)                | Hours/Days (Bolts)                     |
| **Who Drives**          | Human-driven, AI assists       | AI-driven, human-validated             |
| **Design Techniques**   | Out of scope                   | Integrated (DDD in construction bolts) |
| **Task Decomposition**  | Manual                         | AI-powered                             |
| **Phases**              | Repeating sprints              | Rapid three-phase cycles               |
| **Rituals**             | Daily standups, retrospectives | Mob Elaboration, Mob Construction      |
| **Documentation**       | Often neglected                | Built-in artifacts                     |
| **Context Engineering** | Lost between sprints           | Specs + Memory Bank                    |

## Iteration: Sprints vs Bolts

<Tabs>
  <Tab title="Agile Sprints">
    * **Duration**: 1-4 weeks
    * **Planning**: Sprint planning ceremony
    * **Execution**: Daily standups, continuous work
    * **Review**: Sprint review, retrospective
    * **Output**: Potentially shippable increment
  </Tab>

  <Tab title="AI-DLC Bolts">
    * **Duration**: Hours to days
    * **Planning**: AI-powered decomposition
    * **Execution**: Stage-gated progression
    * **Review**: Human validation at each checkpoint
    * **Output**: Validated, tested feature
  </Tab>
</Tabs>

## Role Inversion

### Traditional Agile

```mermaid actions={false} theme={null}
flowchart LR
    H1(Human):::plan --> P(Plans):::plan --> H2(Human):::plan --> E(Executes):::plan --> AI(AI assists):::build
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
```

Humans drive the entire process. AI tools (copilots, assistants) help with specific tasks but don't lead.

### AI-DLC

```mermaid actions={false} theme={null}
flowchart LR
    H1(Human):::plan --> I(Defines Intent):::plan --> AI1(AI Proposes):::done --> H2(Human Validates):::check --> AI2(AI Executes):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

AI leads the conversation. Humans provide intent and validation. AI handles decomposition, planning, and execution.

## Design Techniques

<CardGroup>
  <Card title="Agile Approach" icon="question">
    Design techniques like DDD are optional. Many teams skip them due to time pressure, leading to technical debt.
  </Card>

  <Card title="AI-DLC Approach" icon="check">
    Domain-Driven Design is built into DDD construction bolts. You can't skip Domain Modeling - it's a required gate.
  </Card>
</CardGroup>

## Bolt Types with Built-in Design

| Bolt Type               | Best For                             | Stages                                  |
| ----------------------- | ------------------------------------ | --------------------------------------- |
| **DDD Construction**    | Complex domain logic, business rules | Model → Design → ADR → Implement → Test |
| **Simple Construction** | UI, integrations, utilities          | Plan → Implement → Test                 |

## Context Engineering

<Warning>
  One of the biggest challenges in traditional Agile is context loss between sprints. Knowledge leaves with team members, decisions aren't documented, and the codebase becomes a mystery.
</Warning>

### AI-DLC Solution: Specs + Memory Bank

Specs and Memory Bank provide structured context for AI agents:

* All project artifacts (requirements, designs, decisions)
* Traceability between artifacts
* Context that agents can reload in any session

```
memory-bank/
├── intents/           # What we're building
├── bolts/             # How we built it
├── standards/         # Project decisions
└── operations/        # Deployment context
```

## When to Use Each

<Tabs>
  <Tab title="Use Agile When">
    * Team is not using AI coding tools
    * Organization has established Agile processes
    * Regulatory requirements mandate specific ceremonies
    * Team prefers human-led planning
  </Tab>

  <Tab title="Use AI-DLC When">
    * Building with AI coding assistants
    * Need rapid iteration cycles
    * Want integrated design practices
    * Building complex systems
    * Context persistence is critical
  </Tab>
</Tabs>

## Migration Path

AI-DLC retains familiar concepts to ease transition:

| Agile Concept      | AI-DLC Equivalent       |
| ------------------ | ----------------------- |
| Epic               | Intent                  |
| User Story         | Story (within Unit)     |
| Sprint             | Bolt                    |
| Backlog            | Intent/Unit definitions |
| Definition of Done | Checkpoint validations  |


# The AI-Native SDLC: Reimagined
Source: https://specs.md/methodology/sdlc-reimagined

Why the Agentic Age demands a new methodology—and why retrofitting AI into Agile delivery frameworks doesn't work.

## The End of "Faster Horse Chariots"

For decades, software development methodologies evolved incrementally. Waterfall gave way to Agile delivery frameworks like Scrum. Sprints replaced long release cycles. Story points replaced time estimates. Each iteration made us marginally faster.

<Note>
  Throughout this page, "Agile" refers to Agile delivery frameworks and process implementations such as Scrum and related practices, not the values and principles of the Agile Manifesto.
</Note>

Then AI arrived—and broke the entire model.

<Info>
  **"Retrofitting AI into existing methods not only limits its potential, but also reinforces outdated inefficiencies. To fully leverage AI's transformative power, SDLC methods need to be reimagined."**

  — [AWS AI-DLC Whitepaper](https://github.com/fabriqaai/specsmd/blob/main/resources/aidlc.pdf)
</Info>

We don't need faster horse chariots. We need automobiles.

***

## Three Eras of AI in Development

| Era                         | Human Role                | AI Role                         | Paradigm                    |
| --------------------------- | ------------------------- | ------------------------------- | --------------------------- |
| **AI-Assisted** (2020-2023) | Primary creator           | Autocomplete, suggestions       | Human drives, AI helps      |
| **AI-Driven** (2023-2025)   | Validator, decision-maker | Generates code, plans, tests    | AI proposes, human approves |
| **Agentic** (2025+)         | Supervisor, architect     | Autonomous multi-step execution | AI executes, human oversees |

We're now in the **Agentic Age**—where AI agents don't just assist; they autonomously plan, reason, and execute complex workflows.

This isn't a minor upgrade. It's a paradigm shift that renders traditional methodologies obsolete.

***

## Why Sprints Don't Work Anymore

### Two Weeks Is No Longer Fast

<Warning>
  AI-enabled development produces working prototypes in hours. A two-week sprint is not rapid iteration—it's an artificial delay that queues work behind an arbitrary time boundary.
</Warning>

When concept-to-working-code happens in an afternoon, waiting twelve more days for a sprint boundary serves no purpose except ceremony compliance.

### The Cost of Code Has Collapsed

Agile delivery frameworks assumed producing code was expensive because human effort was expensive. The methodology optimized for producing *less code more carefully*.

AI inverted this assumption. Code generation now costs minutes, not days.

### Estimation Becomes Meaningless

| Traditional Metric  | Problem in AI Era                                                          |
| ------------------- | -------------------------------------------------------------------------- |
| **Story Points**    | AI execution time bears no relation to human effort estimates              |
| **Velocity**        | Fluctuates wildly based on AI tool usage, not team capability              |
| **Sprint Planning** | Creates artificial delays for completed work waiting for ceremonies        |
| **Daily Standups**  | Consume time sharing information automated systems could surface instantly |

<Info>
  **"Would effort estimation (story points) be as critical if AI diminishes the boundaries between simple, medium, and hard tasks? Would metrics like velocity be relevant, or should we replace it with Business Value?"**

  — AWS AI-DLC Whitepaper
</Info>

***

## The V-Bounce Model: Humans as Validators

The [V-Bounce paper](https://arxiv.org/abs/2408.03416) from Crowdbotics introduced a foundational insight:

<Card title="Core Insight" icon="lightbulb">
  **The role of humans shifts from primary implementers to validators and verifiers.**
</Card>

### Traditional V-Model vs V-Bounce

| Aspect                   | Traditional V-Model        | V-Bounce                                            |
| ------------------------ | -------------------------- | --------------------------------------------------- |
| **Implementation Phase** | Substantial (weeks/months) | Drastically reduced (hours/days)                    |
| **Human Role**           | Hands-on coding            | Validation and verification                         |
| **Emphasis**             | Code production            | Requirements + Architecture + Continuous validation |
| **AI Role**              | None/minimal               | End-to-end: planning → code → tests → maintenance   |

### Three Core Assumptions

<Steps>
  <Step title="Near-Instantaneous Code Generation">
    LLMs enable rapid generation of high-quality code
  </Step>

  <Step title="Natural Language as Primary Interface">
    Programming is becoming language-driven
  </Step>

  <Step title="Humans as Verifiers">
    Human roles shift from creators to sophisticated validators
  </Step>
</Steps>

### Empirical Results

* **55.8%** faster task completion with AI tools (GitHub Copilot study)
* **70%+** efficiency in generating test suites with AI
* Enhanced early bug detection and overall software quality

***

## AI-DLC: The Methodology for the Agentic Age

AWS's **AI-Driven Development Lifecycle (AI-DLC)** takes these insights and builds a complete, production-ready methodology.

### Core Principle: Reimagine, Don't Retrofit

<Info>
  **"We need automobiles, not faster horse chariots."**
</Info>

AI-DLC doesn't bolt AI onto existing processes. It rebuilds from first principles for an AI-native world.

### The Reversed Conversation

In traditional development, humans prompt AI:

```
Human: "Write a function that calculates tax"
AI: [generates code]
Human: "Now add error handling"
AI: [updates code]
```

In AI-DLC, **AI drives the conversation**:

```
AI: "I've analyzed your intent. Here are 3 Units I propose,
     with 12 user stories. I have 5 clarifying questions
     before we proceed. Question 1: What's your compliance
     framework for tax calculations?"
Human: [validates, approves, or redirects]
```

This is like Google Maps: *humans set the destination, AI provides step-by-step directions, humans maintain oversight.*

### Three Phases, Not Endless Sprints

| Phase            | Ritual           | Duration           | Output                              |
| ---------------- | ---------------- | ------------------ | ----------------------------------- |
| **Inception**    | Mob Elaboration  | Hours              | Intents → Units → Stories           |
| **Construction** | Mob Construction | Hours/Days (Bolts) | Domain Design → Code → Tests        |
| **Operations**   | Continuous       | Ongoing            | Deployment, monitoring, maintenance |

### Bolts Replace Sprints

| Sprints                | Bolts                        |
| ---------------------- | ---------------------------- |
| 2-4 weeks              | Hours or days                |
| Fixed timeboxes        | Flexible, intent-driven      |
| Velocity measured      | Business value measured      |
| Story points estimated | AI executes, humans validate |

### Mob Rituals: Collaborative AI Alignment

<AccordionGroup>
  <Accordion title="Mob Elaboration (Inception)">
    * Product managers, developers, QA collaborate with AI from the start
    * AI proposes breakdown into Units and Stories
    * Team validates in single room with shared screen
    * *What took months now takes hours*
  </Accordion>

  <Accordion title="Mob Construction (Construction)">
    * Teams work in parallel after domain modeling
    * AI generates component models, sequence diagrams, functional flows
    * Team provides real-time clarification on technical decisions
    * *Prevents hallucinations and poor design*
  </Accordion>
</AccordionGroup>

***

## Why You Don't Need Other Spec-Driven Tools

### The Landscape Today

| Tool         | Philosophy          | Limitation                      |
| ------------ | ------------------- | ------------------------------- |
| **Spec Kit** | Lightweight toolkit | No methodology, human-driven    |
| **BMAD**     | 19-agent simulation | Complex, no formal methodology  |
| **OpenSpec** | Change-centric      | No lifecycle, brownfield-only   |
| **Kiro**     | IDE-integrated      | Vendor lock-in, no team rituals |

### What They're Missing

These tools focus on **specifications**—they help you write better prompts and structure your requirements.

But specifications alone don't solve the fundamental problem:

<Warning>
  Traditional methods were built for longer iteration durations (months and weeks), which led to rituals like daily standups and retrospectives. With AI, iteration cycles are measured in hours or days. This needs continuous, real-time validation and feedback mechanisms, rendering many traditional rituals less relevant.
</Warning>

### AI-DLC Is Different

AI-DLC isn't a tool—it's a **methodology** that includes:

* **Formal phases** (Inception → Construction → Operations)
* **Defined rituals** (Mob Elaboration, Mob Construction)
* **Design integration** (DDD as core, not optional)
* **Reversed conversation** (AI proposes, human validates)
* **New artifacts** (Intents, Units, Bolts)

***

## specs.md: Three Flows for Every Use Case

**specs.md** is an AI-native development framework with pluggable flows. Choose the level of methodology that matches your project needs.

<CardGroup>
  <Card title="Simple Flow" icon="feather" href="/simple-flow/overview">
    **Spec Generation Only**

    Quick requirements, design, and task documents without execution tracking.

    * 1 agent, 3 phase gates
    * Kiro-style workflow
    * Best for: prototypes, handoff
  </Card>

  <Card title="FIRE Flow" icon="bolt" href="/fire-flow/overview">
    **Adaptive Execution**

    Ship in hours with adaptive checkpoints and first-class brownfield support.

    * 3 agents, adaptive checkpoints
    * Monorepo & brownfield ready
    * Optimized for: teams who hate friction
  </Card>

  <Card title="AI-DLC Flow" icon="building" href="/methodology/what-is-ai-dlc">
    **Full Methodology**

    Complete AI-DLC implementation with DDD and comprehensive traceability.

    * 4 agents, 10-26 checkpoints
    * Mob rituals, DDD as core
    * Best for: teams, complex domains
  </Card>
</CardGroup>

<Info>
  **Not sure which flow?** Check out our [Choose Your Flow](/architecture/choose-flow) guide.
</Info>

***

## The Bottom Line

| Old World                                  | New World                       |
| ------------------------------------------ | ------------------------------- |
| Sprints (weeks)                            | Bolts (hours/days)              |
| Story points                               | Business value                  |
| Human codes, AI assists                    | AI proposes, human validates    |
| Retrofit AI into Agile delivery frameworks | Reimagine from first principles |
| Specification tools                        | Complete methodology (AI-DLC)   |

<Info>
  **"AI might be the death of Agile delivery frameworks, but it's the beginning of true agility."**
</Info>

***

## Further Reading

<CardGroup>
  <Card title="AI-DLC Whitepaper (AWS)" icon="file-pdf" href="https://github.com/fabriqaai/specsmd/blob/main/resources/aidlc.pdf">
    The original AWS whitepaper defining AI-DLC methodology
  </Card>

  <Card title="V-Bounce Paper (arXiv)" icon="book" href="https://arxiv.org/abs/2408.03416">
    The AI-Native Software Development Lifecycle research paper
  </Card>

  <Card title="AWS Blog: AI-DLC" icon="aws" href="https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/">
    AWS DevOps blog post on reimagining software engineering
  </Card>

  <Card title="Compare Tools" icon="scale-balanced" href="/compare/overview">
    See how specs.md compares to Spec Kit, BMAD, Kiro, and OpenSpec
  </Card>
</CardGroup>


# The Three Phases
Source: https://specs.md/methodology/three-phases

Deep dive into Inception, Construction, and Operations

## Overview

AI-DLC organizes development into three distinct phases, each with specialized agents and clear outputs.

```mermaid actions={false} theme={null}
flowchart TB
    MA(Master Agent):::design --> IA(Inception):::plan
    MA --> CA(Construction):::build
    MA --> OA(Operations):::warn
    IA --> CA --> OA
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

## Phase 1: Inception

<Card title="Inception Agent" icon="lightbulb">
  Captures intents, elaborates requirements, and decomposes work into manageable units.
</Card>

### Purpose

Transform high-level goals into well-defined, implementable work items.

### Activities

<Steps>
  <Step title="Intent Capture">
    Gather the high-level goal: "User authentication system"
  </Step>

  <Step title="Requirement Elaboration">
    AI asks clarifying questions, generates user stories and NFRs
  </Step>

  <Step title="System Context">
    Define boundaries, interfaces, and constraints
  </Step>

  <Step title="Unit Decomposition">
    Break intent into loosely-coupled, independently developable units
  </Step>

  <Step title="Bolt Planning">
    Plan the bolts needed to implement each story
  </Step>
</Steps>

### Key Outputs

| Artifact            | Description                             |
| ------------------- | --------------------------------------- |
| `requirements.md`   | User stories, acceptance criteria, NFRs |
| `system-context.md` | Boundaries, interfaces, constraints     |
| `units.md`          | Unit definitions with dependencies      |
| Bolt Plans          | Ordered list of bolts per unit          |

***

## Phase 2: Construction

<Card title="Construction Agent" icon="hammer">
  Executes bolts through validated stages, producing tested, production-ready code.
</Card>

### Purpose

Transform specifications into working, tested code through disciplined stages.

### Bolt Stages

Each bolt type progresses through validated stages:

<Tabs>
  <Tab title="DDD Construction">
    For complex business logic and domain modeling:

    <AccordionGroup>
      <Accordion title="1. Domain Model">
        Model the business logic using DDD principles:

        * Identify aggregates, entities, value objects
        * Define domain events and commands
        * Establish ubiquitous language
      </Accordion>

      <Accordion title="2. Technical Design">
        Apply patterns and make architecture decisions:

        * Choose implementation patterns
        * Define interfaces and contracts
        * Plan data structures
      </Accordion>

      <Accordion title="3. ADR Analysis (Optional)">
        Document significant architectural decisions:

        * Context and problem statement
        * Options considered
        * Decision and rationale
        * Consequences
      </Accordion>

      <Accordion title="4. Implement">
        Generate production code:

        * Follow coding standards
        * Apply design patterns
        * Write clean, maintainable code
      </Accordion>

      <Accordion title="5. Test">
        Verify correctness:

        * Unit tests for domain logic
        * Integration tests for interfaces
        * Acceptance tests for stories
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Simple Construction">
    For UI, integrations, and utilities:

    <AccordionGroup>
      <Accordion title="1. Plan">
        Define what to build:

        * Review stories and requirements
        * List specific deliverables
        * Identify dependencies
        * Define acceptance criteria
      </Accordion>

      <Accordion title="2. Implement">
        Write the code:

        * Setup file structure
        * Implement core functionality
        * Handle edge cases
        * Add documentation
      </Accordion>

      <Accordion title="3. Test">
        Verify the implementation:

        * Write unit tests
        * Run test suite
        * Verify acceptance criteria
        * Document results
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

### Human Checkpoints

<Warning>
  Human validation happens at each checkpoint. The AI proposes, the human approves or requests changes. This prevents errors from cascading downstream.
</Warning>

### Bolt Types

| Type                    | Best For                             | Stages                             |
| ----------------------- | ------------------------------------ | ---------------------------------- |
| **DDD Construction**    | Complex domain logic, business rules | Model → Design → ADR → Code → Test |
| **Simple Construction** | UI, integrations, utilities          | Plan → Implement → Test            |

***

## Phase 3: Operations

<Card title="Operations Agent" icon="server">
  Deploys, verifies, and monitors the system in production.
</Card>

### Purpose

Take constructed features to production and ensure they run reliably.

### Activities

<Steps>
  <Step title="Build">
    Compile, bundle, and prepare deployment artifacts
  </Step>

  <Step title="Deploy">
    Deploy to target environment (staging, production)
  </Step>

  <Step title="Verify">
    Run smoke tests, health checks, and validation
  </Step>

  <Step title="Monitor">
    Set up logging, metrics, and alerting
  </Step>
</Steps>

### Key Outputs

| Artifact          | Description                            |
| ----------------- | -------------------------------------- |
| Deployment Units  | Containerized or packaged applications |
| Runbooks          | Operational procedures                 |
| Monitoring Config | Dashboards and alerts                  |

***

## Phase Transitions

### Inception → Construction

When moving from Inception to Construction:

1. All units are defined with clear boundaries
2. Stories have acceptance criteria
3. Bolt plans are approved
4. Dependencies are mapped

### Construction → Operations

When moving from Construction to Operations:

1. All bolts are completed and validated
2. Tests are passing
3. Code review is complete
4. Documentation is updated

## Master Agent Role

The Master Agent orchestrates across phases:

* **Routing**: Directs to the appropriate agent
* **Context**: Maintains awareness of project state
* **Guidance**: Helps navigate the methodology
* **Standards**: Enforces project conventions


# What is AI-DLC?
Source: https://specs.md/methodology/what-is-ai-dlc

Understanding the AI-Driven Development Lifecycle

## The AI-Driven Development Lifecycle

AI-DLC is the first development flow implemented in specs.md. It's a reimagined software development methodology where **AI drives the conversation** and humans validate. Unlike traditional Agile where iterations span weeks, AI-DLC operates in **Bolts** - rapid iterations measured in hours or days.

<Info>
  AI-DLC was developed by AWS and documented in their [AI-Driven Development Life Cycle](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) blog post. specs.md implements this methodology as a pluggable flow.
</Info>

## The Core Insight

> "Traditional development methods were built for human-driven, long-running processes. AI-DLC reimagines the development lifecycle with AI as a central collaborator, enabling rapid cycles measured in hours or days rather than weeks."

## Key Principles

<CardGroup>
  <Card title="AI-Driven" icon="robot">
    AI leads the conversation, proposes solutions, and generates artifacts. Humans validate and guide.
  </Card>

  <Card title="Rapid Iterations" icon="bolt">
    Bolts replace Sprints. Complete meaningful work in hours, not weeks.
  </Card>

  <Card title="Human Checkpoints" icon="door-open">
    Human validation at each checkpoint catches errors before they cascade.
  </Card>

  <Card title="Design-First" icon="compass-drafting">
    Domain-Driven Design is built into construction bolts, not an afterthought.
  </Card>
</CardGroup>

## The Three Phases

AI-DLC organizes work into three phases, each with a specialized agent:

```mermaid actions={false} theme={null}
flowchart TB
    MA(Master Agent):::design --> IA(Inception):::plan
    MA --> CA(Construction):::build
    MA --> OA(Operations):::warn
    IA --> CA --> OA
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
```

| Phase            | Purpose                                 | Key Outputs                          |
| ---------------- | --------------------------------------- | ------------------------------------ |
| **Inception**    | Capture intents, elaborate requirements | User stories, NFRs, Unit definitions |
| **Construction** | Execute bolts through validated stages  | Domain models, Code, Tests           |
| **Operations**   | Deploy, verify, and monitor             | Deployment units, Runbooks           |

## Why AI-DLC?

### The Problem with Traditional Methods

Traditional Agile methods have "whitespace" - areas left undefined that lead to:

* Inconsistent architecture decisions
* Missing design documentation
* Quality issues from skipped steps
* Context loss between iterations

### The AI-DLC Solution

AI-DLC fills these gaps by:

1. **Integrating design techniques** - DDD is integrated into construction bolts
2. **Creating persistent artifacts** - Memory Bank maintains context
3. **Enforcing checkpoints** - Each validation point ensures quality
4. **Enabling rapid iteration** - AI-powered decomposition and execution

## When to Use AI-DLC

AI-DLC is the right choice when:

* You have a team requiring coordination
* Your domain logic is complex and benefits from DDD
* You need comprehensive documentation and traceability
* You're in a regulated environment with audit requirements

<Info>
  **Need less ceremony?** specs.md offers two lighter flows:

  * **[FIRE Flow](/fire-flow/overview)** - Adaptive execution with brownfield & monorepo support
  * **[Simple Flow](/simple-flow/overview)** - Spec generation only, no execution tracking

  [Compare all flows →](/architecture/choose-flow)
</Info>

## Next Steps

<CardGroup>
  <Card title="AI-DLC vs Agile" icon="scale-balanced" href="/methodology/ai-dlc-vs-agile">
    Detailed comparison with traditional methods
  </Card>

  <Card title="The Three Phases" icon="diagram-project" href="/methodology/three-phases">
    Deep dive into Inception, Construction, Operations
  </Card>
</CardGroup>


# Simple Flow Agent
Source: https://specs.md/simple-flow/agent

The single agent that guides you through spec generation

## Overview

Simple Flow uses a single agent (`/specsmd-agent`) that guides you through all three phases: Requirements, Design, and Tasks.

```mermaid actions={false} theme={null}
flowchart LR
    A(specsmd-agent):::design --> R(Requirements):::plan
    A --> D(Design):::build
    A --> T(Tasks):::warn
    A --> E(Execute):::check
    classDef design fill:#fff,stroke:#A855F7,color:#7E22CE,stroke-width:1.5px,rx:8,ry:8
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8
```

## Invoking the Agent

<Warning>
  **These are NOT command-line commands.** These are prompts you type in your AI coding tool's chat interface.
</Warning>

<Tabs>
  <Tab title="Claude Code">
    ```
    /specsmd-agent
    ```
  </Tab>

  <Tab title="Cursor">
    ```
    /specsmd-agent
    ```

    Or use the `@` prefix:

    ```
    @specsmd-agent
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    ```
    @specsmd-agent
    ```
  </Tab>
</Tabs>

## Agent Capabilities

The Simple Flow agent handles:

<CardGroup>
  <Card title="Spec Creation" icon="file-plus">
    Generate requirements, design, and task documents from a feature idea
  </Card>

  <Card title="Phase Navigation" icon="arrows-left-right">
    Move through Requirements → Design → Tasks with explicit approval gates
  </Card>

  <Card title="Task Execution" icon="play">
    Execute implementation tasks one at a time with review
  </Card>

  <Card title="Context Loading" icon="folder-open">
    Resume work on existing specs by reading saved documents
  </Card>
</CardGroup>

## Commands

| Command         | Description              | Example                                |
| --------------- | ------------------------ | -------------------------------------- |
| Create new spec | Start a new feature spec | `/specsmd-agent Create a todo app`     |
| Continue work   | Resume existing spec     | `/specsmd-agent`                       |
| Resume specific | Work on named spec       | `/specsmd-agent --spec="todo-app"`     |
| Next task       | Ask what to do next      | `/specsmd-agent What's the next task?` |
| Execute task    | Run specific task        | `/specsmd-agent Execute task 2.1`      |

## Workflow

### 1. Create a Spec

```
/specsmd-agent Create a user dashboard with analytics
```

The agent:

1. Derives a feature name (`user-dashboard`)
2. Generates `requirements.md`
3. Waits for approval

### 2. Approve or Revise

**To approve:** Say "yes", "approved", or "looks good"

**To revise:** Provide specific feedback like "Add a requirement for export functionality"

### 3. Progress Through Phases

After approving requirements:

* Agent generates `design.md`
* Wait for approval
* Agent generates `tasks.md`
* Wait for approval

### 4. Execute Tasks

```
/specsmd-agent What's the next task?
```

The agent executes one task, then waits for review before continuing.

## Agent Session Lifecycle

<Steps>
  <Step title="Context Loading">
    Agent reads existing spec files from `specs/{feature-name}/`
  </Step>

  <Step title="Phase Detection">
    Agent determines current phase based on which files exist and their status
  </Step>

  <Step title="Generation or Execution">
    Agent generates the next document or executes the next task
  </Step>

  <Step title="Approval Gate">
    Agent waits for explicit approval before proceeding
  </Step>
</Steps>

<Warning>
  The agent is stateless. It reads spec files at startup. Ensure documents are saved after each step.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Be specific with feature ideas">
    **Good**: "User auth with email/password and session management"

    **Too vague**: "Login feature"

    The more specific you are, the better the generated specs.
  </Accordion>

  <Accordion title="Review each phase carefully">
    Don't rush through approvals. The design phase influences task generation, and tasks influence implementation quality.
  </Accordion>

  <Accordion title="One task at a time (default)">
    The agent pauses after each task for review. If you're confident, say "continue until done" or "go yolo".
  </Accordion>

  <Accordion title="Use checkpoints">
    Checkpoint tasks run the test suite. Don't skip them—they catch issues early.
  </Accordion>
</AccordionGroup>

## Comparison with Other Flows

| Aspect         | Simple (1 agent)         | FIRE (3 agents)    | AI-DLC (4 agents)                     |
| -------------- | ------------------------ | ------------------ | ------------------------------------- |
| **Complexity** | Single agent handles all | Specialized agents | Highly specialized                    |
| **Phases**     | Req → Design → Tasks     | Plan → Execute     | Inception → Construction → Operations |
| **Overhead**   | Minimal                  | Adaptive           | Comprehensive                         |
| **Best for**   | Quick specs, prototypes  | Production work    | Complex domains                       |


# Simple Flow Overview
Source: https://specs.md/simple-flow/overview

Lightweight spec-driven development for simpler projects

## What is Simple Flow?

Simple Flow is a lightweight spec-driven development workflow for projects that don't need the full complexity of AI-DLC. It guides you through three phases to transform a feature idea into an actionable implementation plan.

<Info>
  **Think of it as**: Kiro-style spec-driven development that works with any AI coding tool—Claude Code, Cursor, GitHub Copilot, and more.
</Info>

***

## Three Phases

| Phase            | Output            | Purpose                                                        |
| ---------------- | ----------------- | -------------------------------------------------------------- |
| **Requirements** | `requirements.md` | Define what to build with user stories and EARS criteria       |
| **Design**       | `design.md`       | Create technical design with architecture and Mermaid diagrams |
| **Tasks**        | `tasks.md`        | Generate implementation checklist with coding tasks            |

One agent (`/specsmd-agent`) guides you through all phases.

***

## When to Use Simple Flow

<CardGroup>
  <Card title="Simple Flow" icon="feather">
    **Spec generation only**

    * Building prototypes or MVPs
    * Quick feature specs
    * Handoff to other teams
    * No execution tracking needed
  </Card>

  <Card title="FIRE Flow" icon="bolt" href="/fire-flow/overview">
    **Adaptive execution**

    * Teams who hate friction
    * Brownfield projects
    * Monorepos
    * Ship in hours, not days
  </Card>

  <Card title="AI-DLC Flow" icon="building" href="/methodology/what-is-ai-dlc">
    **Full methodology**

    * Multi-team coordination
    * Complex domain logic (DDD)
    * Regulated environments
    * Full traceability needed
  </Card>
</CardGroup>

<Info>
  **Independent Flows**: Flows are designed for different use cases—they're not an upgrade path. Choose based on your project needs. [Compare all flows →](/architecture/choose-flow)
</Info>

***

## Flow Comparison

| Aspect                 | Simple               | FIRE               | AI-DLC                                |
| ---------------------- | -------------------- | ------------------ | ------------------------------------- |
| **Optimized For**      | Spec generation      | Adaptive execution | Full traceability                     |
| **Checkpoints**        | 3 (phase gates)      | Adaptive           | Comprehensive                         |
| **Agents**             | 1                    | 3                  | 4                                     |
| **Execution Tracking** | No                   | Yes                | Yes                                   |
| **Phases**             | Req → Design → Tasks | Plan → Execute     | Inception → Construction → Operations |
| **Output**             | `specs/` folder      | `.specs-fire/`     | `memory-bank/`                        |
| **Design Docs**        | Basic                | When needed        | DDD or Simple bolt                    |
| **Overhead**           | Minimal              | Adaptive           | Significant                           |

***

## Output Structure

Simple Flow creates a clean, flat structure:

```
specs/
└── {feature-name}/
    ├── requirements.md    # What to build
    ├── design.md          # How to build it
    └── tasks.md           # Step-by-step plan
```

No complex memory-bank hierarchy—just specs.

***

## Core Principles

### Generate First, Ask Later

The agent generates a draft document immediately based on your feature idea. This serves as a starting point for discussion rather than requiring extensive Q\&A upfront.

### Explicit Approval Gates

You must explicitly approve each phase before proceeding. Say "yes", "approved", or "looks good" to continue. Any feedback triggers revision.

### One Phase at a Time

The agent focuses on one document per interaction. Complete each phase before moving to the next.

### One Task at a Time

During execution, only one task is implemented per interaction. This allows careful review of each change.

***

## Getting Started

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/simple-flow/quick-start">
    Get started with Simple Flow in minutes
  </Card>

  <Card title="Three Phases" icon="list-check" href="/simple-flow/three-phases">
    Learn about Requirements, Design, and Tasks
  </Card>
</CardGroup>


# Quick Start
Source: https://specs.md/simple-flow/quick-start

Get started with Simple Flow in minutes

## Prerequisites

* Node.js 18+ installed
* An AI coding tool (Claude Code, Cursor, GitHub Copilot, etc.)
* A feature idea to spec out

## Installation

```bash theme={null}
npx specsmd@latest install
```

Select **Simple** when prompted for the SDLC flow.

The installer will:

1. Detect available agentic coding tools (Claude Code, Cursor, Kiro, etc.)
2. Install the spec agent and skills
3. Set up slash commands for your tools

***

## Your First Spec

### Step 1: Create a New Spec

Open your AI coding tool and invoke the agent:

```
/specsmd-agent Create a todo app with local storage
```

The agent will:

1. Derive a feature name (`todo-app`)
2. Generate a requirements document
3. Ask for your approval

### Step 2: Review Requirements

The agent generates:

```markdown theme={null}
# Requirements Document

## Introduction
A simple todo application that allows users to manage their daily tasks...

## Glossary
- **Todo_System**: The complete todo application
- **Task**: A single todo item with description and completion status
- **Task_List**: The collection of all tasks

## Requirements

### Requirement 1
**User Story:** As a user, I want to add new tasks...

#### Acceptance Criteria
1. WHEN user types a task and presses Enter, THE Todo_System SHALL create a new task
2. WHEN user attempts to add empty task, THE Todo_System SHALL prevent addition
```

**To approve:** Say "yes", "approved", or "looks good"

**To revise:** Provide specific feedback

### Step 3: Review Design

After approval, the agent generates a technical design:

```markdown theme={null}
# Design Document

## Overview
The todo application uses a simple client-side architecture...

## Architecture
[Mermaid diagram]

## Components
- TaskInput: Handles new task creation
- TaskList: Renders all tasks
- TaskItem: Individual task with actions

## Data Models
interface Task {
  id: string;
  description: string;
  completed: boolean;
  createdAt: Date;
}
```

### Step 4: Review Tasks

After design approval:

```markdown theme={null}
# Implementation Tasks

- [ ] 1. Set up project structure
  _Requirements: Setup_

- [ ] 2. Create Task data model
  - [ ] 2.1 Define Task interface
  - [ ] 2.2 Add validation
  _Requirements: 1.1_

- [ ] 3. Checkpoint - Verify tests pass

- [ ] 4. Implement TaskInput component
  _Requirements: 1.1, 1.2_
```

### Step 5: Execute Tasks

Once tasks are approved:

```
/specsmd-agent What's the next task?
```

The agent executes one task, then waits for your review.

***

## Commands Reference

| Action                | Command                                  |
| --------------------- | ---------------------------------------- |
| Create new spec       | `/specsmd-agent Create a [feature idea]` |
| Continue existing     | `/specsmd-agent`                         |
| Resume specific spec  | `/specsmd-agent --spec="todo-app"`       |
| Ask what's next       | `/specsmd-agent What's the next task?`   |
| Execute specific task | `/specsmd-agent Execute task 2.1`        |

***

## File Structure

After installation:

```
.specsmd/
├── manifest.yaml              # Installation manifest
└── simple/                    # Simple flow resources
    ├── agents/agent.md        # Agent definition
    ├── skills/                # Agent skills
    ├── templates/             # Document templates
    └── memory-bank.yaml       # Storage schema

specs/                         # Your feature specs
└── todo-app/
    ├── requirements.md
    ├── design.md
    └── tasks.md
```

***

## Tips for Success

<AccordionGroup>
  <Accordion title="Be specific with your feature idea">
    **Good**: "User auth with email/password and session management"

    **Too vague**: "Login feature"

    The more specific you are, the better the generated specs.
  </Accordion>

  <Accordion title="Review checkpoints">
    Checkpoint tasks run the test suite. Don't skip them—they catch issues early.
  </Accordion>

  <Accordion title="One task at a time (default)">
    The agent pauses after each task for review. If you're happy with progress, tell it to keep going (e.g., "continue until done", "go yolo").
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent doesn't remember context">
    The agent is stateless—it reads spec files at startup. Ensure documents are saved after each step.
  </Accordion>

  <Accordion title="Multiple specs exist">
    Run `/specsmd-agent` without arguments to see all specs and choose which to work on.
  </Accordion>

  <Accordion title="Want to start over">
    Delete the spec folder:

    ```bash theme={null}
    rm -rf specs/{feature-name}
    ```
  </Accordion>

  <Accordion title="Input too vague">
    If your feature idea is too vague, the agent will ask a clarifying question before generating. Provide more specific details.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Three Phases" icon="list-check" href="/simple-flow/three-phases">
    Deep dive into Requirements, Design, and Tasks
  </Card>

  <Card title="Compare with AI-DLC" icon="scale-balanced" href="/simple-flow/overview">
    When to use Simple Flow vs full AI-DLC
  </Card>
</CardGroup>


# Three Phases
Source: https://specs.md/simple-flow/three-phases

Requirements, Design, and Tasks in Simple Flow

## Overview

Simple Flow guides you through three sequential phases, each producing a markdown document:

```mermaid actions={false} theme={null}
flowchart LR
    A(Feature Idea):::build --> B(Requirements):::plan
    B --> C(Design):::build
    C --> D(Tasks):::warn
    D --> E(Execute):::done
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

Each phase requires explicit approval before proceeding to the next.

***

## Phase 1: Requirements

Define **what** to build with user stories and acceptance criteria.

### Output

`specs/{feature}/requirements.md`

### Contents

* **Introduction** - 2-3 sentence feature summary
* **Glossary** - Domain terms used consistently throughout
* **Requirements** - User stories with EARS acceptance criteria

### EARS Format

Requirements use EARS (Easy Approach to Requirements Syntax):

| Pattern          | Format                                                | Example                                                              |
| ---------------- | ----------------------------------------------------- | -------------------------------------------------------------------- |
| **Event-driven** | WHEN \[trigger], THE \[system] SHALL \[response]      | WHEN user submits login, THE Auth\_System SHALL validate credentials |
| **State-driven** | WHILE \[condition], THE \[system] SHALL \[response]   | WHILE session active, THE Auth\_System SHALL refresh tokens          |
| **Unwanted**     | IF \[condition], THEN THE \[system] SHALL \[response] | IF password invalid, THEN THE Auth\_System SHALL display error       |
| **Optional**     | WHERE \[option], THE \[system] SHALL \[response]      | WHERE MFA enabled, THE Auth\_System SHALL require second factor      |

### Example

```markdown theme={null}
## Requirements

### Requirement 1

**User Story:** As a user, I want to log in with my email and password,
so that I can access my account.

#### Acceptance Criteria

1. WHEN user submits valid credentials, THE Auth_System SHALL create a session
2. IF password is invalid, THEN THE Auth_System SHALL display error message
3. WHILE session is active, THE Auth_System SHALL maintain authentication state
```

### Approval Prompt

> "Do the requirements look good? If so, we can move on to the design."

***

## Phase 2: Design

Define **how** to build it with technical architecture.

### Output

`specs/{feature}/design.md`

### Contents

* **Overview** - Solution approach and key decisions
* **Architecture** - Mermaid diagrams showing system structure
* **Components** - Interfaces and responsibilities
* **Data Models** - TypeScript interfaces with validation rules
* **Error Handling** - Error types and recovery strategies
* **Testing Strategy** - Test categories and coverage

### Mermaid Diagrams

All visual diagrams use Mermaid syntax:

```mermaid actions={false} theme={null}
flowchart TB
    subgraph Frontend
        UI(Login Form):::plan
    end

    subgraph Backend
        API(Auth API):::build
        DB[(User DB)]:::done
    end

    UI --> API
    API --> DB
    classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8
    classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8
    classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8
```

### Example Data Model

```typescript theme={null}
interface User {
  id: string;           // UUID, required
  email: string;        // Valid email format
  passwordHash: string; // Bcrypt hash
  createdAt: Date;
  lastLogin?: Date;
}
```

### Approval Prompt

> "Does the design look good? If so, we can move on to the implementation plan."

***

## Phase 3: Tasks

Generate a **step-by-step** implementation plan.

### Output

`specs/{feature}/tasks.md`

### Contents

* **Numbered checkbox list** - Incremental coding steps
* **Requirement references** - Traceability to requirements
* **Checkpoint tasks** - Verification points (run tests)

### Task Format

```markdown theme={null}
## Tasks

- [ ] 1. Set up authentication module structure
  _Requirements: 1.1_

- [ ] 2. Implement user data model
  - [ ] 2.1 Create User interface
  - [ ] 2.2 Add validation rules
  - [ ] 2.3 Write unit tests
  _Requirements: 1.2, 1.3_

- [ ] 3. Checkpoint - Verify all tests pass

- [ ] 4. Implement login endpoint
  _Requirements: 1.1, 1.4_
```

### Task Rules

| Rule                  | Description                                       |
| --------------------- | ------------------------------------------------- |
| **Coding tasks only** | No deployment, documentation, or manual testing   |
| **Incremental**       | Each task builds on previous                      |
| **Checkpoints**       | Run tests every 2-3 tasks                         |
| **Traceability**      | Reference requirements with `_Requirements: X.Y_` |
| **Max 2 levels**      | Top-level (1, 2, 3) and sub-tasks (2.1, 2.2)      |

### Approval Prompt

> "Do the tasks look good?"

***

## Phase Transitions

### Forward Flow

```
Requirements ──approved──> Design ──approved──> Tasks ──approved──> Execute
```

### Backward Flow (Phase Regression)

If gaps are found, the agent suggests returning to a previous phase:

| Current | Trigger               | Action                           |
| ------- | --------------------- | -------------------------------- |
| Design  | Requirement ambiguous | "Should we update requirements?" |
| Tasks   | Design gap found      | "Should we update design?"       |
| Execute | Task blocked          | "Should we add a task?"          |

***

## Execution

After all three documents are approved, execute tasks one at a time:

```
/specsmd-agent What's the next task?
```

Or specify a task:

```
/specsmd-agent Execute task 2.1
```

The agent:

1. Reads all three spec files
2. Executes the task
3. Marks it complete `[x]`
4. Recommends the next task
5. **Stops and waits for review**

***

## Summary

| Phase        | Question       | Output                  | Approval     |
| ------------ | -------------- | ----------------------- | ------------ |
| Requirements | What to build? | `requirements.md`       | "looks good" |
| Design       | How to build?  | `design.md`             | "approved"   |
| Tasks        | Step by step?  | `tasks.md`              | "yes"        |
| Execute      | Build it       | Code + `[x]` checkmarks | Per task     |