### Initialize Project with Standards

Source: https://specs.md/agents/master-agent

Run the 'project-init' command to start the project setup process. This command guides you through establishing technical standards, coding conventions, and system architecture.

```bash
> project-init
```

--------------------------------

### Initialize Project with Master Agent

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

Use the Master Agent to initiate project setup and guide through standard establishment.

```bash
/specsmd-master-agent
> project-init
```

--------------------------------

### Start Master Agent with Cursor

Source: https://specs.md/agents/quick-start

Initiate the Master Agent for project setup using the specified command or @ prefix in Cursor.

```bash
/specsmd-master-agent
```

```bash
@specsmd-master-agent
```

--------------------------------

### Construction Agent Example Session

Source: https://specs.md/agents/construction-agent

An example interaction demonstrating how a user starts a 'bolt' and progresses through the 'Domain Model' stage, including user prompts and agent responses.

```text
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...

```

--------------------------------

### Setup Monitoring with Operations Agent

Source: https://specs.md/agents/operations-agent

Use this command to initiate the monitoring setup process managed by the Operations Agent.

```bash
> monitor setup
```

--------------------------------

### Start Builder Agent (GitHub Copilot)

Source: https://specs.md/fire-flow/quick-start

Use the @ prefix to start the builder agent with GitHub Copilot.

```bash
@fire-builder
```

--------------------------------

### Create Spec Example

Source: https://specs.md/simple-flow/agent

Example of initiating the creation of a new feature spec, such as a user dashboard with analytics.

```bash
/specsmd-agent Create a user dashboard with analytics
```

--------------------------------

### Start Master Agent with Claude Code

Source: https://specs.md/agents/quick-start

Initiate the Master Agent for project setup using the specified command in Claude Code.

```bash
/specsmd-master-agent
```

--------------------------------

### Start Builder Agent (Cursor)

Source: https://specs.md/fire-flow/quick-start

Use this command or the @ prefix to start the builder agent in Cursor.

```bash
/specsmd-fire-builder
```

```bash
@fire-builder
```

--------------------------------

### Planner Agent Example Session

Source: https://specs.md/fire-flow/agents

An example of a command-line session demonstrating the Planner Agent's intent capture and work item decomposition process.

```text
/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]
```

--------------------------------

### Review Walkthrough Example

Source: https://specs.md/fire-flow/quick-start

This is an example of a generated walkthrough file after a run, detailing the summary, files changed, key decisions, verification steps, and test coverage.

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

--------------------------------

### Install specs.md CLI

Source: https://specs.md/

Command to install the specs.md CLI tool globally. This is the first step to begin using the framework.

```bash
npx specsmd@latest install

```

--------------------------------

### Builder Agent Example Session

Source: https://specs.md/fire-flow/agents

An example session demonstrating the Builder Agent's workflow, including selecting a work item, planning changes, executing them, and generating a walkthrough.

```shell
/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
```

--------------------------------

### Implementation Tasks Example

Source: https://specs.md/simple-flow/quick-start

An example of implementation tasks generated by the agent, including task breakdown and requirements linkage.

```markdown
# 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_
```

--------------------------------

### Install specs.md CLI

Source: https://specs.md/agents/quick-start

Install the specs.md command-line interface globally using npm. Ensure you have Node.js 18+ installed.

```bash
npx specsmd@latest install
```

--------------------------------

### Start Builder Agent (Claude Code)

Source: https://specs.md/fire-flow/quick-start

Use this command to start the builder agent when using Claude Code.

```bash
/specsmd-fire-builder
```

--------------------------------

### Web Dashboard Examples

Source: https://specs.md/getting-started/specs-md-dashboard

Illustrates various ways to launch the web dashboard with different configurations, such as inspecting another workspace or using a fixed port.

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

--------------------------------

### Module Tech Stack Convention Example

Source: https://specs.md/fire-flow/monorepo-support

Example of documenting a module's tech stack, explaining the rationale for technology choices and migration details.

```markdown
# 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.
```

--------------------------------

### Select FIRE flow during installation

Source: https://specs.md/fire-flow/quick-start

When prompted during installation, choose FIRE as your development flow to enable adaptive execution for brownfield and monorepo projects.

```bash
? Select a development flow:
  AI-DLC - Full methodology with DDD
❯ FIRE - Adaptive execution, brownfield & monorepo ready
  Simple - Spec generation only
```

--------------------------------

### Example Build Session

