specs.md (AI-DLC) — Workflow

Three Flows

Simple Flow

3 phase gates, 1 agent.

FIRE Flow (Adaptive Checkpoints)

Checkpoint count based on complexity:

• 0 checkpoints (Autopilot): Simple task
• 1 checkpoint (Confirm): Medium complexity
• 2 checkpoints (Validate): Complex task

AI-DLC Flow (Full Lifecycle)

DDD Bolt Execution (AI-DLC Construction Phase)

Each bolt goes through:

1. Model — Domain model definition
2. Design — Technical design
3. ADR — Architecture Decision Record
4. Implement — Code implementation
5. Test — Test creation and execution

Approval Gates

Master Agent Routing (AI-DLC)

[1] Standards exist? → No → NEW USER FLOW
                    → Yes → RETURNING USER FLOW

[NEW USER FLOW]
  [1a] execute explain skill → Introduce AI-DLC
  [1b] execute project-init skill → Setup standards

[RETURNING USER FLOW]
  [2] analyze skill → Determine project state
  [3] route skill → Route to appropriate agent

Spec Format

Markdown. Requirements use EARS-style criteria. AI-DLC uses memory-bank.yaml as artifact schema definition.

specs.md (AI-DLC) — Memory & Context

Memory Architecture

specs.md maintains separate memory systems per flow, each stored in distinct directories.

FIRE Flow Memory

Central State File

.specs-fire/state.yaml — single source of truth for all FIRE operations.

Top-level sections:

• project — name, description, created timestamp, fire_version
• workspace — type (greenfield/brownfield), structure (monolith/monorepo/multi-part), autonomy_bias (autonomous/balanced/controlled), run_scope_preference (learned from history), scanned_at
• intents[] — list of intents each with id, title, status (pending/in_progress/completed), work_items[]

FIRE Directory Structure

.specs-fire/
├── state.yaml            ← central state (source of truth)
├── standards/            ← project standards (monorepo-aware)
│   ├── constitution.md   ← root-level only, never overridden
│   ├── tech-stack.md
│   ├── coding-standards.md
│   └── testing-standards.md
├── intents/              ← intent documents
└── runs/                 ← execution walkthroughs and logs

Monorepo Standards Hierarchy

FIRE supports hierarchical standards for monorepos:

• constitution.md is always resolved from root — never module-level overridden
• Other standard files use override semantics: module-level file overrides root if present
• Discovery: presence of .specs-fire/standards/ at any path defines a scope

AI-DLC Flow Memory

memory-bank.yaml

.specsmd/aidlc/memory-bank.yaml — artifact schema definition that all four AI-DLC agents read on activation.

Defines:

• structure[] — directories created at project init (intents/, bolts/, standards/, operations/)
• project_config — path to memory-bank/project.yaml, fields: project_type, initialized_at
• conventions.timestamps — ISO 8601 with time+timezone required on ALL date fields
• naming — zero-padded 3-digit prefix conventions for intents (NNN), units (UUU), stories (SSS), bolts (BBB)
• schema — canonical paths for all artifact types

Artifact path schema:

memory-bank/intents/{NNN}-{intent-name}/
memory-bank/intents/{NNN}-{intent-name}/units/{UUU}-{unit-name}/
memory-bank/intents/{NNN}-{intent-name}/units/{UUU}-{unit-name}/stories/{SSS}-{title-slug}.md
memory-bank/bolts/{BBB}-{unit-name}/

Dynamic vs. Static Structure

Directories created at project init (static):

• intents/, bolts/, standards/, operations/

Directories created dynamically by agents:

• intents/{NNN}-{intent-name}/ — created by Inception when intent is created
• intents/{NNN}-{intent-name}/units/ — created when units are defined
• intents/{NNN}-{intent-name}/units/{unit-name}/stories/ — created when stories are added

context-config.yaml

.specsmd/aidlc/context-config.yaml — maps which context files each agent must/may load.

On missing critical context: construction agent warns and offers to continue without standards. Inception continues with defaults.

AI-DLC Bolt Artifacts

