AI-native software development with multi-agent orchestration.
specsmd implements the AI-Driven Development Lifecycle (AI-DLC) methodology as a set of markdown-based agents that work with your favorite AI coding tools.
Track your AI-DLC progress with our sidebar extension for VS Code and compatible IDEs.
Note: Works with any VS Code-based IDE including Cursor, Google Antigravity, Windsurf, and others.
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
- Node.js 18 or higher
- An AI coding tool (Claude Code, Cursor, GitHub Copilot, or Google Antigravity)
Note
Do not use npm if you want to always get the latest version. Use the npx command below.
npx specsmd@latest installThe installer detects your AI coding tools (Claude Code, Cursor, GitHub Copilot) and sets up:
- Agent definitions and skills
- Memory bank structure for context persistence
- Slash commands for easy agent invocation
# Check the manifest
cat .specsmd/manifest.yaml
# List installed agents
ls .specsmd/aidlc/agents/Open your AI Assisted Tool (Claude Code, Cursor, GitHub Copilot) and run the following commands:
# Start the Master Agent
/specsmd-master-agent
# Then type:
project-initThis guides you through establishing:
- Tech Stack - Languages, frameworks, databases, infrastructure
- Coding Standards - Formatting, linting, naming, testing strategy
- System Architecture - Architecture style, API design, state management
- UX Guide - Design system, styling, accessibility (optional)
- API Conventions - API style, versioning, response formats (optional)
/specsmd-inception-agent intent-createAn Intent is your high-level goal:
- "User authentication system"
- "Product catalog with search"
- "Payment processing integration"
The agent will:
- Ask clarifying questions to minimize ambiguity
- Elaborate into user stories and NFRs
- Define system context
- Decompose into loosely-coupled units
# Plan bolts for your stories
/specsmd-inception-agent bolt-plan
# Execute a bolt
/specsmd-construction-agent bolt-startEach bolt goes through validated stages:
- Domain Model - Model business logic using DDD principles
- Technical Design - Apply patterns and make architecture decisions
- ADR Analysis - Document significant decisions (optional)
- Implement - Generate production code
- Test - Verify correctness with automated tests
Human validation happens at each stage gate.
AI-DLC is a reimagined software development methodology where AI drives the conversation and humans validate. Unlike traditional Agile where iterations span weeks, AI-DLC operates in Bolts - rapid iterations measured in hours or days.
"Traditional development methods were built for human-driven, long-running processes. AI-DLC reimagines the development lifecycle with AI as a central collaborator, enabling rapid cycles measured in hours or days rather than weeks."
| Aspect | Agile/Scrum | AI-DLC |
|---|---|---|
| Iteration duration | Weeks (Sprints) | Hours/days (Bolts) |
| Who drives | Human-driven, AI assists | AI-driven, human-validated |
| Design techniques | Out of scope | Integrated (DDD, TDD, BDD) |
| Task decomposition | Manual | AI-powered |
| Phases | Repeating sprints | Rapid three-phase cycles (Inception → Construction → Operations) |
| Rituals | Daily standups, retrospectives | Mob Elaboration, Mob Construction |
specsmd provides four specialized agents that guide you through the entire development lifecycle:
flowchart TB
MA[Master Agent<br/>Orchestrates & Navigates] --> IA[Inception Agent]
MA --> CA[Construction Agent]
MA --> OA[Operations Agent]
IA --> CA --> OA
style MA fill:#8B5CF6,stroke:#7C3AED,color:#fff
style IA fill:#818CF8,stroke:#6366F1,color:#fff
style CA fill:#34D399,stroke:#10B981,color:#fff
style OA fill:#FBBF24,stroke:#F59E0B,color:#fff
| Phase | Agent | Purpose | Key Outputs |
|---|---|---|---|
| Inception | Inception Agent | Capture intents, elaborate requirements, decompose into units | User stories, NFRs, Unit definitions, Bolt plans |
| Construction | Construction Agent | Execute bolts through domain design → logical design → code → test | Domain models, Technical designs, Code, Tests |
| Operations | Operations Agent | Deploy, verify, and monitor | Deployment units, Monitoring, Runbooks |
A high-level statement of purpose that encapsulates what needs to be achieved - whether a business goal, feature, or technical outcome. It serves as the starting point for AI-driven decomposition.
A cohesive, self-contained work element derived from an Intent. Units are loosely coupled and can be developed independently. Analogous to a Subdomain (DDD) or Epic (Scrum).
The smallest iteration in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are hours to days. Each bolt encapsulates a well-defined scope of work.
| Type | Best For | Stages |
|---|---|---|
| DDD Construction | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
| Simple Construction | UI, integrations, utilities | Plan → Implement → Test |
File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.
Project decisions that inform AI code generation. Standards ensure consistency across all generated code and documentation.
After installation:
.specsmd/
├── manifest.yaml # Installation manifest
└── aidlc/ # AI-DLC flow
├── agents/ # Agent definitions
├── skills/ # Agent capabilities
├── templates/ # Artifact templates
│ └── standards/ # Standards facilitation guides
└── memory-bank.yaml # Memory bank schema
memory-bank/ # Created after project-init
├── intents/ # Your captured intents
│ └── {intent-name}/
│ ├── requirements.md
│ ├── system-context.md
│ └── units/
├── bolts/ # Bolt execution records
├── standards/ # Project standards
│ ├── tech-stack.md
│ ├── coding-standards.md
│ └── ...
└── operations/ # Deployment context
/specsmd-master-agent| Command | Purpose |
|---|---|
project-init |
Initialize project with standards |
analyze-context |
View current project state |
route-request |
Get directed to the right agent |
explain-flow |
Learn about AI-DLC methodology |
answer-question |
Get help with any specsmd question |
/specsmd-inception-agent| Command | Purpose |
|---|---|
intent-create |
Create a new intent |
intent-list |
List all intents |
requirements |
Elaborate intent requirements |
context |
Define system context |
units |
Decompose into units |
story-create |
Create stories for a unit |
bolt-plan |
Plan bolts for stories |
review |
Review inception artifacts |
/specsmd-construction-agent| Command | Purpose |
|---|---|
bolt-start |
Start/continue executing a bolt |
bolt-status |
Check bolt progress |
bolt-list |
List all bolts |
bolt-replan |
Replan bolts if needed |
/specsmd-operations-agent| Command | Purpose |
|---|---|
build |
Build the project |
deploy |
Deploy to environment |
verify |
Verify deployment |
monitor |
Set up monitoring |
Built from the ground up for AI-driven development. AI-DLC is a reimagination based on first principles, not a retrofit of existing methods.
Validation at each stage catches errors early before they cascade downstream. Each validation transforms artifacts into rich context for subsequent stages.
DDD, TDD, and BDD are integral to the methodology - not optional add-ons. This addresses the "whitespace" in Agile that has led to quality issues.
Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
Specs and Memory Bank provide structured context for AI agents. Agents reload context each session - no more lost knowledge.
| Tool | Status | Installation |
|---|---|---|
| Claude Code | Full support | Slash commands in .claude/commands/ |
| Cursor | Full support | Rules in .cursor/rules/ (.mdc format) |
| GitHub Copilot | Full support | Agents in .github/agents/ (.agent.md format) |
| Google Antigravity | Full support | Agents in .agent/agents/ |
| Windsurf | Full support | Workflows in .windsurf/workflows/ |
| Amazon Kiro | Full support | Steering in .kiro/steering/ |
| Gemini CLI | Full support | Commands in .gemini/commands/ (.toml format) |
| Cline | Full support | Rules in .clinerules/ |
| Roo Code | Full support | Commands in .roo/commands/ |
| OpenAI Codex | Full support | Config in .codex/ |
| OpenCode | Full support | Agents in .opencode/agent/ |
Agent commands not recognized
Ensure specs.md is installed correctly:
ls .specsmd/aidlc/agents/If the directory is empty or missing, reinstall:
npx specsmd@latest installMemory Bank artifacts missing
Check if the memory-bank directory exists:
ls memory-bank/If missing, run project initialization:
/specsmd-master-agent
> project-init
Standards not being followed in generated code
Ensure standards are defined in memory-bank/standards/:
tech-stack.mdcoding-standards.mdarchitecture.md
If missing or incomplete, use the Master Agent to define them:
/specsmd-master-agent
> project-init
Q: Agents don't seem to remember previous context? Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.
Q: How do I reset project state?
Clear the memory-bank/ directory to reset all artifacts. To remove specsmd entirely, delete the .specsmd/ directory and tool-specific command files.
Q: Can I use specsmd with existing Agile workflows? AI-DLC is designed as a reimagination, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.
Q: What project types is this suited for? specsmd is designed for building complex systems that demand architectural complexity, trade-off management, and scalability. Simpler systems may be better suited for low-code/no-code approaches.
MIT License - see LICENSE for details.
Built with AWS' AI-DLC methodology by the specs.md team.