Source: https://specs.md/agents/operations-agent

Illustrates a typical user interaction and agent response during a build process, showing the steps from prerequisites check to artifact creation.

```text
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.
```

--------------------------------

### Autopilot Mode Example

Source: https://specs.md/fire-flow/execution-modes

Illustrates the output of Autopilot mode, showing the execution summary and generated walkthrough for a typo fix.

```text
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.
```

--------------------------------

### Example Intent Definition

Source: https://specs.md/aidlc/overview

Defines a high-level business objective for AI-DLC development. This is the starting point for all work.

```yaml
intent:
  id: 001-user-authentication
  title: User Authentication System
  status: in_progress
```

--------------------------------

### Select Development Flow

Source: https://specs.md/getting-started/installation

During installation, you'll be prompted to select a development flow. The table outlines the purpose and agent count for each flow.

```bash
? 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)
```

--------------------------------

### Install VS Code Extension via Command Line

Source: https://specs.md/getting-started/vscode-extension

Use this command to install the specsmd extension directly from your terminal.

```bash
code --install-extension fabriqaai.specsmd

```

--------------------------------

### Example Inception Agent Session

Source: https://specs.md/agents/inception-agent

An example interaction session demonstrating the Inception Agent's process of capturing a user's goal, asking clarifying questions, and generating requirements.

```text
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 Document Example

Source: https://specs.md/simple-flow/quick-start

An example of a requirements document generated by the agent, including introduction, glossary, user stories, and acceptance criteria.

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

--------------------------------

### specs.md Skills and Templates Example

Source: https://specs.md/compare/vs-kiro

An example of a skill definition in specs.md that outlines actions for domain modeling, triggered by specific events.

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

```

--------------------------------

### Run Project Initialization Command

Source: https://specs.md/agents/quick-start

After starting the Master Agent, run the 'project-init' command to begin configuring your project's technical stack, coding standards, and architecture.

```bash
project-init
```

--------------------------------

### Work Item Dependencies Example

Source: https://specs.md/fire-flow/work-items

Illustrates how to define dependencies between work items using a YAML structure. The 'depends_on' field lists the IDs of work items that must be completed before the current one can start.

```yaml
work_items:
  - id: user-schema
    depends_on: []

  - id: login-endpoint
    depends_on: [user-schema]  # Must complete first

  - id: session-middleware
    depends_on: [login-endpoint]
```

--------------------------------

### Work Item Sizing - Just Right Example

Source: https://specs.md/fire-flow/work-items

Examples of appropriately sized work items that deliver clear value and have defined completion criteria.

```text
✅ "Create user database schema"
✅ "Implement login endpoint"
✅ "Add session management"

```

--------------------------------

### System Context Document Example

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

The system-context.md file defines the scope, interfaces, and constraints for an intent.

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

--------------------------------

### Confirm Mode Feedback Example

Source: https://specs.md/fire-flow/execution-modes

Demonstrates how to provide feedback to the AI in Confirm mode when the initial plan requires revision.

```text
[Confirm? n]

Feedback: Also include the user's recent activity in the response
```

--------------------------------

### Orchestrator Agent Session Resume Example

Source: https://specs.md/fire-flow/agents

This example demonstrates how the Orchestrator agent handles session resume, allowing users to continue or modify a previous session's progress.

```bash
/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
```

--------------------------------

### Run Tracking Log Example

Source: https://specs.md/fire-flow/work-items

An example of a YAML file used to log the details of a completed Fire Flow run, including status, files modified, and generated walkthrough.

```yaml
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
```

--------------------------------

### Work Item Sizing - Too Large Example

Source: https://specs.md/fire-flow/work-items

Examples of work items that are too large and should be decomposed into smaller, manageable Intents.

```text
❌ "Build authentication system"
❌ "Implement entire API"

```

--------------------------------

### Run the Web Dashboard

Source: https://specs.md/learn/specs-md-dashboard

Execute this command in your project folder to start the local web dashboard. It reads local memory banks and updates as agents change project state.

```bash
npx specsmd@latest dashboard
```

--------------------------------

### Start on a Specific Worktree

Source: https://specs.md/getting-started/specs-md-dashboard

Use the `--worktree` option to specify the initial worktree (branch name, ID, or path) to display.

```bash
npx specsmd@latest dashboard-cli --worktree feature-auth
```

--------------------------------

### Start Bolt with Construction Agent

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

