--- title: Construction Agent description: 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 **Claude Code** ```bash /specsmd-construction-agent ``` **Cursor** ``` /specsmd-construction-agent ``` Or use the `@` prefix: ``` @specsmd-construction-agent ``` **GitHub Copilot** ``` /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: 1. Show available bolts from your plan 2. Let you select which to start 3. Begin the first stage If a bolt is in progress: 1. Load current stage context 2. Continue from where you left off ### Stage Progression For a DDD Construction bolt: 1. **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 2. **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 3. **ADR Analysis (Optional)** For significant decisions: - Document context and problem - List options considered - Record decision and rationale **Gate**: Review and approve ADR 4. **Implement** The agent generates production code: - Follow coding standards - Apply design patterns - Write clean, maintainable code **Gate**: Review generated code 5. **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) ```mermaid flowchart LR M(Model):::plan --> G1{{"✋"}}:::check G1 --> D(Design):::plan D --> G2{{"✋"}}:::check G2 --> A(ADR):::plan A --> G3{{"✋"}}:::check G3 --> I(Implement):::build I --> G4{{"✋"}}:::check G4 --> T(Test):::warn T --> G5{{"✋"}}:::check G5 --> Done((Done)):::done classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8 classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8 classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8 classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8 classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8 ``` | 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) ```mermaid flowchart LR S(Spec):::plan --> G1{{"✋"}}:::check G1 --> I(Implement):::build I --> G2{{"✋"}}:::check G2 --> T(Test):::warn T --> G3{{"✋"}}:::check G3 --> Done((Done)):::done classDef plan fill:#fff,stroke:#6366F1,color:#4338CA,stroke-width:1.5px,rx:8,ry:8 classDef build fill:#fff,stroke:#0EA5E9,color:#0369A1,stroke-width:1.5px,rx:8,ry:8 classDef warn fill:#fff,stroke:#F59E0B,color:#B45309,stroke-width:1.5px,rx:8,ry:8 classDef check fill:#fff,stroke:#EC4899,color:#BE185D,stroke-width:2px,rx:8,ry:8 classDef done fill:#fff,stroke:#10B981,color:#047857,stroke-width:1.5px,rx:8,ry:8 ``` | 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 | :::warning You cannot proceed to the next stage without explicit approval. This is intentional - it catches errors before they cascade. ::: 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: **DDD Construction** ``` 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/ ``` **Simple Construction** ``` 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 Ensure Inception is complete before starting Construction. Missing requirements cause rework. Checkpoints are your opportunity to catch issues. Don't rubber-stamp approvals. If a bolt is taking too long, the scope may be too big. Consider splitting. Don't skip the Test stage. Untested code is a liability. ## Troubleshooting - Check if scope is too large - Consider splitting into multiple bolts - Use `bolt-replan` to adjust - Review the feedback carefully - Make requested changes - Resubmit for approval - Ensure previous bolt artifacts are saved - Check Memory Bank for missing files - Reload with `bolt-start`