specsmd

specs.md - by fabriqa

AI-native development framework with pluggable flows for every use case.

Choose the flow that matches your project needs: Ideation for creative brainstorming, Simple for quick specs, FIRE for adaptive execution, or AI-DLC for full methodology with DDD.

---

VS Code Extension

Track your progress with our sidebar extension for VS Code and compatible IDEs.

AI-DLC Flow:

FIRE Flow:

Note: Works with any VS Code-based IDE including Cursor, Google Antigravity, Windsurf, and others.

Features:

• Flow switcher for AI-DLC and FIRE views
• Active run/bolt tracking with progress indicators
• Intent and work item visualization
• Click-to-open spec files

Install from:

• VS Code Marketplace — VS Code, GitHub Codespaces
• Open VSX Registry — Cursor, Windsurf, Amazon Kiro, Google Antigravity, VSCodium, Gitpod, Google IDX
• GitHub Releases (VSIX) — Manual installation

---

Four Flows, Every Use Case

Flow	Optimized For	Agents	Checkpoints
Ideation	Creative brainstorming, concept shaping, product discovery	1	0 (non-blocking)
Simple	Spec generation, prototypes	1	3 (phase gates)
FIRE	Adaptive execution, brownfield, monorepos	3	Adaptive (0-2)
AI-DLC	Full traceability, DDD, regulated environments	4	Comprehensive

Not sure which flow? If you want to explore ideas before committing to a feature, use Ideation. If you want quick specs without execution tracking, use Simple. If you want adaptive execution that right-sizes rigor, use FIRE. If you need comprehensive documentation and DDD, use AI-DLC.

---

Quick Start

Prerequisites

• Node.js 18 or higher
• An AI coding tool (Claude Code, Cursor, GitHub Copilot, or Google Antigravity)

Installation

[!NOTE] Always use npx to get the latest version. Do not install globally with npm.

npx specsmd@latest install

During installation, select your flow:

? Select a development flow:
  Ideation - Creative ideation: Spark → Flame → Forge idea generation and shaping
  Simple - Spec generation only (requirements, design, tasks)
❯ FIRE - Adaptive execution, brownfield & monorepo ready
  AI-DLC - Full methodology with DDD (comprehensive checkpoints)

The installer detects your AI coding tools and sets up agent definitions, slash commands, and project structure for your selected flow.

Dashboard Web

Track specsmd flow state from a local browser dashboard:

npx specsmd@latest dashboard

Useful options:

npx specsmd@latest dashboard --flow fire --path . --no-open
npx specsmd@latest dashboard --host 127.0.0.1 --port 4317

Prefer the terminal dashboard?

npx specsmd@latest dashboard-cli
npx specsmd@latest dashboard-cli --flow fire --path . --refresh-ms 1000

Install VS Code Extension (Optional)

Track your progress visually with our sidebar extension:

• VS Code Marketplace — VS Code, GitHub Codespaces
• Open VSX Registry — Cursor, Windsurf, Amazon Kiro, Google Antigravity

Verify Installation

# Check the manifest
cat .specsmd/manifest.yaml

# List installed agents (adjust path for your flow)
ls .specsmd/ideation/agents/  # Ideation flow
ls .specsmd/fire/agents/      # FIRE flow
ls .specsmd/simple/agents/    # Simple flow
ls .specsmd/aidlc/agents/     # AI-DLC flow

---

Ideation Flow

Creative ideation. Spark → Flame → Forge. Give it a topic and get genuinely diverse ideas in 30 seconds — no setup, no technique selection, no friction.

/specsmd-ideation   # Full guided flow (orchestrator)
/specsmd-spark      # Direct idea generation
/specsmd-flame      # Direct idea evaluation
/specsmd-forge      # Direct concept shaping

Three Skills:

1. Spark → spark-bank.md - Rapid idea generation with anti-bias domain wheel (12 domains, deep thinking per batch)
2. Flame → flame-report.md - Multi-perspective evaluation with Six Hats + impact/feasibility scoring + shortlist
3. Forge → concept-brief.md - Concept development using Disney Creative Strategy (Dreamer → Realist → Critic)

Best for: Product discovery, finding novel angles before committing to a feature, brainstorming sessions, early-stage thinking.

Output structure:

.specs-ideation/
└── sessions/
    └── {topic-slug}-{YYYYMMDD}/
        ├── session.yaml         # Session state (resumable)
        ├── spark-bank.md        # Ideas generated
        ├── flame-report.md      # Evaluation results
        └── concept-briefs/      # Shaped concepts
            └── {concept-name}.md

Ideation Flow Documentation →

---

Simple Flow

Spec generation only. Generate requirements, design, and task documents without execution tracking.

/specsmd-agent

Three Phases:

1. Requirements → requirements.md - User stories, EARS criteria
2. Design → design.md - Technical design, architecture diagrams
3. Tasks → tasks.md - Implementation checklist

Best for: Prototypes, MVPs, spec handoff, projects that don't need AI-assisted execution.

Output structure:

specs/
└── {feature-name}/
    ├── requirements.md
    ├── design.md
    └── tasks.md

Simple Flow Documentation →

---

FIRE Flow

Fast Intent-Run Engineering. Adaptive execution with brownfield and monorepo support. Ships in hours with 0-2 checkpoints based on task complexity.

/fire-orchestrator   # Entry point, routing
/fire-planner        # Intent capture, work item decomposition
/fire-builder        # Run execution, walkthrough generation

Key Features:

• Adaptive checkpoints - Autopilot (0), Confirm (1), or Validate (2) based on complexity
• First-class brownfield - Auto-detects existing patterns and conventions
• Monorepo support - Hierarchical standards with module-specific overrides
• Walkthrough generation - Documents every change automatically

Best for: Teams who hate friction, brownfield projects, monorepos.

Output structure:

.specs-fire/
├── state.yaml           # Central state tracking
├── standards/           # Project standards
├── intents/             # Intent documentation
├── runs/                # Run logs
└── walkthroughs/        # Generated documentation

FIRE Flow Documentation →

---

AI-DLC Flow

Full methodology. Implements the AI-Driven Development Lifecycle with Domain-Driven Design and comprehensive traceability.

/specsmd-master-agent       # Orchestrates & navigates
/specsmd-inception-agent    # Requirements, stories, bolt planning
/specsmd-construction-agent # Execute bolts through DDD stages
/specsmd-operations-agent   # Deploy, verify, monitor

Three Sequential Phases:

1. Inception - Capture intents, elaborate requirements, decompose into units
2. Construction - Execute bolts: Model → Design → ADR → Implement → Test
3. Operations - Deploy, verify, and monitor

Best for: Complex domains, multi-team coordination, regulated environments.

Output structure:

memory-bank/
├── standards/           # Project standards
├── intents/             # Intent documentation
│   └── {intent-name}/
│       ├── requirements.md
│       ├── system-context.md
│       └── units/
├── bolts/               # Bolt execution records
└── operations/          # Deployment context

AI-DLC Flow Documentation →

---

Why specs.md?

Four Flows for Every Use Case

From creative brainstorming (Ideation) to quick specs (Simple) to adaptive execution (FIRE) to full methodology (AI-DLC). Choose the flow that matches your project needs.

Adaptive Checkpoints (FIRE)

Right-sizes the rigor. Simple bug fixes burn through fast. Critical changes get design review. You configure your autonomy preference.

First-Class Brownfield & Monorepo (FIRE)

Auto-detects existing patterns and respects your conventions. Hierarchical standards with module-specific overrides.

Full DDD Methodology (AI-DLC)

Domain-Driven Design is integral to Construction, not an optional add-on. Every decision documented with full traceability.

Tool Agnostic

Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere—no vendor lock-in.

Context Engineering

Structured artifacts provide persistent context for AI agents. Agents reload context each session—no more lost knowledge.

---

Supported Tools

specs.md is IDE and AI-agnostic—your specs and agents are portable markdown files that work anywhere.

Tool	Integration
Claude Code	Slash commands in .claude/commands/
Cursor	Rules in .cursor/rules/ (.mdc format)
GitHub Copilot	Agents in .github/agents/ (.agent.md format)
Google Antigravity	Agents in .agent/agents/
Windsurf	Rules in .windsurf/rules/
Amazon Kiro	Steering in .kiro/steering/
Gemini CLI	Commands in .gemini/commands/ (.toml format)
Cline	Rules in .clinerules/
Roo Code	Commands in .roo/commands/
OpenAI Codex	Config in .codex/
OpenCode	Agents in .opencode/agent/

---

Troubleshooting

Ensure specs.md is installed correctly:

# Check for your flow
ls .specsmd/ideation/agents/  # Ideation
ls .specsmd/fire/agents/      # FIRE
ls .specsmd/simple/agents/    # Simple
ls .specsmd/aidlc/agents/     # AI-DLC

If the directory is empty or missing, reinstall:

npx specsmd@latest install

Check if the artifacts directory exists for your flow:

ls .specs-ideation/  # Ideation flow
ls .specs-fire/      # FIRE flow
ls specs/            # Simple flow
ls memory-bank/      # AI-DLC flow

If missing, initialize your project using the appropriate agent.

Ensure standards are defined in your flow's standards directory:

• Ideation: .specs-ideation/standards/ (optional — used for context-aware ideation)
• FIRE: .specs-fire/standards/
• AI-DLC: memory-bank/standards/

Run project initialization if missing.

---

Q: Which flow should I choose?