Command to initiate the Construction Agent for a specific unit. This command starts the bolt execution process.

```bash
/specsmd-construction-agent --unit="my-unit"
```

--------------------------------

### Select AI-DLC Development Flow

Source: https://specs.md/agents/quick-start

When prompted during installation, select 'AI-DLC' to use the full methodology with Domain-Driven Design principles.

```bash
? Select a development flow:
❯ AI-DLC - Full methodology with DDD
  FIRE - Adaptive execution, brownfield & monorepo ready
  Simple - Spec generation only
```

--------------------------------

### Confirm Mode Plan Example

Source: https://specs.md/fire-flow/execution-modes

Shows the plan presented by the AI in Confirm mode for adding a user profile endpoint, awaiting human confirmation.

```text
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]
```

--------------------------------

### Example Intent Decomposition into Units

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

Illustrates how a high-level intent like 'User Authentication System' can be broken down into smaller, manageable units.

```text
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
```

--------------------------------

### Kiro Agent Hooks Example

Source: https://specs.md/compare/vs-kiro

Demonstrates an event-driven agent hook in Kiro that triggers an action when a file is saved.

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

```

--------------------------------

### EARS Format Examples

Source: https://specs.md/simple-flow/three-phases

Examples of the EARS (Easy Approach to Requirements Syntax) patterns for defining requirements. These patterns include Event-driven, State-driven, Unwanted, and Optional scenarios.

```markdown
WHEN [trigger], THE [system] SHALL [response]
WHEN user submits login, THE Auth_System SHALL validate credentials
```

```markdown
WHILE [condition], THE [system] SHALL [response]
WHILE session active, THE Auth_System SHALL refresh tokens
```

```markdown
IF [condition], THEN THE [system] SHALL [response]
IF password invalid, THEN THE Auth_System SHALL display error
```

```markdown
WHERE [option], THE [system] SHALL [response]
WHERE MFA enabled, THE Auth_System SHALL require second factor
```

--------------------------------

### Requirements Document Example

Source: https://specs.md/simple-flow/three-phases

An example of a requirements document section using the EARS format for user stories and acceptance criteria. This demonstrates how to structure requirements for a feature.

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

--------------------------------

### BMAD Agent Organization Example

Source: https://specs.md/compare/vs-bmad

Illustrates the traditional Agile role-based organization of agents in the BMAD methodology.

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

--------------------------------

### Simple Flow Installation Structure

Source: https://specs.md/getting-started/installation

This structure is created for the Simple Flow, featuring a single agent configuration.

```text
.specsmd/
├── manifest.yaml              # Installation manifest
└── simple/                    # Simple flow
    └── agents/                # Single agent

specs/                         # Your specs will go here
└── (feature folders)
```

--------------------------------

### Verify Specs.md Installation

Source: https://specs.md/faq

Check if the Specs.md agent directory is populated. If it's empty or missing, reinstall Specs.md using the provided command.

```bash
ls .specsmd/aidlc/agents/
```

```bash
npx specsmd@latest install
```

--------------------------------

### Work Item Sizing - Too Small Example

Source: https://specs.md/fire-flow/work-items

Examples of work items that are too small and represent implementation details rather than deliverable units of value.

```text
❌ "Add import statement"
❌ "Create empty file"
❌ "Add one test case"