Each bolt in memory-bank/bolts/{BBB}-{unit-name}/ contains:

• bolt.md — bolt instance metadata
• ddd-01-domain-model.md — Stage 1 artifact
• ddd-02-technical-design.md — Stage 2 artifact
• adr-{n}-{slug}.md — Stage 3 artifacts (0 or more, optional)
• Source code — Stage 4 artifact (in project tree, not bolt dir)
• ddd-03-test-report.md — Stage 5 artifact

Bolt Types Available

Simple Flow Memory

No persistent state file. Artifacts stored as markdown in user-defined specs/{feature}/ directory:

• specs/{feature}/requirements.md
• specs/{feature}/design.md
• specs/{feature}/tasks.md

Cross-Session Continuity

All three flows persist state via filesystem files. Agents read state files on activation, enabling session resumption:

• FIRE: Orchestrator reads .specs-fire/state.yaml to detect active runs
• AI-DLC: Master agent reads memory-bank.yaml to detect initialization status; Construction agent reads bolt files to detect in-progress stages
• Simple: No explicit resumption mechanism; users re-invoke agents pointing at existing spec files

specs.md (AI-DLC) — Orchestration

Orchestration Model

specs.md is a multi-flow, sequential multi-agent system. Each flow uses a dedicated set of agents arranged in a linear handoff chain. There is no parallel fan-out, no swarm coordination, and no shared agent pool across flows.

Flow-Level Orchestration

Simple Flow

Single agent, three sequential phases with phase gates.

/specsmd-agent (phase 1) → requirements.md
         ↓ [user approval gate]
/specsmd-agent (phase 2) → design.md
         ↓ [user approval gate]
/specsmd-agent (phase 3) → tasks.md

No inter-agent communication. One agent handles all three phases.

FIRE Flow

Three specialized agents in a state-machine chain:

/fire-orchestrator
    ↓ reads .specs-fire/state.yaml
    ↓ new project → project-init skill
    ↓ active run → route to Builder Agent
    ↓ no active run → [2]

/fire-planner
    ↓ creates intent documents in .specs-fire/intents/
    ↓ decomposes intent into work items
    ↓ determines complexity → checkpoint count

/fire-builder
    ↓ executes work items
    ↓ produces walkthroughs in .specs-fire/runs/
    ↓ 0/1/2 checkpoints based on complexity

Checkpoint adaptation logic (assessed by orchestrator):

• Simple task → 0 checkpoints (Autopilot: full autonomous execution)
• Medium complexity → 1 checkpoint (confirm before implementation)
• Complex task → 2 checkpoints (validate at start AND end)

AI-DLC Flow

Four named specialist agents in a lifecycle sequence:

/specsmd-master-agent
    ↓ reads memory-bank.yaml
    ↓ not initialized → explain skill → project-init skill
    ↓ initialized → analyze skill → route skill

/specsmd-inception-agent
    ↓ vibe-to-spec: NL → structured intents
    ↓ creates intents/{NNN}-{name}/ with units and stories
    ↓ requirements.md per unit (EARS-format)

/specsmd-construction-agent
    ↓ reads context-config.yaml for standards
    ↓ bolt-list skill → user selects bolt
    ↓ executes bolt stages (DDD: Model → Design → ADR → Implement → Test)
    ↓ human checkpoint after EVERY stage

/specsmd-operations-agent
    ↓ deployment context
    ↓ verification and monitoring

Agent Skill Architecture (AI-DLC)

Each agent delegates to named skills loaded from .specsmd/aidlc/skills/{agent}/:

Master Agent Skills:

Construction Agent Skills:

Inception Agent Skills (selected):

Handoff Protocol

Agents do not call each other programmatically. Handoff is always via the user:

1. Master agent's route-request skill tells the user which agent to invoke next
2. User manually invokes the next agent command
3. Receiving agent reads shared filesystem state (memory-bank, state.yaml) to get context

There is no automated spawning, message passing, or shared runtime between agents.

DDD Bolt Execution (Detail)

