project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/agents/construction-agent.mdx

@@ -0,0 +1,358 @@
+---
+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
+
+<Tabs>
+  <Tab title="Claude Code">
+    ```bash
+    /specsmd-construction-agent
+    ```
+  </Tab>
+  <Tab title="Cursor">
+    ```
+    /specsmd-construction-agent
+    ```
+    Or use the `@` prefix:
+    ```
+    @specsmd-construction-agent
+    ```
+  </Tab>
+  <Tab title="GitHub Copilot">
+    ```
+    /specsmd-construction-agent
+    ```
+  </Tab>
+</Tabs>
+
+## 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:
+
+<Steps>
+  <Step title="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
+  </Step>
+  <Step title="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
+  </Step>
+  <Step title="ADR Analysis (Optional)">
+    For significant decisions:
+    - Document context and problem
+    - List options considered
+    - Record decision and rationale
+    
+    **Gate**: Review and approve ADR
+  </Step>
+  <Step title="Implement">
+    The agent generates production code:
+    - Follow coding standards
+    - Apply design patterns
+    - Write clean, maintainable code
+    
+    **Gate**: Review generated code
+  </Step>
+  <Step title="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
+  </Step>
+</Steps>
+
+### 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] --> G1{Gate}
+    G1 --> D[Design]
+    D --> G2{Gate}
+    G2 --> A[ADR]
+    A --> G3{Gate}
+    G3 --> I[Implement]
+    I --> G4{Gate}
+    G4 --> T[Test]
+    T --> G5{Gate}
+    G5 --> Done((Done))
+
+    style G1 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G2 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G3 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G4 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G5 fill:#F472B6,stroke:#EC4899,color:#fff
+    style M fill:#818CF8,stroke:#6366F1,color:#fff
+    style D fill:#818CF8,stroke:#6366F1,color:#fff
+    style A fill:#818CF8,stroke:#6366F1,color:#fff
+    style I fill:#34D399,stroke:#10B981,color:#fff
+    style T fill:#FBBF24,stroke:#F59E0B,color:#fff
+```
+
+| 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] --> G1{Gate}
+    G1 --> I[Implement]
+    I --> G2{Gate}
+    G2 --> T[Test]
+    T --> G3{Gate}
+    G3 --> Done((Done))
+
+    style G1 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G2 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G3 fill:#F472B6,stroke:#EC4899,color:#fff
+    style S fill:#818CF8,stroke:#6366F1,color:#fff
+    style I fill:#34D399,stroke:#10B981,color:#fff
+    style T fill:#FBBF24,stroke:#F59E0B,color:#fff
+```
+
+| 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.
+</Warning>
+
+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:
+
+<Tabs>
+  <Tab title="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/
+    ```
+  </Tab>
+  <Tab title="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/
+    ```
+  </Tab>
+</Tabs>
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Complete Before Starting">
+    Ensure Inception is complete before starting Construction. Missing requirements cause rework.
+  </Accordion>
+  <Accordion title="Review Carefully at Checkpoints">
+    Checkpoints are your opportunity to catch issues. Don't rubber-stamp approvals.
+  </Accordion>
+  <Accordion title="Keep Bolts Focused">
+    If a bolt is taking too long, the scope may be too big. Consider splitting.
+  </Accordion>
+  <Accordion title="Test Thoroughly">
+    Don't skip the Test stage. Untested code is a liability.
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Bolt Taking Too Long">
+    - Check if scope is too large
+    - Consider splitting into multiple bolts
+    - Use `bolt-replan` to adjust
+  </Accordion>
+  <Accordion title="Stage Rejections">
+    - Review the feedback carefully
+    - Make requested changes
+    - Resubmit for approval
+  </Accordion>
+  <Accordion title="Context Lost">
+    - Ensure previous bolt artifacts are saved
+    - Check Memory Bank for missing files
+    - Reload with `bolt-start`
+  </Accordion>
+</AccordionGroup>

