Skip to main content

​
General

specs.md is an AI-native development framework with pluggable flows for every use case. It provides markdown-based agents that work with your favorite AI coding tools (Claude Code, Cursor, GitHub Copilot) to guide software development.We offer three flows:
  • Simple Flow - Spec generation only (requirements, design, tasks)
  • FIRE Flow - Adaptive execution with brownfield & monorepo support
  • AI-DLC Flow - Full methodology with comprehensive traceability
Choose your flow →
FlowOptimized ForCheckpoints
SimpleQuick specs, prototypes, handoff to other teams3 (phase gates)
FIREAdaptive execution, brownfield, monoreposAdaptive
AI-DLCFull traceability, comprehensive documentationComprehensive
Quick decision:
  • Just need specs without execution tracking? → Simple
  • Want adaptive rigor that right-sizes to complexity? → FIRE
  • Need comprehensive documentation and fixed workflows? → AI-DLC
Detailed comparison →
FIRE (Fast Intent-Run Engineering) is an Adaptive Spec-Driven Development flow. It analyzes work complexity and your config preference to decide when to ask and when to burn through.
  • Adaptive checkpoints: Based on work complexity + your autonomy preference
  • Brownfield-first: Analyzes your existing structure and respects your patterns
  • Monorepo support: Hierarchical standards with module-specific overrides
  • Walkthrough generation: Every change documented automatically
  • Design docs when needed: Implementation plan for simple tasks, design docs for complex ones
Learn more about FIRE →
AI-DLC is a software development methodology developed by AWS where AI drives the conversation and humans validate. Unlike traditional Agile with week-long sprints, AI-DLC operates in “Bolts” - rapid iterations measured in hours or days.Key principles:
  • Reimagine, don’t retrofit - AI-DLC is built from first principles, not AI bolted onto Agile
  • Reversed conversation - AI proposes, humans validate (not vice versa)
  • DDD as core - Domain-Driven Design is integral, not optional
Learn more about AI-DLC →
specs.md supports:
  • Claude Code - Full support with slash commands
  • Cursor - Full support with rules
  • GitHub Copilot - Full support with agents
  • Google Antigravity - Full support with agents
  • Any AI assistant - Works with any tool that can read markdown prompts
Yes, specs.md is open source under the MIT license. You can use it freely in personal and commercial projects. You only pay for your AI API tokens.

​
FIRE Flow

FIRE adapts oversight to complexity with three modes:
ModeCheckpointsUse For
Autopilot0Bug fixes, minor updates, well-defined changes
Confirm1Standard features, moderate complexity
Validate2Security, payments, core architecture
Learn more about execution modes →
FIRE treats existing codebases as first-class citizens:
  • Auto-detection: Scans your codebase to infer tech stack and conventions
  • Search before create: Extends existing modules rather than duplicating
  • Respect patterns: Follows existing naming and folder structures
  • Minimal changes: Targeted edits, no unnecessary rewrites
Learn more about brownfield support →
FIRE has first-class monorepo support with hierarchical standards:
  • Root standards: Project-wide defaults
  • Module overrides: Per-module tech stack and conventions
  • Constitution: Universal policies (always inherited, never overridden)
  • AI detection: Automatically detects language/framework per module
Learn more about monorepo support →
Walkthroughs are generated documentation after each work item completes:
  • Summary of what changed
  • Files created/modified/deleted
  • Key decisions made
  • Verification steps
  • Test coverage
They enable async review—you don’t need to watch AI code in real-time.
Consider AI-DLC instead if:
  • You have a large team requiring coordination
  • Your domain logic is complex and needs DDD
  • You’re in a regulated environment requiring extensive documentation
  • Multiple stakeholders need to review and approve changes
Flow comparison →

​
Why AI-DLC? (The Agentic Age)

Traditional methods were built for longer iteration durations (months and weeks), leading to rituals like daily standups and retrospectives. With AI, iteration cycles are measured in hours or days.Retrofitting AI into Agile limits its potential and reinforces outdated inefficiencies. We need automobiles, not faster horse chariots.Read: The AI-Native SDLC: Reimagined →
  • Two weeks is no longer fast - AI produces working prototypes in hours
  • Story points are meaningless - AI execution time bears no relation to human effort
  • Sprint boundaries create artificial delays - Completed work waits for ceremonies
  • Velocity fluctuates wildly - Based on AI tool usage, not team capability
AI-DLC replaces sprints with “Bolts” - hours or days, not weeks.
V-Bounce is a model from the Crowdbotics research paper that introduced a key insight: humans shift from primary implementers to validators and verifiers.AI handles planning, coding, and testing. Humans focus on requirements, architecture, and continuous validation.
In traditional development, humans prompt AI to complete tasks. In AI-DLC, the conversation is reversed:Traditional: Human asks → AI respondsAI-DLC: AI proposes breakdown, trade-offs, designs → Human validates, approves, redirectsThink of it like Google Maps: you set the destination, AI provides step-by-step directions, you maintain oversight.
These are AI-DLC’s collaborative rituals:
  • Mob Elaboration (Inception): Product managers, developers, QA collaborate with AI to refine requirements into user stories. What took months now takes hours.
  • Mob Construction (Construction): Teams work in parallel after domain modeling, with AI generating component models while team provides real-time clarification.
Both happen in a single room with shared screen for deep alignment.

​
Comparisons

