project-iris 0.0.17 → 0.1.0

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md

@@ -25,23 +25,23 @@
 **Stages MUST be executed in this exact order:**
 
 ```text
-Stage 1: Domain Model → Stage 2: Technical Design → Stage 3: ADR Analysis (optional) → Stage 4: Implement → Stage 5: Test
+Stage 1: Domain Design → Stage 2: Logical Design → Stage 3: ADR Analysis (optional) → Stage 4: Code Generation → Stage 5: Testing
 ```
 
 **Stage Overview:**
 
-- ✅/[ ] **1. Domain Model** (Required) → `ddd-01-domain-model.md`
-- ✅/[ ] **2. Technical Design** (Required) → `ddd-02-technical-design.md`
+- ✅/[ ] **1. Domain Design** (Required) → `ddd-01-domain-design.md`
+- ✅/[ ] **2. Logical Design** (Required) → `ddd-02-logical-design.md`
 - ✅/[ ] **3. ADR Analysis** (Optional) → `adr-{n}-{slug}.md` (zero or more)
-- ✅/[ ] **4. Implement** (Required) → Source code
-- ✅/[ ] **5. Test** (Required) → Tests + `ddd-03-test-report.md`
+- ✅/[ ] **4. Code Generation** (Required) → Source code
+- ✅/[ ] **5. Testing** (Required) → Tests + `ddd-03-test-report.md`
 
 **Rules**:
 
 - Each stage MUST be completed before the next begins
 - Stage 3 can be skipped if no ADR-worthy decisions are identified
 - **⛔ Human validation is MANDATORY at each stage checkpoint - STOP and WAIT for approval**
-- NEVER skip to implementation without completing Domain Model and Technical Design
+- NEVER skip to code generation without completing Domain Design and Logical Design
 - NEVER auto-advance to next stage without explicit user confirmation
 
 ---
@@ -77,7 +77,7 @@ This bolt type implements Domain-Driven Design (DDD) methodology through five se
 
 ## Stages
 
-### Stage 1: Domain Model
+### Stage 1: Domain Design
 
 **Objective**: Create a static domain model using DDD principles
 
@@ -86,7 +86,7 @@ This bolt type implements Domain-Driven Design (DDD) methodology through five se
 **⛔ CONSTRAINTS**:
 
 - **FORBIDDEN**: Reading, analyzing, or modifying ANY source code files
-- **ONLY OUTPUT**: Documentation artifact (`ddd-01-domain-model.md`)
+- **ONLY OUTPUT**: Documentation artifact (`ddd-01-domain-design.md`)
 
 **Activities**:
 
@@ -98,10 +98,10 @@ This bolt type implements Domain-Driven Design (DDD) methodology through five se
 6 - **Design repository interfaces**: Define contracts for data access
 7 - **Document ubiquitous language**: Create glossary of domain terms
 
-**Artifact**: `ddd-01-domain-model.md`
-**Template**: `.iris/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-01-domain-model-template.md`
+**Artifact**: `ddd-01-domain-design.md`
+**Template**: `.iris/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-01-domain-design-template.md`
 **Location**: Path defined by `schema.bolts` in `.iris/aidlc/memory-bank.yaml`
-*(Default: `memory-bank/bolts/{bolt-id}/ddd-01-domain-model.md`)*
+*(Default: `memory-bank/bolts/{bolt-id}/ddd-01-domain-design.md`)*
 
 **Template Structure**:
 
@@ -157,16 +157,16 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 
 ---
 
-### Stage 2: Technical Design
+### Stage 2: Logical Design
 
-**Objective**: Transform static model into technical architecture
+**Objective**: Transform static model into technical architecture with NFRs and patterns
 
 **Duration**: Hours (typically 2-4 hours)
 
 **⛔ CONSTRAINTS**:
 
 - **FORBIDDEN**: Reading, analyzing, or modifying ANY source code files
-- **ONLY OUTPUT**: Documentation artifact (`ddd-02-technical-design.md`)
+- **ONLY OUTPUT**: Documentation artifact (`ddd-02-logical-design.md`)
 
 **Activities**:
 
@@ -178,10 +178,10 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 6 - **Design for NFRs**: Plan performance and scalability approach
 7 - **Plan integrations**: Document integration points
 
-**Artifact**: `ddd-02-technical-design.md`
-**Template**: `.iris/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-02-technical-design-template.md`
+**Artifact**: `ddd-02-logical-design.md`
+**Template**: `.iris/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-02-logical-design-template.md`
 **Location**: Path defined by `schema.bolts` in `.iris/aidlc/memory-bank.yaml`