```

--------------------------------

### Master Agent Interaction Example

Source: https://specs.md/agents/master-agent

Demonstrates a typical user interaction with the Master Agent, showcasing its capabilities for project initialization and guidance.

```text
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]
```

--------------------------------

### Design Document Example

Source: https://specs.md/simple-flow/quick-start

An example of a technical design document generated by the agent, outlining the overview, architecture, components, and data models.

```markdown
# 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;
}
```

--------------------------------

### Start Dashboard Without Opening Browser

Source: https://specs.md/getting-started/specs-md-dashboard

Use this command to start the dashboard without automatically opening a browser window. This is useful if you prefer to manually navigate to the dashboard URL.

```bash
npx specsmd@latest dashboard --no-open
```

--------------------------------

### Requirements Document Example

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

The requirements.md file outlines user stories, acceptance criteria, and non-functional requirements for an intent.

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

--------------------------------

### Example Verification Output

Source: https://specs.md/agents/operations-agent

This output shows the detailed results of a 'verify staging' command, including smoke tests, health endpoint checks, integration tests, and performance metrics.

```text
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.
```

--------------------------------

### Activate Inception Agent with @ prefix in Cursor

Source: https://specs.md/agents/overview

Use this command with the '@' prefix to start the inception agent in Cursor. Ensure you are in the chat interface.

```bash
@specsmd-inception-agent
```

--------------------------------

### Intent Brief Document Example

Source: https://specs.md/fire-flow/work-items

Markdown format for an Intent's brief documentation, outlining the objective, context, and success criteria.

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

--------------------------------

### Project Constitution Example

Source: https://specs.md/fire-flow/monorepo-support

Defines universal policies for a project, covering Git workflow, security, CI/CD, and quality standards. This constitution is always inherited and cannot be overridden by individual modules.

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

--------------------------------

### FIRE State Tracking Example

Source: https://specs.md/fire-flow/quick-start

This YAML file shows the structure of FIRE's state tracking, including project details, workspace configuration, and intent statuses.

```yaml
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
```

--------------------------------

### SpecsMD Default File Structure

Source: https://specs.md/simple-flow/quick-start

Illustrates the directory and file structure created by SpecsMD after installation, including configuration files and resource directories.

```tree
.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
```

--------------------------------

### Explain AI-DLC Methodology

Source: https://specs.md/agents/master-agent

Use 'explain-flow' to get an explanation of the AI-DLC methodology, including its phases, core concepts like Intents and Units, and how checkpoints and memory banks function.

```bash
> explain-flow
```

--------------------------------

### specs.md (AI-DLC) Agent Organization Example

Source: https://specs.md/compare/vs-bmad

Shows the phase-aligned agent structure used in the specs.md (AI-DLC) methodology.

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

--------------------------------

### Autopilot Mode Execution

Source: https://specs.md/fire-flow/quick-start

In Autopilot mode, the AI executes directly and generates a walkthrough. This example shows successful file creation and model updates.

```text
✓ 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
```

--------------------------------

### Activate Construction Agent with @ prefix in Cursor

Source: https://specs.md/agents/overview

Use this command with the '@' prefix to start the construction agent in Cursor. Ensure you are in the chat interface.

```bash
@specsmd-construction-agent
```

--------------------------------

### Run Lifecycle Diagram

Source: https://specs.md/fire-flow/work-items

Visualizes the state transitions of a Fire Flow run from start to completion or failure.

```mermaid
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
```

--------------------------------

### Orchestrator Agent Usage Example

Source: https://specs.md/fire-flow/agents

This snippet shows a typical interaction with the Orchestrator agent, including reading project state and routing to the appropriate agent for the next action.

```bash
/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.
```

--------------------------------

### Invoke FIRE Planner Agent (GitHub Copilot)

Source: https://specs.md/fire-flow/quick-start

Start the FIRE Planner agent within your AI coding tool using the '@' prefix for GitHub Copilot.

```bash
@fire-planner
```

--------------------------------

### Walkthrough Structure Example

Source: https://specs.md/fire-flow/work-items

This markdown structure outlines a typical walkthrough generated after a successful run, detailing summary, files changed, key decisions, verification steps, and test coverage.

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

```

--------------------------------

### Monorepo Workspace Analysis Example

Source: https://specs.md/fire-flow/monorepo-support

This YAML snippet shows the structure of a detected monorepo workspace, including its type, structure, parts, integrations, and key files.

```yaml
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
```

--------------------------------

### Intent Structure Example

Source: https://specs.md/fire-flow/work-items

YAML structure for defining an Intent, including its ID, title, description, status, priority, and creation timestamp.

```yaml
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
```

--------------------------------

### List All Bolts

Source: https://specs.md/agents/construction-agent

Use this command to get a comprehensive list of all bolts across the project, including their status and completion time.

```bash
> bolt-list
```

--------------------------------

### Activate Operations Agent with @ prefix in Cursor

Source: https://specs.md/agents/overview

Use this command with the '@' prefix to start the operations agent in Cursor. Ensure you are in the chat interface.

```bash
@specsmd-operations-agent
```

--------------------------------

### Describe User Intent for Authentication

Source: https://specs.md/fire-flow/quick-start

Provide a clear description of your desired feature to the FIRE Planner. This example outlines the requirements for user authentication.

```plaintext
I want to add user authentication with email/password login,
password reset, and session management.
```

--------------------------------

### Targeting a Single Module for Work Item

Source: https://specs.md/fire-flow/monorepo-support

