Construction Agent

Executes bolts through validated stages to produce tested code

Overview

The Construction Agent handles the second phase of AI-DLC. It executes bolts through validated stages, producing tested, production-ready code.

Invocation

/specsmd-construction-agent

/specsmd-construction-agent

Or use the @ prefix:

@specsmd-construction-agent

/specsmd-construction-agent

Commands

Command	Purpose
`bolt-start`	Start or continue executing a bolt
`bolt-status`	Check bolt progress
`bolt-list`	List all bolts
`bolt-replan`	Replan bolts if needed

bolt-start

Starts or continues a bolt execution:

> bolt-start

If no bolt is in progress, the agent will:

Show available bolts from your plan
Let you select which to start
Begin the first stage

If a bolt is in progress:

Load current stage context
Continue from where you left off

Stage Progression

For a DDD Construction bolt:

Domain Model

The agent helps you model business logic:

Identify aggregates and entities
Define value objects
Map domain events
Establish ubiquitous language

Gate: Review and approve the domain model

Technical Design

The agent creates the technical design:

Choose implementation patterns
Define interfaces and contracts
Plan data structures
Make architecture decisions

Gate: Review and approve the design

ADR Analysis (Optional)

For significant decisions:

Document context and problem
List options considered
Record decision and rationale

Gate: Review and approve ADR

Implement

The agent generates production code:

Follow coding standards
Apply design patterns
Write clean, maintainable code

Gate: Review generated code

Test

The agent creates and runs tests:

Unit tests for domain logic
Integration tests for interfaces
Acceptance tests for stories

Gate: Verify all tests pass

Example Session

User: bolt-start

Construction Agent: Available bolts for User Registration:

1. Registration Domain Model (DDD) - Not started
2. Email Validation (TDD) - Not started
3. Welcome Email (BDD) - Not started

Which bolt would you like to start?

User: 1

Construction Agent: Starting "Registration Domain Model" bolt.

## Stage 1: Domain Model

Let's model the user registration domain. Based on your 
requirements, I'll identify the key domain concepts.

### Aggregates
- **User**: The root aggregate representing a registered user

### Entities  
- **EmailAddress**: Validated email with confirmation status
- **Password**: Hashed password with strength validation

### Value Objects
- **UserId**: Unique identifier for users
- **RegistrationDate**: When the user registered

### Domain Events
- **UserRegistered**: Raised when registration completes
- **EmailConfirmed**: Raised when email is verified

Does this domain model look correct? 
[Approve] [Request Changes]

User: Approve

Construction Agent: Domain model approved. Moving to Technical Design...

bolt-status

Check the current progress of bolts:

> bolt-status

Output shows:

Current Bolt: Registration Domain Model
Status: In Progress
Current Stage: Technical Design (2 of 5)
Completed Stages:
  ✓ Domain Model - Approved
  → Technical Design - In Progress
  ○ ADR Analysis
  ○ Implement  
  ○ Test

Time in bolt: 45 minutes

bolt-list

List all bolts across the project:

> bolt-list

Output:

User Authentication / User Registration
  ✓ Registration Domain Model - Completed (2h 15m)
  → Email Validation - In Progress
  ○ Welcome Email - Not Started

User Authentication / User Login
  ○ Login Domain Model - Not Started
  ○ Session Handling - Not Started

bolt-replan

Replan bolts when scope changes:

> bolt-replan user-authentication/user-registration

Use this when:

New requirements were added
Stories were split or combined
Priorities changed
Estimates were off

Human Checkpoints

The Construction Agent’s checkpoints are defined by the bolt type. Each bolt type has its own checkpoint structure.

DDD Construction (5 checkpoints)

Gate	After Stage	Purpose
Gate 1	Domain Model	Validate domain concepts before design
Gate 2	Technical Design	Approve architecture before ADR
Gate 3	ADR Analysis	Confirm decisions documented
Gate 4	Implement	Review code before testing
Gate 5	Test	Verify all tests pass, bolt complete

Simple Construction (3 checkpoints)

Gate	After Stage	Purpose
Gate 1	Spec	Validate requirements before coding
Gate 2	Implement	Review code before testing
Gate 3	Test	Verify all tests pass, bolt complete

At each gate, you can:

Approve: Move to the next stage
Request Changes: Ask for modifications
Reject: Go back to a previous stage

Artifacts Generated

Each bolt produces artifacts in the Memory Bank:

memory-bank/intents/{intent}/units/{unit}/bolts/{bolt}/
├── domain-model.md       # Stage 1 output
├── technical-design.md   # Stage 2 output
├── adr-001.md           # Stage 3 output (if applicable)
├── implementation/       # Stage 4 output
│   ├── src/
│   └── ...
└── tests/               # Stage 5 output
    ├── unit/
    └── integration/

memory-bank/intents/{intent}/units/{unit}/bolts/{bolt}/
├── spec.md              # Stage 1 output
├── implementation/       # Stage 2 output
│   ├── src/
│   └── ...
└── tests/               # Stage 3 output
    ├── unit/
    └── integration/

Best Practices

Complete Before Starting

Ensure Inception is complete before starting Construction. Missing requirements cause rework.

Review Carefully at Checkpoints

Checkpoints are your opportunity to catch issues. Don’t rubber-stamp approvals.

Keep Bolts Focused

If a bolt is taking too long, the scope may be too big. Consider splitting.

Test Thoroughly

Don’t skip the Test stage. Untested code is a liability.

Troubleshooting

Bolt Taking Too Long

Check if scope is too large
Consider splitting into multiple bolts
Use bolt-replan to adjust

Stage Rejections

Review the feedback carefully
Make requested changes
Resubmit for approval

Context Lost

Ensure previous bolt artifacts are saved
Check Memory Bank for missing files
Reload with bolt-start