package/src/iris_bundle/frameworks/iris-core/docs.iris.md/agents/inception-agent.mdx

@@ -0,0 +1,306 @@
+---
+title: Inception Agent
+description: Captures intents, elaborates requirements, and decomposes into units
+---
+
+## Overview
+
+The **Inception Agent** handles the first phase of AI-DLC. It captures your high-level goals (Intents), elaborates them into detailed requirements, and decomposes them into manageable Units.
+
+## Invocation
+
+<Tabs>
+  <Tab title="Claude Code">
+    ```bash
+    /specsmd-inception-agent
+    ```
+  </Tab>
+  <Tab title="Cursor">
+    ```
+    /specsmd-inception-agent
+    ```
+    Or use the `@` prefix:
+    ```
+    @specsmd-inception-agent
+    ```
+  </Tab>
+  <Tab title="GitHub Copilot">
+    ```
+    /specsmd-inception-agent
+    ```
+  </Tab>
+</Tabs>
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `intent-create` | Create a new intent |
+| `intent-list` | List all intents |
+| `requirements` | Elaborate intent requirements |
+| `context` | Define system context |
+| `units` | Decompose into units |
+| `story-create` | Create stories for a unit |
+| `bolt-plan` | Plan bolts for stories |
+| `review` | Review inception artifacts |
+
+## intent-create
+
+Creates a new intent from your high-level goal:
+
+```
+> intent-create
+> I want to build a user authentication system
+```
+
+The agent will:
+
+<Steps>
+  <Step title="Capture Goal">
+    Record your high-level intent description
+  </Step>
+  <Step title="Ask Clarifying Questions">
+    Minimize ambiguity through targeted questions
+  </Step>
+  <Step title="Generate Requirements">
+    Create user stories and non-functional requirements
+  </Step>
+  <Step title="Define Context">
+    Establish system boundaries and constraints
+  </Step>
+</Steps>
+
+### Example Session
+
+```
+User: intent-create
+
+Inception Agent: What would you like to build?
+
+User: A user authentication system with login, registration, 
+and password reset
+
+Inception Agent: I'll help you elaborate this intent. Let me 
+ask some clarifying questions:
+
+1. Should users be able to log in with social providers 
+   (Google, GitHub)?
+2. Do you need multi-factor authentication?
+3. What password requirements do you have?
+4. How long should sessions last?
+
+User: No social login for now, no MFA, standard password rules, 
+sessions should last 24 hours
+
+Inception Agent: Based on your answers, I've generated the 
+following requirements...
+
+[Shows generated requirements.md]
+
+Does this look correct? Should I adjust anything?
+```
+
+## requirements
+
+Elaborate or refine requirements for an existing intent:
+
+```
+> requirements user-authentication
+```
+
+Use this to:
+
+- Add new user stories
+- Refine acceptance criteria
+- Add non-functional requirements
+- Update priorities
+
+## context
+
+Define or update system context:
+
+```
+> context user-authentication
+```
+
+The agent helps you specify:
+
+- What's in scope vs out of scope
+- External interfaces
+- Technical constraints
+- Dependencies
+
+## units
+
+Decompose an intent into units:
+
+```
+> units user-authentication
+```
+
+The agent will:
+
+1. Analyze requirements and context
+2. Identify natural boundaries
+3. Propose unit structure
+4. Define interfaces between units
+5. Map dependencies
+
+### Example Output
+
+```
+Intent: User Authentication
+├── Unit: User Registration
+│   └── Stories: 3
+├── Unit: User Login  
+│   └── Stories: 2
+├── Unit: Password Management
+│   └── Stories: 3
+└── Unit: Session Management
+    └── Stories: 2
+
+Dependencies:
+- Login depends on Registration (user must exist)
+- Password Management depends on Session (must be logged in)
+```
+
+## story-create
+
+Create user stories for a specific unit:
+
+```
+> story-create user-authentication/user-registration
+```
+
+The agent generates stories with:
+
+- User story format (As a... I want... So that...)
+- Acceptance criteria
+- Edge cases
+- Test scenarios
+
+## bolt-plan
+
+Plan the bolts needed to implement stories:
+
+```
+> bolt-plan user-authentication/user-registration
+```
+
+The agent:
+
+1. Analyzes stories and their complexity
+2. Groups related stories
+3. Assigns bolt types (DDD, TDD, BDD)
+4. Orders bolts by dependencies
+5. Estimates duration
+
+### Example Output
+
+```
+Bolt Plan for User Registration:
+
+1. Bolt: Registration Domain Model (DDD Construction)
+   - Stories: US-001, US-002
+   - Duration: 2-4 hours
+   - Stages: Model → Design → Implement → Test
+
+2. Bolt: Email Validation (TDD Construction)  
+   - Stories: US-003
+   - Duration: 1-2 hours
+   - Stages: Test → Implement → Refactor
+
+3. Bolt: Welcome Email (BDD Construction)
+   - Stories: US-004
+   - Duration: 1-2 hours
+   - Stages: Scenario → Implement → Verify
+```
+
+## review
+
+Review all inception artifacts for an intent:
+
+```
+> review user-authentication
+```
+
+The agent checks for:
+
+- Completeness of requirements
+- Consistency between artifacts
+- Gaps in coverage
+- Potential issues
+
+## Workflow
+
+Typical Inception flow:
+
+```
+intent-create → requirements → context → units → story-create → bolt-plan → review
+```
+
+<Warning>
+  Complete each step before moving on. Incomplete inception leads to problems in construction.
+</Warning>
+
+## Human Checkpoints
+
+The Inception Agent has **4 human checkpoints** with auto-continue between artifact generation:
+
+```mermaid
+flowchart TB
+    A[User Request] --> B[Clarifying Questions]
+    B --> G1{Gate 1}
+    G1 -->|User answers| C[Generate Requirements]
+    C --> G2{Gate 2}
+    G2 -->|User approves| D[Auto-Generate Artifacts]
+
+    subgraph Auto-Continue
+        D --> D1[Context]
+        D1 --> D2[Units]
+        D2 --> D3[Stories]
+        D3 --> D4[Bolt Plan]
+    end
+
+    D4 --> G3{Gate 3}
+    G3 -->|User approves| E[Ready for Construction?]
+    E --> G4{Gate 4}
+    G4 -->|User confirms| F[Route to Construction]
+
+    style G1 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G2 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G3 fill:#F472B6,stroke:#EC4899,color:#fff
+    style G4 fill:#F472B6,stroke:#EC4899,color:#fff
+    style D1 fill:#818CF8,stroke:#6366F1,color:#fff
+    style D2 fill:#818CF8,stroke:#6366F1,color:#fff
+    style D3 fill:#818CF8,stroke:#6366F1,color:#fff
+    style D4 fill:#818CF8,stroke:#6366F1,color:#fff
+```
+
+| Gate | Location | Purpose |
+|------|----------|---------|
+| **Gate 1** | After clarifying questions | Ensure all ambiguities addressed |
+| **Gate 2** | After requirements generated | Validate requirements are correct |
+| **Gate 3** | After all artifacts generated | Review context, units, stories, bolt plan |
+| **Gate 4** | Ready for construction | Confirm inception complete |
+
+<Info>
+  Between Gate 2 and Gate 3, the agent auto-continues through context → units → stories → bolt-plan without stopping. This speeds up artifact generation while maintaining key validation points.
+</Info>
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Be Specific">
+    Provide detailed answers to clarifying questions. Vague inputs lead to vague outputs.
+  </Accordion>
+  <Accordion title="Review Generated Artifacts">
+    Always review what the agent generates. Correct errors before moving forward.
+  </Accordion>
+  <Accordion title="Keep Units Focused">
+    If a unit feels too big, ask the agent to split it further.
+  </Accordion>
+  <Accordion title="Plan Before Building">
+    Don't skip to Construction. Good bolt plans save time later.
+  </Accordion>
+</AccordionGroup>