This YAML example demonstrates how to specify a single target module for a work item, ensuring that module-specific standards and conventions are followed.

```yaml
work_item:
  id: add-user-endpoint
  module: packages/api  # Target specific module
  title: Add user CRUD endpoint
```

--------------------------------

### Standards Catalog Configuration

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

Defines the structure and hierarchy of project standards, including their importance, dependencies, and associated facilitation guides.

```yaml
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]
```

--------------------------------

### Generated Tech Stack Example

Source: https://specs.md/fire-flow/monorepo-support

A generated markdown file detailing the detected technologies used within a project, including languages, frameworks, databases, testing tools, and build configurations.

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

--------------------------------

### Activate Inception Agent in Claude Code

Source: https://specs.md/agents/overview

Use this command to start the inception agent in Claude Code. Ensure you are in the chat interface.

```bash
/specsmd-inception-agent
```

--------------------------------

### Confirm Mode Execution

Source: https://specs.md/fire-flow/quick-start

In Confirm mode, the AI presents a plan and waits for user confirmation before proceeding. This example shows a plan for creating a login endpoint.

```text
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]
```

--------------------------------

### Example FIRE Work Items

Source: https://specs.md/fire-flow/quick-start

Review the work items generated by the FIRE Planner, noting their IDs, titles, complexity, and recommended execution modes (autopilot, confirm, validate).

```yaml
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
```

--------------------------------

### Deploy to Production Environment

Source: https://specs.md/agents/operations-agent

Use the 'deploy' command followed by 'production'. Production deployments require explicit confirmation.

```bash
> deploy production
```

--------------------------------

### FIRE Flow Installation Structure

Source: https://specs.md/getting-started/installation

This structure is generated for the FIRE Flow, including orchestrator, planner, and builder agents, along with agent capabilities.

```text
.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
```

--------------------------------

### Answer Project-Specific Questions

Source: https://specs.md/agents/master-agent

Utilize 'answer-question' to get help with any specs.md related queries. The agent provides context-aware answers by leveraging the AI-DLC methodology, your project's current state, and Memory Bank artifacts.

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

--------------------------------

### Invoke FIRE Planner Agent (Cursor)

Source: https://specs.md/fire-flow/quick-start

Start the FIRE Planner agent within your AI coding tool using either the slash command or the '@' prefix for Cursor.

```bash
/specsmd-fire-planner
```

```bash
@fire-planner
```

--------------------------------

### Deploy to Staging Environment

Source: https://specs.md/agents/operations-agent

Use the 'deploy' command followed by the target environment name, such as 'staging'.

```bash
> deploy staging
```

--------------------------------

### Planner Agent Design Document Generation

Source: https://specs.md/fire-flow/agents

An example of the Planner Agent generating a design document for a 'session-middleware' work item, including its structure and security considerations.

```text
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]
```

--------------------------------

### Validate Mode Example: Password Reset Flow

Source: https://specs.md/fire-flow/execution-modes

Illustrates a work item in Validate mode, including the AI-generated design document and the human-approved implementation plan for a password reset flow.

```markdown
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]
```

--------------------------------

### Builder Picks Next Work Item

Source: https://specs.md/fire-flow/quick-start

The builder agent automatically selects the next work item based on dependencies. This output shows the start of a work item execution.

```text
Starting work item: user-schema
Mode: Autopilot (0 checkpoints)

Executing...
```

--------------------------------

### Work Item Structure Example

Source: https://specs.md/fire-flow/work-items

Defines the core attributes of a work item, including its ID, intent, title, description, complexity, execution mode, dependencies, and status.

