project-iris 0.0.17 → 0.0.18

package/flows/aidlc/skills/master/code-elevate.md

@@ -0,0 +1,434 @@
+# Skill: Code Elevation (Brownfield)
+
+---
+
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+- ✅ **ALWAYS** show elevation progress with phase indicators
+- ✅ **ALWAYS** produce both static and dynamic models
+- 🛑 **STOP** at each checkpoint - wait for user validation
+
+## Success Metrics
+
+- ✅ Static model captures all domain components, responsibilities, and relationships
+- ✅ Dynamic model shows component interactions for significant use cases
+- ✅ Models are semantically rich enough for AI context
+- ✅ User validates models against their understanding of the codebase
+- ✅ Models stored at project level for reuse across intents
+
+## Failure Modes
+
+- ❌ Skipping static model and jumping to dynamic model
+- ❌ Missing key domain components in static model
+- ❌ Dynamic model doesn't cover significant use cases
+- ❌ Models too shallow (not semantically rich)
+- ❌ Not validating with user before proceeding
+
+---
+
+## AI-DLC Specification Reference
+
+> **Brown-Field Scenarios:** In the brown-field (existing application) 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. The suggested modelling representations are:
+> - **Static models** (just the domain components, responsibilities and their relationships)
+> - **Dynamic models** (how the components interact to realize the significant use cases)
+
+---
+
+## Context: Master Agent Skill
+
+This skill is executed by the **Master Agent** after project initialization for brownfield projects.
+
+**When triggered:**
+- After `project-init` completes with `scenario: brownfield`
+- When returning user has brownfield project without elevation
+- Master offers: "Run code elevation to analyze existing code?"
+
+**Why project-level (not intent-level):**
+- Codebase structure is project-wide, not per-intent
+- Elevation done once, reused by all intents
+- Avoids redundant analysis for each feature
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Code Elevation Progress (Brownfield)
+- [ ] Codebase Analysis  ← current
+- [ ] Static Model (components, responsibilities, relationships)
+- [ ] Dynamic Model (interactions for significant use cases)
+- [ ] User Validation
+- [ ] Ready for Inception/Construction
+```
+
+---
+
+## Checkpoints
+
+- **Checkpoint 1**: Static model review and validation
+- **Checkpoint 2**: Dynamic model review and validation
+- **Checkpoint 3**: Models approved, elevation complete
+
+---
+
+## Goal
+
+Elevate existing codebase into semantic-rich modeling representations (static and dynamic models) that provide concise and accurate context for AI-driven planning and construction in brownfield scenarios.
+
+---
+
+## Input
+
+- **Required**: `memory-bank/project.yaml` - project configuration with `scenario: brownfield`
+- **Required**: `project.yaml.existing_codebase.paths` - directories to analyze
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: Existing documentation, README files, architecture diagrams
+
+**Note**: This is a project-level skill. Intent/unit selection happens later in Inception.
+
+---
+
+## When to Use This Skill
+
+**Triggered by Master Agent when:**
+
+1. **First-time brownfield**: User has existing code, just initialized iris
+2. **Returning brownfield**: Brownfield project without elevation completed
+3. **User request**: User explicitly asks to analyze codebase
+
+**Do NOT use for greenfield** - skip directly to Inception.
+
+---
+
+## Process
+
+### Phase 1: Load Project Context
+
+Read project configuration:
+
+```text
+1. Read memory-bank/project.yaml
+2. Get existing_codebase.paths (e.g., src/, lib/, app/)
+3. Get project_type for context (e.g., backend-api, full-stack-web)
+```
+
+### Phase 2: Codebase Analysis
+
+Present analysis plan to user:
+
+```markdown
+## Codebase Analysis
+
+Based on your project configuration, I'll analyze:
+
+**Directories**:
+- `src/` - {N} files
+- `lib/` - {N} files
+
+**Analysis Goals**:
+1. **Project Structure**: How is the code organized?
+2. **Entry Points**: Where does execution begin?
+3. **Domain Boundaries**: What are the logical groupings?
+4. **External Dependencies**: What external systems does it interact with?
+
+Proceed with analysis?
+
+1 - **Analyze all** - Scan all configured paths
+2 - **Specify scope** - Focus on specific directories
+3 - **Skip** - Proceed without elevation
+```
+
+**Wait for user confirmation.**
+
+### Phase 3: Generate Static Model
+
+**Objective**: Capture domain components, their responsibilities, and relationships.
+
+**Activities**:
+
+1 - **Identify Components**: Find classes, modules, services
+2 - **Document Responsibilities**: What does each component do?
+3 - **Map Relationships**: How do components relate to each other?
+4 - **Note Boundaries**: Where are the logical boundaries?
+
+**Static Model Structure**:
+
+```markdown
+## Static Model: {project-name}
+
+### Overview
+- **Project Type**: {type}
+- **Primary Language**: {language}
+- **Components Identified**: {N}
+
+### Components
+
+#### Component 1: {Name}
+- **Type**: {Class/Module/Service/Repository/etc.}
+- **Location**: `{file path}`
+- **Responsibility**: {Single responsibility description}
+- **Key Methods/Functions**:
+  - `{method1}`: {what it does}
+  - `{method2}`: {what it does}
+
+#### Component 2: {Name}
+...
+
+### Relationships
+
+```text
+┌─────────────────┐     uses      ┌─────────────────┐
+│   Component A   │──────────────►│   Component B   │
+└─────────────────┘               └─────────────────┘
+        │                                 │
+        │ extends                         │ implements
+        ▼                                 ▼
+┌─────────────────┐               ┌─────────────────┐
+│   Component C   │               │   Interface D   │
+└─────────────────┘               └─────────────────┘
+```
+
+### Dependency Graph
+
+- **{Component A}** depends on: {Component B}, {Component C}
+- **{Component B}** depends on: {External Service X}
+
+### Architectural Layers
+
+- **Domain Layer**: {components}
+- **Application Layer**: {components}
+- **Infrastructure Layer**: {components}
+- **External Integrations**: {components}
+
+### Technology Stack (Detected)
+
+- **Framework**: {detected framework}
+- **Database**: {detected DB client/ORM}
+- **External APIs**: {detected integrations}
+```
+
+**Checkpoint 1**: Present static model for validation.
+
+```markdown
+## Static Model Complete
+
+I've analyzed the codebase and created a static model capturing:
+
+- **{N} Components** identified
+- **{N} Relationships** mapped
+- **{N} Layers** defined
+
+### Key Findings
+- {Finding 1: e.g., "Clean separation between domain and infrastructure"}
+- {Finding 2: e.g., "Heavy coupling in payment module"}
+
+Does this static model accurately represent your codebase?
+
+1 - **Approve** - Proceed to dynamic model
+2 - **Revise** - Specify corrections
+3 - **Expand** - Analyze additional files
+```
+
+**Wait for user response.**
+
+---
+
+### Phase 4: Generate Dynamic Model
+
+**Objective**: Show how components interact to realize significant use cases.
+
+**Activities**:
+
+1 - **Identify Use Cases**: What are the key user flows?
+2 - **Trace Interactions**: Follow the call chain through components
+3 - **Document Data Flow**: What data moves between components?
+4 - **Note Side Effects**: What external effects occur?
+
+**Dynamic Model Structure**:
+
+```markdown
+## Dynamic Model: {project-name}
+
+### Significant Use Cases
+
+#### Use Case 1: {Name}
+
+**Trigger**: {What initiates this flow}
+**Actors**: {Who/what participates}
+
+**Interaction Sequence**:
+
+```text
+┌──────┐     1. Request      ┌───────────┐     2. Validate     ┌───────────┐
+│ User │────────────────────►│ Controller│────────────────────►│  Service  │
+└──────┘                     └───────────┘                     └───────────┘
+                                                                     │
+                                   ┌─────────────────────────────────┘
+                                   │ 3. Query
+                                   ▼
+                             ┌───────────┐     4. SQL          ┌──────────┐
+                             │Repository │────────────────────►│ Database │
+                             └───────────┘                     └──────────┘
+```
+
+**Step-by-Step**:
+1. {Step 1}: {Component A} receives {input} from {source}
+2. {Step 2}: {Component A} calls {Component B}.{method}({params})
+3. {Step 3}: {Component B} queries {Component C} for {data}
+4. {Step 4}: {Response} returned to {originator}
+
+**Data Flow**:
+- Input: {data structure}
+- Output: {data structure}
+- Side Effects: {external changes, events emitted}
+
+#### Use Case 2: {Name}
+...
+
+### Integration Points
+
+| Integration | Protocol | Direction | Data |
+|-------------|----------|-----------|------|
+| {External API} | REST | Outbound | {data} |
+| {Message Queue} | AMQP | Bidirectional | {events} |
+| {Database} | SQL | Bidirectional | {entities} |
+
+### Critical Paths
+
+- **Happy Path**: {primary success scenario}
+- **Error Handling**: {how errors propagate}
+- **Authentication Flow**: {if applicable}
+```
+
+**Checkpoint 2**: Present dynamic model for validation.
+
+```markdown
+## Dynamic Model Complete
+
+I've traced the key interactions and created a dynamic model capturing:
+
+- **{N} Use Cases** documented
+- **{N} Integration Points** identified
+- **{N} Data Flows** mapped
+
+### Coverage Assessment
+- ✅ {Use case 1} - Critical path covered
+- ✅ {Use case 2} - Happy path covered
+- ⚠️ {Use case 3} - Error handling paths need review
+
+Does this dynamic model accurately represent how your system behaves?
+
+1 - **Approve** - Finalize elevation
+2 - **Revise** - Specify corrections
+3 - **Add Use Case** - Document additional flows
+```
+
+**Wait for user response.**
+
+---
+
+### Phase 5: Finalize Elevation
+
+**Checkpoint 3**: Confirm models are ready.
+
+Save artifacts and present summary:
+
+```markdown
+## Code Elevation Complete
+
+### Models Created
+- ✅ `memory-bank/elevation/static-model.md`
+- ✅ `memory-bank/elevation/dynamic-model.md`
+
+### Summary
+- **Components**: {N} documented
+- **Relationships**: {N} mapped
+- **Use Cases**: {N} traced
+- **Integration Points**: {N} identified
+
+### What These Models Enable
+
+Inception Agent will use these to:
+- Understand what already exists before planning new features
+- Identify which components a new intent might affect
+- Suggest appropriate units based on existing structure
+
+Construction Agent will use these to:
+- Generate code consistent with existing patterns
+- Extend existing components rather than duplicating
+- Avoid breaking existing functionality
+
+### Next Steps
+
+1 - **Create intent** - Start planning a new feature
+2 - **Review models** - Look at models again
+3 - **Return to menu** - See other options
+
+**Recommended**: Create your first intent with `/iris-inception-agent`
+```
+
+---
+
+## Output Artifacts
+
+### Location (Project-Level)
+
+```text
+memory-bank/elevation/
+├── static-model.md     # Components, responsibilities, relationships
+├── dynamic-model.md    # Use case interactions, data flows
+└── elevation-log.md    # When elevated, what was analyzed
+```
+
+### Usage by Other Agents
+
+**Inception Agent**:
+- Loads elevation models when creating intents
+- Uses component list to suggest unit decomposition
+- References existing patterns in requirements
+
+**Construction Agent**:
+- Loads elevation models during bolt execution
+- References static model during Domain Design stage
+- References dynamic model during Logical Design stage
+
+---
+
+## Templates
+
+- **Static Model Template**: `.iris/aidlc/templates/construction/elevation-static-model-template.md`
+- **Dynamic Model Template**: `.iris/aidlc/templates/construction/elevation-dynamic-model-template.md`
+
+---
+
+## Transition
+
+After code elevation complete:
+
+- → **Master Agent** returns control
+- → Master offers to route to **Inception Agent**
+- → Elevation context available for all future intents
+
+---
+
+## Test Contract
+
+```yaml
+input: Existing codebase paths from project.yaml
+output: memory-bank/elevation/static-model.md, memory-bank/elevation/dynamic-model.md
+checkpoints: 3
+  - Checkpoint 1: Static model validated
+  - Checkpoint 2: Dynamic model validated
+  - Checkpoint 3: Models approved
+ai_dlc_alignment:
+  - Brownfield code elevation per spec Section V.2
+  - Semantic-rich modeling for AI context
+  - Static models (components, responsibilities, relationships)
+  - Dynamic models (use case interactions)
+  - Project-level analysis, reused across intents
+```

package/flows/aidlc/skills/master/explain-flow.md

@@ -71,16 +71,16 @@ AI-DLC is a reimagined development methodology where AI drives the workflow and
    - Output: Tested, working code
 
    **DDD Bolt** (for domain-heavy business logic):
-   - Stage 1: Domain Model → AI models entities, aggregates, events
-   - Stage 2: Technical Design → AI architects layers, APIs, data
+   - Stage 1: Domain Design → AI models entities, aggregates, events
+   - Stage 2: Logical Design → AI architects layers, APIs, data
    - Stage 3: ADR Analysis → Capture architectural decisions (optional)
-   - Stage 4: Implement → AI generates code from designs
-   - Stage 5: Test → AI writes and runs tests
+   - Stage 4: Code Generation → AI generates code from designs
+   - Stage 5: Testing → AI writes and runs tests
 
    **Simple Bolt** (for straightforward tasks):
    - Stage 1: Plan → Define what to build
-   - Stage 2: Implement → AI generates code
-   - Stage 3: Test → AI writes and runs tests
+   - Stage 2: Code Generation → AI generates code
+   - Stage 3: Testing → AI writes and runs tests
 
 3. **Operations** → Deploy & Monitor
    - Package deployment units

package/flows/aidlc/skills/master/project-init.md

@@ -13,7 +13,8 @@
 
 ## Success Metrics
 
-- ✅ project.yaml created with project type
+- ✅ project.yaml created with project type AND scenario (greenfield/brownfield/hybrid)
+- ✅ Scenario detected automatically with user confirmation
 - ✅ Standards created in correct order (dependencies respected)
 - ✅ Each question is single-focus (not combined)
 - ✅ Final summary shows all created/skipped standards
@@ -24,6 +25,7 @@
 - ❌ Asking multiple questions at once
 - ❌ Creating standard before its dependencies
 - ❌ Not creating project.yaml
+- ❌ Not detecting/asking about greenfield vs brownfield scenario
 
 ---
 
@@ -85,26 +87,112 @@ Use the project type to determine:
 - Recommended standards (suggest, but optional)
 - Skippable standards (not relevant)
 
-**IMPORTANT**: After determining project type, immediately save it to `memory-bank/project.yaml`:
+**IMPORTANT**: After determining project type, proceed to scenario detection before saving project.yaml.
+
+### 3. Detect Project Scenario (Greenfield vs Brownfield)
+
+**AI-DLC requires different workflows for new vs existing projects.**
+
+#### Step 3a: Auto-detect existing code
+
+Check for existing code in common directories:
+
+```text
+Check these directories:
+- src/
+- lib/
+- app/
+- packages/
+
+If ANY contain source files (*.js, *.ts, *.py, etc.) → Suggest brownfield
+If ALL are empty or don't exist → Suggest greenfield
+```
+
+#### Step 3b: Confirm with user
+
+**If existing code detected:**
+
+```markdown
+## Project Scenario
+
+I detected existing code in your project:
+- `src/` - {n} files found
+- `lib/` - {n} files found
+
+This appears to be a **brownfield** project (enhancing existing code).
+
+1. **Brownfield** - Yes, I'm adding to/modifying existing code
+2. **Greenfield** - No, ignore existing code, starting fresh
+3. **Hybrid** - Some features will modify existing, some are new
+
+This affects how the Construction Agent works:
+- **Brownfield**: Runs code elevation first to understand existing structure
+- **Greenfield**: Starts fresh with domain modeling
+- **Hybrid**: Asks per-intent which flow to use
+```
+
+**If no existing code detected:**
+
+```markdown
+## Project Scenario
+
+No existing code detected. This appears to be a **greenfield** project.
+
+1. **Greenfield** - Yes, this is a new project (recommended)
+2. **Brownfield** - Actually, there's existing code elsewhere
+3. **Hybrid** - Planning to integrate with existing code later
+
+This affects how the Construction Agent works.
+```
+
+#### Step 3c: Capture existing codebase paths (if brownfield/hybrid)
+
+If user selected brownfield or hybrid:
+
+```markdown
+## Existing Code Location
+
+Where is your existing code located?
+
+Common paths I'll analyze during code elevation:
+- `src/` - main source
+- `lib/` - libraries
+- `app/` - application code
+
+1. **Use defaults** - src/, lib/, app/
+2. **Specify paths** - I'll list specific directories
+```
+
+### 4. Save project.yaml
+
+**IMPORTANT**: After determining BOTH project type AND scenario, save to `memory-bank/project.yaml`:
 
 ```yaml
 # Project Configuration
 # Generated by project-init
 
