Choosing Bolt Types

A practical guide to selecting the right bolt type for your work

Overview

The AI-DLC flow in specs.md provides two bolt types, each optimized for different types of work. Choosing the right bolt type ensures you have the appropriate level of rigor and structure for your task.

Quick Decision Guide

The Inception Agent automatically selects the appropriate bolt type based on your requirements. If you disagree with its choice, you can change it during the human checkpoint review.

1. Does it involve complex business logic or domain rules?

   Yes → Use DDD Construction Bolt

   No → Continue to next question

2. Is it UI, integration, utility, or straightforward CRUD?

   Yes → Use Simple Construction Bolt

---

DDD Construction Bolt

When to Use

Complex domain logic requiring careful modeling and design decisions.

Best For

• Core business logic with complex rules
• Domain models with aggregates, entities, and value objects
• Services that encode business knowledge
• Features where incorrect logic has significant consequences
• Bounded contexts with rich domain models

Stages

Stage	Purpose	Output
1. Domain Model	Model business logic using DDD principles	Domain model document
2. Technical Design	Apply patterns, define interfaces	Technical design document
3. ADR Analysis	Document significant decisions	Architecture Decision Record
4. Implement	Generate production code	Implementation
5. Test	Verify correctness	Test suite

Example Use Cases

E-commerce Order Processing

Orders involve complex state transitions, pricing rules, inventory checks, and payment processing. DDD helps model these business rules explicitly.

Financial Calculations

Interest calculations, fee structures, and compliance rules require careful domain modeling to ensure correctness.

Booking Systems

Availability rules, conflict detection, and reservation logic benefit from explicit domain modeling.

Workflow Engines

State machines, transition rules, and approval chains require careful design.

---

Simple Construction Bolt

When to Use

Straightforward implementations that don’t require extensive domain modeling.

Best For

• Frontend pages and components
• Simple CRUD endpoints
• External API integrations
• Utilities and helper modules
• CLI commands and scripts
• Configuration and setup code

Stages

Stage	Purpose	Output
1. Plan	Define what to build	implementation-plan.md
2. Implement	Write the code	Source code + implementation-walkthrough.md
3. Test	Verify the implementation	Tests + test-walkthrough.md

Example Use Cases

User Profile Page

A React component displaying user information with edit capabilities. Clear requirements, no complex business logic.

REST API Integration

Connecting to a third-party API with well-documented endpoints. Focus on correct integration, not domain modeling.

Admin Dashboard

Data display and basic filtering. CRUD operations with straightforward UI.

CLI Tool

A command-line utility for common operations. Clear inputs and outputs.

---

Comparison Table

Aspect	DDD Construction	Simple Construction
Stages	5	3
Duration	Hours to days	Hours
Documentation	Extensive	Light
Design Rigor	High	Low
Output	Production code + artifacts	Production code
Human Reviews	5 checkpoint reviews	3 checkpoint reviews

Common Mistakes

Choosing the wrong bolt type leads to either over-engineering simple tasks or under-designing complex ones.

Over-Engineering (DDD for Simple Tasks)

Symptom: Using DDD Construction for a simple settings page.

Problem: Excessive ceremony for straightforward work. Domain modeling for CRUD operations wastes time without adding value.

Solution: Use Simple Construction for UI, utilities, and integrations.

Under-Engineering (Simple for Complex Tasks)

Symptom: Using Simple Construction for complex pricing logic.

Problem: Skipping domain modeling leads to implicit business rules scattered in code. Bugs emerge as edge cases are missed.

Solution: Use DDD Construction when business logic is non-trivial.

Next Steps

Bolts Overview

Core concepts and bolt mechanics

Construction Agent

Learn how the agent executes bolts