-*(Default: `memory-bank/bolts/{bolt-id}/ddd-02-technical-design.md`)*
+*(Default: `memory-bank/bolts/{bolt-id}/ddd-02-logical-design.md`)*
 
 **Template Structure**:
 
@@ -192,7 +192,7 @@ bolt: {bolt-id}
 created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
-## Technical Design: {unit-name}
+## Logical Design: {unit-name}
 
 ### Architecture Pattern
 {Selected pattern and rationale}
@@ -251,7 +251,7 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 **⛔ CONSTRAINTS**:
 
 - **OPTIONAL**: This stage can be skipped if no ADR-worthy decisions are identified
-- **REQUIRED**: Must have completed `Domain Model` and `Technical Design` stages first
+- **REQUIRED**: Must have completed `Domain Design` and `Logical Design` stages first
 - **OUTPUT**: ADR documents (if any created)
 
 **When to Create ADRs**:
@@ -337,7 +337,7 @@ Implement CQRS pattern with separate read models for task queries.
 
 ---
 
-### Stage 4: Implement
+### Stage 4: Code Generation
 
 **Objective**: Generate production-ready code from designs
 
@@ -420,7 +420,7 @@ src/{unit}/
 **Checkpoint Output Format**:
 
 ```text
-## Stage 4 Complete: Implementation
+## Stage 4 Complete: Code Generation
 
 ### Code Generated
 - {n} domain entities
@@ -444,7 +444,7 @@ Ready to proceed to testing?
 
 ---
 
-### Stage 5: Test
+### Stage 5: Testing
 
 **Objective**: Ensure quality through comprehensive testing with acceptance criteria validation
 
@@ -452,7 +452,7 @@ Ready to proceed to testing?
 
 **⛔ CONSTRAINTS**:
 
-- **REQUIRED**: Must have completed `Implement` stage first
+- **REQUIRED**: Must have completed `Code Generation` stage first
 - **REQUIRED**: Load all bolt folder artifacts (see Bolt Context Loading section)
 - **OUTPUT**: Tests + documentation artifact (`ddd-03-test-report.md`)
 
@@ -568,7 +568,7 @@ current_stage: design
 stages_completed:
   - name: model
     completed: 2024-12-05T10:00:00Z
-    artifact: ddd-01-domain-model.md
+    artifact: ddd-01-domain-design.md
 status: in-progress
 ---
 ```
@@ -577,15 +577,15 @@ status: in-progress
 
 ## Bolt Context Loading
 
-For stages that build on previous work (Stage 4: Implement, Stage 5: Test), load all artifacts from the bolt folder:
+For stages that build on previous work (Stage 4: Code Generation, Stage 5: Testing), load all artifacts from the bolt folder:
 
 **Location**: `memory-bank/bolts/{bolt-id}/`
 
 **Load all files in this folder**, which may include:
 
 - `bolt.md` - Bolt instance metadata
-- `ddd-01-domain-model.md` - Domain model from Stage 1
-- `ddd-02-technical-design.md` - Technical design from Stage 2
+- `ddd-01-domain-design.md` - Domain design from Stage 1
+- `ddd-02-logical-design.md` - Logical design from Stage 2
 - `adr-*.md` - Any ADRs from Stage 3
 
 This ensures the implementation and test stages have full context from earlier design work.

package/flows/aidlc/templates/construction/bolt-types/simple-construction-bolt.md

@@ -25,14 +25,14 @@
 **Stages MUST be executed in this exact order:**
 
 ```text
-Stage 1: Plan → Stage 2: Implement → Stage 3: Test
+Stage 1: Plan → Stage 2: Code Generation → Stage 3: Testing
 ```
 
 **Stage Overview:**
 
 - ✅/[ ] **1. Plan** (Required) → `implementation-plan.md`
-- ✅/[ ] **2. Implement** (Required) → Source code + `implementation-walkthrough.md`
-- ✅/[ ] **3. Test** (Required) → Tests + `test-walkthrough.md`
+- ✅/[ ] **2. Code Generation** (Required) → Source code + `implementation-walkthrough.md`
+- ✅/[ ] **3. Testing** (Required) → Tests + `test-walkthrough.md`
 
 **Rules**:
 
@@ -141,7 +141,7 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 
 ---
 
-### Stage 2: Implement
+### Stage 2: Code Generation
 
 **Objective**: Write the code and document what was done
 
@@ -237,7 +237,7 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 
 ---
 
-### Stage 3: Test
+### Stage 3: Testing
 
 **Objective**: Verify the implementation works correctly
 
@@ -315,7 +315,7 @@ status: in-progress
 
 ## Bolt Context Loading
 
