Specs.md

https://specs.md/
Admin
Specs.md is an AI-native development framework with pluggable flows for every use case, offering...
Tokens:52,245
Snippets:803
Trust Score:5.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

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

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

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

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

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

```

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

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

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

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

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

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

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

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

```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```

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

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

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

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

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

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

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

### Initialize project standards

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

Initializes project standards using the specsmd-master-agent.

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

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

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

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

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

```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### 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.
```
Tokens:
Raw