Bolts
Time-boxed execution sessions for rapid implementation
What is a Bolt?
A Bolt is a time-boxed execution session in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are completed in hours to days. Each bolt encapsulates a well-defined scope of work scoped to a Unit.
Bolt Characteristics
Rapid
Hours to days, not weeks
Focused
One story or small set of related stories
Stage-Gated
Validated checkpoints prevent errors
Complete
Produces working, tested code
Bolt Types
specs.md currently supports two bolt types:
| Type | Best For | Stages |
|---|---|---|
| DDD Construction | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
| Simple Construction | UI, integrations, utilities | Plan → Implement → Test |
Choosing a Bolt Type
Use DDD Construction Bolt when...
- Building complex domain logic with business rules
- Creating bounded contexts with rich domain models
- Implementing services that require domain expertise
- Working on core business functionality
Use Simple Construction Bolt when...
- Building frontend pages and components
- Creating simple CRUD endpoints
- Integrating with external APIs
- Writing utilities and helper modules
- Building CLI commands or scripts
DDD Construction Bolt
The most comprehensive bolt type, used for complex domain logic:
Domain Model
Model business logic using DDD principles:
- Identify aggregates, entities, value objects
- Define domain events and commands
- Establish ubiquitous language
Technical Design
Apply patterns and make architecture decisions:
- Choose implementation patterns
- Define interfaces and contracts
- Plan data structures and APIs
ADR Analysis
Document significant decisions:
- Context and problem
- Options considered
- Decision and rationale
Implement
Generate production code:
- Follow coding standards
- Apply design patterns
- Write clean, documented code
Test
Verify correctness:
- Unit tests
- Integration tests
- Acceptance tests
Simple Construction Bolt
A lightweight bolt for UI, integrations, and utilities:
Plan
Define what to build:
- Review stories and requirements
- List specific deliverables
- Identify dependencies
- Define acceptance criteria
Implement
Write the code:
- Setup file structure
- Implement core functionality
- Handle edge cases
- Add documentation
Test
Verify the implementation:
- Write unit tests
- Run test suite
- Verify acceptance criteria
- Document results
Human Checkpoints
DDD Construction Checkpoints
Simple Construction Checkpoints
Executing Bolts
Start a bolt with the Construction Agent:
/specsmd-construction-agent --unit="my-unit"The agent will:
- Show available bolts for the unit
- Ask which bolt to work on
- Guide you through each stage
- Generate artifacts at each step
- Wait for your approval at gates
- Record progress in the Memory Bank
Bolt Artifacts
Each bolt produces artifacts stored in the Memory Bank:
memory-bank/bolts/{bolt-id}/
├── bolt.md # Bolt metadata and state
├── ddd-01-domain-model.md # Domain model
├── ddd-02-technical-design.md # Technical design
├── adr-*.md # Architecture Decision Records (optional)
└── ddd-03-test-report.md # Test resultsmemory-bank/bolts/{bolt-id}/
├── bolt.md # Bolt metadata and state
├── implementation-plan.md # Plan from Stage 1
├── implementation-walkthrough.md # Developer notes from Stage 2
└── test-walkthrough.md # Test results from Stage 3Bolt Commands
| Command | Purpose |
|---|---|
bolt-list |
List all bolts in unit |
bolt-start |
Start or continue a bolt |
bolt-status |
Check current progress |
bolt-replan |
Replan if scope changed |
Best Practices
Keep Bolts Small
A bolt should complete in hours to a few days. If it’s taking longer, the scope is too big - split it into multiple bolts.
Choose the Right Bolt Type
Use DDD for complex domain logic, Simple for UI/utilities. Don’t over-engineer simple tasks.
Don't Skip Stages
Each stage builds on the previous. Skipping creates technical debt and increases risk.
Validate Thoroughly
Use gate reviews to catch issues early. It’s cheaper to fix problems in design than in code.
Document Decisions
ADRs capture the “why” behind decisions. Future you will thank present you.