-For Stage 2 (Implement) and Stage 3 (Test), load all artifacts from the bolt folder:
+For Stage 2 (Code Generation) and Stage 3 (Testing), load all artifacts from the bolt folder:
 
 **Location**: `memory-bank/bolts/{bolt-id}/`
 

package/flows/aidlc/templates/construction/construction-guide.md

@@ -0,0 +1,244 @@
+# Construction Phase Guide
+
+This guide explains the two construction workflows in AI-DLC: **Greenfield** (new applications) and **Brownfield** (existing applications).
+
+---
+
+## Quick Decision
+
+```text
+Is this a NEW application or feature from scratch?
+├── YES → Greenfield Flow (standard DDD bolt)
+└── NO  → Brownfield Flow (code elevation first)
+
+Is this modifying/enhancing EXISTING code?
+├── YES → Brownfield Flow (code elevation first)
+└── NO  → Greenfield Flow (standard DDD bolt)
+```
+
+---
+
+## Greenfield Flow (New Application)
+
+**Use when**: Building something entirely new with no existing codebase to consider.
+
+**Examples**:
+- New microservice
+- New feature in a new module
+- New application from scratch
+
+### Workflow
+
+```text
+Inception Complete
+       │
+       ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    CONSTRUCTION PHASE                         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Stage 1: Domain Design                                      │
+│  ├── Identify entities, value objects, aggregates            │
+│  ├── Define domain events and services                       │
+│  └── Output: ddd-01-domain-design.md                         │
+│                          │                                   │
+│                          ▼                                   │
+│  Stage 2: Logical Design                                     │
+│  ├── Select architectural patterns                           │
+│  ├── Design API contracts, data model                        │
+│  └── Output: ddd-02-logical-design.md                        │
+│                          │                                   │
+│                          ▼                                   │
+│  Stage 3: ADR Analysis (Optional)                            │
+│  ├── Document significant decisions                          │
+│  └── Output: adr-*.md (if needed)                            │
+│                          │                                   │
+│                          ▼                                   │
+│  Stage 4: Code Generation                                    │
+│  ├── Generate code from designs                              │
+│  └── Output: Source code                                     │
+│                          │                                   │
+│                          ▼                                   │
+│  Stage 5: Testing                                            │
+│  ├── Unit, integration, security tests                       │
+│  └── Output: ddd-03-test-report.md                           │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+       │
+       ▼
+Operations Phase
+```
+
+### Templates Used
+
+| Stage | Template |
+|-------|----------|
+| Domain Design | `bolt-types/ddd-construction-bolt/ddd-01-domain-design-template.md` |
+| Logical Design | `bolt-types/ddd-construction-bolt/ddd-02-logical-design-template.md` |
+| ADR | `bolt-types/ddd-construction-bolt/adr-template.md` |
+| Test Report | `bolt-types/ddd-construction-bolt/ddd-03-test-report-template.md` |
+
+### Start Command
+
+```text
+/iris-construction-agent --unit="{unit-name}"
+```
+
+---
+
+## Brownfield Flow (Existing Application)
+
+**Use when**: Modifying, enhancing, or fixing existing code.
+
+**Examples**:
+- Adding feature to existing service
+- Bug fix in existing module
+- Refactoring existing code
+- Migrating/modernizing existing system
+
+### Why Code Elevation?
+
+Per AI-DLC specification:
+
+> In brown-field scenarios, the construction phase involves first **elevating the codes into a semantic rich modelling representation** so that the context to AI becomes concise and accurate.
+
+This ensures:
+1. AI understands existing structure before making changes
+2. New code is consistent with existing patterns
+3. Changes don't break existing functionality
+4. Impact analysis is accurate
+
+### Workflow
+
+```text
+Inception Complete
+       │
+       ▼
+┌──────────────────────────────────────────────────────────────┐
+│                 CODE ELEVATION (Brownfield Only)              │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Phase 1: Static Model                                       │
+│  ├── Analyze existing codebase                               │
+│  ├── Document components, responsibilities, relationships    │
+│  └── Output: elevation-static-model.md                       │
+│                          │                                   │
+│                          ▼                                   │
+│  Phase 2: Dynamic Model                                      │
+│  ├── Trace significant use cases                             │
+│  ├── Document component interactions, data flows             │
+│  └── Output: elevation-dynamic-model.md                      │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+       │
+       ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    CONSTRUCTION PHASE                         │
+│              (Same as Greenfield, but with context)           │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Stage 1: Domain Design                                      │
+│  ├── EXTEND existing entities (from static model)            │
+│  ├── ADD new entities as needed                              │
+│  └── Output: ddd-01-domain-design.md                         │
+│                          │                                   │
+│                          ▼                                   │
+│  Stage 2: Logical Design                                     │
+│  ├── FOLLOW existing patterns (from dynamic model)           │
+│  ├── Design changes consistent with existing architecture    │
+│  └── Output: ddd-02-logical-design.md                        │
+│                          │                                   │
+│                          ▼                                   │
+│  [Stages 3-5 same as Greenfield]                             │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+       │
+       ▼
+Operations Phase
+```
+
+### Templates Used
+
+| Phase/Stage | Template |
+|-------------|----------|
+| Static Model | `elevation-static-model-template.md` |
+| Dynamic Model | `elevation-dynamic-model-template.md` |
+| Domain Design | `bolt-types/ddd-construction-bolt/ddd-01-domain-design-template.md` |
+| (etc.) | (same as Greenfield) |
+
+### Start Command
+
+```text
+/iris-construction-agent --unit="{unit-name}" --brownfield
+```
+
+Or use the code elevation skill directly:
+
+```text
+/iris-construction-agent --skill="code-elevate" --unit="{unit-name}"
+```
+
+---
+
+## Comparison Table
+
+| Aspect | Greenfield | Brownfield |
+|--------|------------|------------|
+| **Starting Point** | Clean slate | Existing codebase |
+| **First Step** | Domain Design | Code Elevation |
+| **AI Context** | Requirements only | Requirements + Elevation Models |
+| **Design Approach** | Create new patterns | Follow existing patterns |
+| **Risk** | Design risk | Integration/regression risk |
+| **Extra Artifacts** | None | Static Model, Dynamic Model |
+
+---
+
+## How Construction Agent Detects Flow
+
+The Construction Agent determines the flow by:
+
+1. **Explicit flag**: `--brownfield` or `--greenfield`
+2. **Unit brief**: Check `unit_type` in unit-brief.md
+3. **Codebase detection**: Check if `src/{unit}/` already exists
+4. **Ask user**: If unclear, ask which flow to use
+
+```text
+## Construction Flow Detection
+
+I detected existing code in `src/{unit}/`. This appears to be a brownfield scenario.
+
+1 - **Brownfield**: Run code elevation first (recommended)
+2 - **Greenfield**: Skip elevation, start fresh
+3 - **Explain**: Tell me more about the flows
+```
+
+---
+
+## Best Practices
+
+### Greenfield
+
+- ✅ Start with clear domain boundaries
+- ✅ Apply DDD patterns from the beginning
+- ✅ Document decisions in ADRs
+- ❌ Don't skip Domain Design stage
+
+### Brownfield
+
+- ✅ Always run code elevation first
+- ✅ Validate elevation models with team
+- ✅ Follow existing patterns unless explicitly changing them
+- ✅ Document deviations from existing patterns in ADRs
+- ❌ Don't assume you understand the codebase without elevation
+- ❌ Don't introduce new patterns without documenting why
+
+---
+
+## Related Skills
+
+| Skill | Purpose | Flow |
+|-------|---------|------|
+| `bolt-start` | Execute construction bolt | Both |
+| `code-elevate` | Elevate existing code to models | Brownfield |
+| `bolt-list` | List available bolts | Both |
+| `bolt-replan` | Modify bolt plan | Both |

