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.

The term “Bolt” emphasizes speed and precision - like a bolt of lightning, work happens fast but with focused energy. Bolts are analogous to Sprints in Scrum, but optimized for AI-driven development.

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:

1. Domain Model

   Model business logic using DDD principles:

   • Identify aggregates, entities, value objects
   • Define domain events and commands
   • Establish ubiquitous language
2. Technical Design

   Apply patterns and make architecture decisions:

   • Choose implementation patterns
   • Define interfaces and contracts
   • Plan data structures and APIs
3. ADR Analysis

   Document significant decisions:

   • Context and problem
   • Options considered
   • Decision and rationale
4. Implement

   Generate production code:

   • Follow coding standards
   • Apply design patterns
   • Write clean, documented code
5. Test

   Verify correctness:

   • Unit tests
   • Integration tests
   • Acceptance tests

Simple Construction Bolt

A lightweight bolt for UI, integrations, and utilities:

1. Plan

   Define what to build:

   • Review stories and requirements
   • List specific deliverables
   • Identify dependencies
   • Define acceptance criteria
2. Implement

   Write the code:

   • Setup file structure
   • Implement core functionality
   • Handle edge cases
   • Add documentation
3. Test

   Verify the implementation:

   • Write unit tests
   • Run test suite
   • Verify acceptance criteria
   • Document results

Human Checkpoints

Human validation happens at each checkpoint. You cannot proceed to the next stage without approval. This is the “Human Oversight as Loss Function” principle - catching errors early before they cascade.

DDD Construction Checkpoints

Simple Construction Checkpoints

Executing Bolts

Start a bolt with the Construction Agent:

/specsmd-construction-agent --unit="my-unit"

The agent will:

1. Show available bolts for the unit
2. Ask which bolt to work on
3. Guide you through each stage
4. Generate artifacts at each step
5. Wait for your approval at gates
6. Record progress in the Memory Bank

Bolt Artifacts

Each bolt produces artifacts stored in the Memory Bank:

DDD Construction

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 results

Simple Construction

memory-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 3

Bolt 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.

Next Steps

Memory Bank

Learn how artifacts are persisted and connected

Bolt Types Guide

Detailed guide on choosing and using bolt types