AI-native development framework with pluggable flows for every use case.
Choose the flow that matches your project needs: Simple for quick specs, FIRE for adaptive execution, or AI-DLC for full methodology with DDD.
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
| Flow | Optimized For | Agents | Checkpoints |
|---|---|---|---|
| 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 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.
- Node.js 18 or higher
- An AI coding tool (Claude Code, Cursor, GitHub Copilot, or Google Antigravity)
Note
Always use npx to get the latest version. Do not install globally with npm.
npx specsmd@latest installDuring installation, select your flow:
? Select a development flow:
Simple - Spec generation only (requirements, design, tasks)
❯ FIRE - Adaptive execution, brownfield & monorepo ready
AI-DLC - Full methodology with DDD (comprehensive checkpoints)
The installer detects your AI coding tools and sets up agent definitions, slash commands, and project structure for your selected flow.
Track your progress visually with our sidebar extension:
- VS Code Marketplace — VS Code, GitHub Codespaces
- Open VSX Registry — Cursor, Windsurf, Amazon Kiro, Google Antigravity
# Check the manifest
cat .specsmd/manifest.yaml
# List installed agents (adjust path for your flow)
ls .specsmd/fire/agents/ # FIRE flow
ls .specsmd/simple/agents/ # Simple flow
ls .specsmd/aidlc/agents/ # AI-DLC flowSpec generation only. Generate requirements, design, and task documents without execution tracking.
/specsmd-agent
Three Phases:
- Requirements →
requirements.md- User stories, EARS criteria - Design →
design.md- Technical design, architecture diagrams - 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
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
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:
- Inception - Capture intents, elaborate requirements, decompose into units
- Construction - Execute bolts: Model → Design → ADR → Implement → Test
- 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
From quick specs (Simple) to adaptive execution (FIRE) to full methodology (AI-DLC). Choose the flow that matches your project needs.
Right-sizes the rigor. Simple bug fixes burn through fast. Critical changes get design review. You configure your autonomy preference.
Auto-detects existing patterns and respects your conventions. Hierarchical standards with module-specific overrides.
Domain-Driven Design is integral to Construction, not an optional add-on. Every decision documented with full traceability.
Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere—no vendor lock-in.
Structured artifacts provide persistent context for AI agents. Agents reload context each session—no more lost knowledge.
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/ |
Agent commands not recognized
Ensure specs.md is installed correctly:
# Check for your flow
ls .specsmd/fire/agents/ # FIRE
ls .specsmd/simple/agents/ # Simple
ls .specsmd/aidlc/agents/ # AI-DLCIf the directory is empty or missing, reinstall:
npx specsmd@latest installProject artifacts missing
Check if the artifacts directory exists for your flow:
ls .specs-fire/ # FIRE flow
ls specs/ # Simple flow
ls memory-bank/ # AI-DLC flowIf missing, initialize your project using the appropriate agent.
Standards not being followed in generated code
Ensure standards are defined in your flow's standards directory:
- FIRE:
.specs-fire/standards/ - AI-DLC:
memory-bank/standards/
Run project initialization if missing.
Q: Which flow should I choose?
- Simple: Spec generation only, no execution tracking
- FIRE: Adaptive execution, brownfield/monorepo support
- AI-DLC: Full methodology with DDD and comprehensive traceability
Q: Can I switch flows after installation? Flows are independent—they're not an upgrade path. Each is designed for different use cases. You can reinstall to change flows, but artifacts are structured differently.
Q: Agents don't seem to remember previous context? Each agent invocation starts fresh. Agents read context from artifacts at startup. Ensure artifacts are saved after each step.
Q: How do I reset project state? Delete the artifacts directory for your flow:
- FIRE:
.specs-fire/ - Simple:
specs/ - AI-DLC:
memory-bank/
To remove specsmd entirely, also delete .specsmd/ and tool-specific command files.
Q: What project types is this suited for? specs.md supports everything from quick prototypes (Simple) to complex enterprise systems (AI-DLC). Choose the flow that matches your project needs.
- Documentation
- Choose Your Flow Guide
- AI-DLC Specification (AWS)
- npm Package
- GitHub Issues
- Discord Community
MIT License - see LICENSE for details.
Built by the specs.md team.