The Construction Agent's DDD bolt enforces strict sequential stages with mandatory human gates:

Stage 1: Domain Model → ddd-01-domain-model.md → [HUMAN CHECKPOINT]
Stage 2: Technical Design → ddd-02-technical-design.md → [HUMAN CHECKPOINT]
Stage 3: ADR Analysis (optional) → adr-{n}-{slug}.md → [HUMAN CHECKPOINT if run]
Stage 4: Implement → source code → [HUMAN CHECKPOINT]
Stage 5: Test → tests + ddd-03-test-report.md → [HUMAN CHECKPOINT]

Rules enforced by bolt type definition:

• Never auto-advance to next stage without explicit user confirmation
• Never skip Domain Model or Technical Design before implementation
• Each stage artifact written to memory-bank/bolts/{BBB}-{unit-name}/

Orchestration Comparison

specs.md (AI-DLC) — UI / CLI Surface

CLI Binary: specsmd

Binary: specsmd (defined in src/package.json as ./bin/cli.js) Install: npm install -g specsmd or npx specsmd@latest <command> Framework: Node.js + Commander.js

Subcommands

Interactive Installer (specsmd install)

4-step wizard with terminal prompts (uses prompts npm library):

Step 1 — Auto-detect tools: Scans filesystem for known AI tool config directories (.claude/, .cursor/, .github/copilot-instructions.md, etc.). Marks detected tools with (detected) indicator.

Step 2 — Select tools (multiselect): User toggles tools with [Space]. Detected tools are pre-selected. Full list of supported targets:

• Claude Code (ClaudeInstaller.js)
• Cursor (CursorInstaller.js)
• GitHub Copilot (CopilotInstaller.js)
• Cline (ClineInstaller.js)
• Roo (RooInstaller.js)
• Windsurf (WindsurfInstaller.js)
• Google Antigravity (AntigravityInstaller.js)
• Gemini CLI (GeminiInstaller.js)
• Kiro (KiroInstaller.js)
• OpenCode (OpenCodeInstaller.js)
• Codex (CodexInstaller.js)

Step 3 — Select flow (single-select):

• Simple — 3-phase sequential (requirements → design → tasks)
• FIRE — Fast Intent-Run Engineering with adaptive checkpoints
• AI-DLC — Full lifecycle with multi-agent orchestration

Step 4 — Deploy: Writes agent/command files to the selected tool's configuration directory. Displays file count on completion.

Terminal Dashboard (specsmd dashboard)

A live Ink-based TUI (React in terminal) that renders flow state in real time.

Options

Dashboard Features

Dashboard submodules (from src/lib/dashboard/):

• flow-detect.js — auto-detects which flow is active by scanning for .specs-fire/, .specsmd/, or specs/ directories
• tui/ — Ink component tree for terminal rendering
• fire/ — FIRE-specific visualizations (intent list, run progress, checkpoint status)
• aidlc/ — AI-DLC bolt tracking and stage completion indicators
• simple/ — Simple flow phase progress
• git/ — Git worktree integration and branch display
• runtime/ — File watcher (chokidar) for live state refresh

Dashboard uses chokidar for filesystem watching so updates appear without manual refresh.

VS Code Extension

• Marketplace: fabriqaai.specsmd (Visual Studio Marketplace)
• Also published to Open VSX Registry
• Provides in-editor access to specsmd agents and flows
• Extension wraps the same flow commands within VS Code's agent/extension surface

AI Tool Command Files (Post-Install)

After specsmd install, the installer deploys markdown command files to each selected tool's configuration directory.

For Claude Code: .claude/commands/ — one .md file per agent/command For Cursor: .cursor/rules/ or cursor-specific structure For Copilot: .github/ copilot instructions structure

Each command file is a self-contained agent prompt with embedded skill references pointing to the shared .specsmd/ or .specs-fire/ directories.

Analytics

specsmd install sends anonymous analytics via Mixpanel (listed as a dependency). Respects opt-out environment variables. Tracks: installer started, IDEs confirmed, flow selected, install completed/failed.