Spec Kit is a toolkit with agent prompts (/speckit.specify, /speckit.plan, /speckit.tasks) for 15+ AI assistants.specs.md is a full methodology with phase-based agents, Mob rituals, and DDD integration.Choose Spec Kit for a 4-phase workflow with minimal learning curve. Choose specs.md for complex systems needing formal methodology structure.specs.md (Simple Flow) provides Kiro-style Requirements → Design → Tasks workflow.Full comparison →
Both target complex systems:
  • BMAD: 19+ role-based agents (Analyst, PM, Architect, Dev, QA…)
  • specs.md: 3 phase-based agents (Master, Inception, Construction, Operations)
Choose BMAD for maximum agent customization. Choose specs.md for formal AWS methodology with simpler agent model.Full comparison →
Kiro is a full IDE with built-in spec-driven development and agent hooks.specs.md is IDE-agnostic—works with any editor and AI model.
Aspectspecs.mdKiro
IDEAnyKiro only
AI ModelAnyClaude Sonnet only
PricingFree + API tokens$19-39/month
specs.md (Simple Flow) provides a Kiro-style workflow that works with any IDE.Full comparison →
OpenSpec is brownfield-first, focused on change management with excellent token efficiency.specs.md provides full lifecycle support (Inception → Operations) for both greenfield and brownfield.Choose OpenSpec for high-volume small changes. Choose specs.md for full lifecycle complex systems.Full comparison →
No. specs.md is a complete methodology that includes everything you need:
  • Formal phases (Inception → Construction → Operations)
  • Defined rituals (Mob Elaboration, Mob Construction)
  • Design integration (DDD as core)
  • Memory Bank for persistent context
  • Phase-based agents
Other tools focus on specifications only. AI-DLC is a full methodology.

​
Installation

npx specsmd@latest install
The installer automatically detects your AI coding tools and sets up the appropriate agents.Full installation guide →
No. Always use npx specsmd@latest install to ensure you get the latest version. Global installation may result in using an outdated version.
specs.md creates a .specsmd/ directory with:
  • Agent definitions
  • Skills and capabilities
  • Templates for artifacts
  • Memory bank schema
It also creates tool-specific files (e.g., .claude/commands/ for Claude Code).

​
Usage

Each agent invocation starts fresh. Agents read context from the Memory Bank at startup.Solution: Ensure artifacts are saved after each step. The Memory Bank is how context persists between sessions.
To reset all artifacts, clear the memory-bank/ directory:
rm -rf memory-bank/
To remove specs.md entirely:
rm -rf .specsmd/
rm -rf .claude/commands/specsmd-*  # For Claude Code
AI-DLC is designed as a reimagination of development methodology, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.You can use specs.md alongside existing Agile processes, treating Intents as Epics and Bolts as focused work items within sprints.
Yes. AI-DLC supports brownfield development through “model elevation” - AI first converts existing code to semantic models (domain components, responsibilities, relationships) before making changes.This ensures AI understands the existing system before proposing modifications.

​
Methodology

  • Intent: High-level goal (“Build user authentication”)
  • Unit: Cohesive work element derived from Intent (“User Registration”)
  • Bolt: Smallest iteration, hours to days (“Registration Domain Model”)
Learn more about core concepts →
  1. Inception: Mob Elaboration ritual - capture intents, decompose into units and stories
  2. Construction: Mob Construction ritual - domain modeling, code generation, testing
  3. Operations: Deployment, monitoring, maintenance
Learn more about phases →
Human checkpoints are validation points within a bolt. You must approve each stage before proceeding to the next:
  1. Domain Model → CHECKPOINT → Technical Design → CHECKPOINT → etc.
This catches errors early before they cascade downstream.
TypeUse Case
DDD ConstructionComplex business logic, domain modeling
Simple ConstructionUI, integrations, utilities
The Memory Bank is a file-based storage system for all project artifacts. It maintains context across agent sessions and provides traceability between requirements, designs, code, and tests.Learn more about Memory Bank →
Unlike Agile frameworks that leave design techniques optional, AI-DLC integrates DDD as its core. AI applies domain-driven design principles during decomposition:
  • Bounded contexts
  • Aggregates and entities
  • Domain events
  • Repositories and factories
This ensures consistent, high-quality domain models regardless of which team member is working.

​
Troubleshooting

Ensure specs.md is installed correctly:
ls .specsmd/aidlc/agents/
If the directory is empty or missing, reinstall:
npx specsmd@latest install
Check if the memory-bank directory exists:
ls memory-bank/
If missing, run project initialization:
/specsmd-master-agent
> project-init
Ensure standards are defined in memory-bank/standards/:
  • tech-stack.md
  • coding-standards.md
  • architecture.md
If missing or incomplete, use the Master Agent to define them:
/specsmd-master-agent
> project-init
This is a known limitation of all spec-driven tools. Even with comprehensive specs, AI agents don’t always follow every instruction.Solutions:
  • Use checkpoints to catch errors early
  • Break work into smaller, clearer units
  • Ensure Memory Bank has complete context
  • Validate each step before proceeding

​
Resources

AI-DLC Whitepaper (AWS)

Original AWS whitepaper defining AI-DLC methodology

V-Bounce Paper (arXiv)

AI-Native Software Development Lifecycle research

GitHub Repository

Source code, issues, and contributions

Compare Tools

See how specs.md compares to alternatives