-project_type: {selected-type}  # e.g., full-stack-web, backend-api, frontend-app, cli-tool, library
+project_type: {selected-type}  # full-stack-web, backend-api, frontend-app, cli-tool, library
+scenario: {scenario}           # greenfield, brownfield, hybrid
 initialized_at: {ISO timestamp}
+
+# Only present if brownfield or hybrid
+existing_codebase:
+  paths:
+    - src/
+    - lib/
+  detected_files: {count}      # Number of source files found
 ```
 
-This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception) read it to provide context-aware suggestions.
+This file MUST be created before proceeding to standards facilitation, as other agents (e.g., Inception, Construction) read it to provide context-aware behavior.
 
-### 3. Check Existing Standards
+### 5. Check Existing Standards
 
 Before creating new standards, check if any exist:
 
 - Read `standards/` directory
 - If files exist, ask: "I found existing standards. Do you want to review and update them, or start fresh?"
 
-### 4. Facilitate Each Standard
+### 6. Facilitate Each Standard
 
 For each required/recommended standard:
 
@@ -115,7 +203,7 @@ For each required/recommended standard:
 5. **Generate the standard file** - using the output format in the guide
 6. **Save to path** defined in catalog (`output_path`)
 
-### 5. Order of Standards
+### 7. Order of Standards
 
 Follow dependency order from catalog:
 
@@ -127,7 +215,7 @@ Follow dependency order from catalog:
 
 Never create a standard before its dependencies are satisfied.
 
-### 6. Handle Optional Standards
+### 8. Handle Optional Standards
 
 For optional/recommended standards:
 
@@ -221,6 +309,12 @@ After completing all standards:
 ```markdown
 ## Project Initialization Complete
 
+### Project Configuration
+
+- **Type**: {project type} (e.g., full-stack-web)
+- **Scenario**: {scenario} (greenfield/brownfield/hybrid)
+- **Config**: `memory-bank/project.yaml`
+
 ### Standards Created
 
 - ✅ **Tech Stack**: Created at `standards/tech-stack.md`
@@ -231,18 +325,22 @@ After completing all standards:
 
 ### Summary
 
-Your project is configured as a **{project type}** using:
+Your project is configured as a **{project type}** ({scenario}) using:
 - **Language**: {language}
 - **Framework**: {framework}
 - **Database**: {database or "TBD"}
 
-### What These Standards Enable
+### What This Configuration Enables
 
-AI agents will now:
+**Standards** - AI agents will:
 - Generate code matching your style preferences
 - Use your chosen libraries and patterns
 - Follow your testing strategy
-- Understand your project structure
+
+**Scenario** - Construction Agent will:
+- {If greenfield}: Start with domain modeling (fresh design)
+- {If brownfield}: Run code elevation first (analyze existing code)
+- {If hybrid}: Ask per-intent which flow to use
 
 ### Actions