```yaml
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 Markdown Documentation

Source: https://specs.md/fire-flow/work-items

Example of a markdown file used to document a specific work item, including its title, definition of done, technical notes, and dependencies.

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

--------------------------------

### Invoke FIRE Planner Agent (Claude Code)

Source: https://specs.md/fire-flow/quick-start

Start the FIRE Planner agent within your AI coding tool by using the specified command for Claude Code.

```bash
/specsmd-fire-planner
```

--------------------------------

### Initialize project standards

Source: https://specs.md/aidlc/overview

Initializes project standards using the specsmd-master-agent.

```bash
/specsmd-master-agent project-init
```

--------------------------------

### Start or Continue Bolt Execution

Source: https://specs.md/agents/construction-agent

Initiates or resumes the execution of a 'bolt', which is a unit of work within the Construction Agent's workflow. If no bolt is active, it prompts for selection; otherwise, it continues from the last saved state.

```bash
> bolt-start
```

--------------------------------

### Build Project Command

Source: https://specs.md/agents/operations-agent

Initiates the build process for the project. This command ensures all prerequisites are met, the project is built and tested, and artifacts are created for deployment.

```bash
> build
```

--------------------------------

### Create Your First Intent

Source: https://specs.md/agents/quick-start

Use this command to initiate the creation of a new intent. The agent will ask clarifying questions to define the intent.

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

--------------------------------

### Typical Inception Workflow

Source: https://specs.md/agents/inception-agent

This sequence outlines the standard steps in the Inception Agent's workflow, from intent creation to review.

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

--------------------------------

### Delete a Spec Folder

Source: https://specs.md/simple-flow/quick-start

Use this command to remove a specific feature's spec folder if you need to start over.

```bash
rm -rf specs/{feature-name}
```

--------------------------------

### UX Guide Standards

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

Outlines the design system, color palette, typography, spacing rules, and accessibility compliance.

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

--------------------------------

### Check Memory Bank Directory

Source: https://specs.md/faq

Verify the existence of the memory-bank directory. If it's missing, initialize your project using the Master Agent.

```bash
ls memory-bank/
```

```bash
/specsmd-master-agent
> project-init
```

--------------------------------

### Verify Staging Environment

Source: https://specs.md/agents/operations-agent

Use the 'verify' command followed by the target environment name, such as 'staging', to run post-deployment checks.

```bash
> verify staging
```

--------------------------------

### Markdown Task List for Implementation Plan

Source: https://specs.md/simple-flow/three-phases

A structured markdown format for creating a step-by-step implementation plan. Features nested tasks, requirement references, and checkpoints.

```markdown
## 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_
```

--------------------------------

### Activate Operations Agent in Claude Code

Source: https://specs.md/agents/overview

Use this command to start the operations agent in Claude Code. Ensure you are in the chat interface.

```bash
/specsmd-operations-agent
```

--------------------------------

### Analyze Project Context

Source: https://specs.md/agents/master-agent

Use this command to view the current state of your project, including active intents, units in progress, and suggested next actions.

```bash
> analyze-context
```

--------------------------------

### Memory Bank Directory Structure

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

Illustrates the default directory structure of the Memory Bank after project initialization, showing organized storage for intents, bolts, standards, and operations.

```directory
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/
```

--------------------------------

### Remove specs.md Installation

Source: https://specs.md/faq

Use these commands to completely remove specs.md and its associated files from your project. This includes agent definitions and tool-specific configurations.

```bash
rm -rf .specsmd/
rm -rf .claude/commands/specsmd-*
```

--------------------------------

### Traditional Human-Prompted AI Interaction

Source: https://specs.md/methodology/sdlc-reimagined

Illustrates the conventional development flow where humans initiate and guide AI code generation through iterative prompts.

```plaintext
Human: "Write a function that calculates tax"
AI: [generates code]
Human: "Now add error handling"
AI: [updates code]
```

--------------------------------

### Orchestrator Routing

Source: https://specs.md/fire-flow/agents

Utilize the orchestrator command to let the system decide which agent is appropriate based on the current state. This is the recommended starting point for most workflows.

```bash
/specsmd-fire   # Routes to appropriate agent
```

--------------------------------

### AI-DLC Workflow Overview

Source: https://specs.md/compare/overview

Illustrates the flow of work within AI-DLC, from initial intent to traceable artifacts, highlighting the role of Bolts and DDD steps.

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

--------------------------------

### Backward Flow (Phase Regression)

Source: https://specs.md/simple-flow/three-phases

Illustrates triggers and actions for returning to a previous phase when gaps or ambiguities are found.

```text
Design  | Requirement ambiguous | "Should we update requirements?"
Tasks   | Design gap found      | "Should we update design?"
Execute | Task blocked          | "Should we add a task?"
```

--------------------------------

### OpenSpec Directory Structure

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

Illustrates the directory structure for OpenSpec, separating current state from proposed changes.

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

--------------------------------

### Create a New Intent

Source: https://specs.md/agents/inception-agent

Use the 'intent-create' command to initiate the creation of a new intent by providing a high-level goal.

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

--------------------------------

### Decomposing Intents into Units using Inception Agent

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

Demonstrates the command to initiate the Inception Agent for decomposing intents into units.

```bash
/specsmd-inception-agent units
```