package/flows/aidlc/templates/construction/construction-log-template.md

@@ -120,10 +120,11 @@ Update this file when:
 ```markdown
 | Date | Bolt | Event | Details |
 |------|------|-------|---------|
-| 2025-12-07 | bolt-auth-1 | started | Stage 1: Model |
-| 2025-12-07 | bolt-auth-1 | stage-complete | Model → Design |
-| 2025-12-07 | bolt-auth-1 | stage-complete | Design → Implement |
-| 2025-12-08 | bolt-auth-1 | stage-complete | Implement → Test |
-| 2025-12-08 | bolt-auth-1 | completed | All 4 stages done |
-| 2025-12-08 | bolt-auth-2 | started | Stage 1: Model |
+| 2025-12-07 | bolt-auth-1 | started | Stage 1: Domain Design |
+| 2025-12-07 | bolt-auth-1 | stage-complete | Domain Design → Logical Design |
+| 2025-12-07 | bolt-auth-1 | stage-complete | Logical Design → ADR Analysis |
+| 2025-12-07 | bolt-auth-1 | stage-complete | ADR Analysis → Code Generation |
+| 2025-12-08 | bolt-auth-1 | stage-complete | Code Generation → Testing |
+| 2025-12-08 | bolt-auth-1 | completed | All 5 stages done |
+| 2025-12-08 | bolt-auth-2 | started | Stage 1: Domain Design |
 ```