project-iris 0.0.16 → 0.0.18

package/flows/aidlc/skills/operations/build.md

@@ -51,7 +51,7 @@ Show at start of this skill:
 
 ## Goal
 
-Create deployable packages (containers, functions, bundles) for a Unit and document the build metadata.
+Create deployable packages (containers, functions, bundles) for a Unit and create/update the Deployment Unit artifact per AI-DLC specification.
 
 ---
 
@@ -63,6 +63,13 @@ Create deployable packages (containers, functions, bundles) for a Unit and docum
 
 ---
 
+## Template
+
+**Deployment Unit Template**: `.iris/aidlc/templates/operations/deployment-unit-template.md`
+**Output Location**: `memory-bank/operations/deployment-units/{unit-name}.md`
+
+---
+
 ## Process
 
 ### 1. Verify Prerequisites
@@ -115,7 +122,24 @@ Upload artifact to configured registry:
 - Package → Package registry
 - Function → Function storage
 
-### 6. Document Build
+### 6. Create/Update Deployment Unit
+
+Create or update `memory-bank/operations/deployment-units/{unit-name}.md` using the template:
+
+1. **If new**: Create from template with packaged artifacts section populated
+2. **If exists**: Update the Packaged Artifacts and Deployment History sections
+
+**Required sections to populate:**
+- Packaged Artifacts (executable code, registry location)
+- Version and status
+- Build timestamp
+
+**Sections populated by other skills:**
+- Test Validation → populated by `verify` skill
+- Deployment History → updated by `deploy` skill
+- Monitoring Integration → populated by `monitor` skill
+
+### 7. Document Build
 
 Create/update `deployment/build.md`:
 
@@ -175,7 +199,8 @@ status: success
 
 ### Documentation Updated
 
-- `{unit-path}/deployment/build.md`
+- `memory-bank/operations/deployment-units/{unit-name}.md` (Deployment Unit)
+- `{unit-path}/deployment/build.md` (Build metadata)
 
 ### Actions
 
@@ -256,7 +281,10 @@ After build approved and completed:
 
 ```yaml
 input: Unit name, version
-output: Deployable artifact, build.md documentation
+output:
+  - Deployable artifact (container/function/package)
+  - memory-bank/operations/deployment-units/{unit}.md (Deployment Unit)
+  - deployment/build.md (Build metadata)
 checkpoints: 1
   - Checkpoint 1: Build approved by user
 ```

package/flows/aidlc/skills/operations/monitor.md

@@ -15,8 +15,9 @@
 
 - ✅ Dashboards created and linked
 - ✅ Alerts configured with thresholds
-- ✅ SLOs defined
-- ✅ Runbooks documented
+- ✅ SLOs defined (traced to requirements.md)
+- ✅ Runbooks documented and stored in `memory-bank/operations/playbooks/`
+- ✅ AI recommendations enabled based on playbooks
 
 ## Failure Modes
 
@@ -24,6 +25,7 @@
 - ❌ Missing dashboard URLs
 - ❌ Alerts without thresholds
 - ❌ No runbooks for common issues
+- ❌ SLOs not traced to requirements
 
 ---
 
@@ -51,7 +53,7 @@ Show at start of this skill:
 
 ## Goal
 
-Configure observability (metrics, logging, alerting) for the unit and document operational runbooks.
+Configure observability (metrics, logging, alerting) for the unit and document operational runbooks. Per AI-DLC specification, AI integrates with predefined incident runbooks to propose actionable recommendations for operational issues.
 
 ---
 
@@ -59,10 +61,25 @@ Configure observability (metrics, logging, alerting) for the unit and document o
 
 - **Required**: `--unit` - The unit to monitor
 - **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Required**: `memory-bank/intents/{intent}/requirements.md` - SLOs from requirements
 - **Optional**: `--env` - Specific environment (default: all)
 
 ---
 
+## Context Loading
+
+Before configuring monitoring, load:
+
+1. **Requirements** (`memory-bank/intents/{intent}/requirements.md`)
+   - Extract SLOs from Measurement Criteria section
+   - Use defined latency, availability, throughput targets
+
+2. **Existing Playbooks** (`memory-bank/operations/playbooks/`)
+   - Check for existing runbooks to extend
+   - Ensure consistency across units
+
+---
+
 ## Process
 
 ### 1. Identify Key Metrics
@@ -74,9 +91,24 @@ Implement RED method (Rate, Errors, Duration):
 - **Duration**: Latency percentiles → Performance
 - **Saturation**: CPU, Memory, Connections → Capacity
 
-### 2. Define SLIs/SLOs
+### 2. Define SLIs/SLOs (From Requirements)
+
+**IMPORTANT**: SLOs must trace to the Measurement Criteria defined in `requirements.md`.
+
+Load SLOs from requirements and configure monitoring:
+
+```markdown
+### SLO Traceability
+
+| SLO | Target | Source | Alert Threshold |
+|-----|--------|--------|-----------------|
+| Availability | {from requirements} | requirements.md | < target - 0.1% |
+| Latency (p95) | {from requirements} | requirements.md | > target + 50ms |
+| Error Rate | {from requirements} | requirements.md | > target + 0.05% |
+| Throughput | {from requirements} | requirements.md | < target - 10% |
+```
 
-Service Level Indicators and Objectives:
+Default SLOs (if not specified in requirements):
 
 - **Availability**: 99.9% (measured by uptime)
 - **Latency**: p95 < 200ms (measured by response time)
@@ -141,14 +173,25 @@ Dashboard layout recommendation:
    - Connection pools
 ```
 
-### 6. Document Runbooks
+### 6. Document Runbooks (Playbook Integration)
+
+Per AI-DLC specification: "AI integrates with predefined incident runbooks, proposing actionable recommendations such as resource scaling, performance tuning, or fault isolation."
 
-Create operational runbooks:
+**Playbook Storage**: `memory-bank/operations/playbooks/`
+
+Create operational runbooks that AI can reference to propose actions:
 
 ```markdown
 ### Runbook: High Error Rate
 
 **Trigger**: Error rate > 1% for 5 minutes
+**Playbook File**: `memory-bank/operations/playbooks/high-error-rate.md`
+
+**AI Recommendations** (proposed when triggered):
+1. Check recent deployments → If found, propose rollback
+2. Review error logs → Propose fix based on error pattern
+3. Check external dependencies → Propose circuit breaker or fallback
+4. Resource issues → Propose scaling action
 
 **Steps**:
 1. Check recent deployments
@@ -160,6 +203,14 @@ Create operational runbooks:
 **Escalation**: If unresolved in 15 min, escalate to {team}
 ```
 
+**Required Playbooks** (create in `memory-bank/operations/playbooks/`):
+
+1. `high-error-rate.md` - Error rate exceeds threshold
+2. `high-latency.md` - Latency exceeds SLO
+3. `service-down.md` - Health check failures
+4. `resource-exhaustion.md` - CPU/Memory critical
+5. `deployment-failure.md` - Deployment rollback procedures
+
 ### 7. Document Configuration
 
 Create/update `deployment/monitoring.md`:
@@ -184,10 +235,13 @@ configured: {timestamp}
 - **High Latency**: p95 > 500ms → Slack
 - **Service Down**: Health failing → PagerDuty
 
-### SLOs
+### SLOs (Traced to Requirements)
 
-- **Availability**: 99.9% (30-day window)
-- **Latency (p95)**: < 200ms (30-day window)
+| SLO | Target | Source |
+|-----|--------|--------|
+| Availability | 99.9% | requirements.md → Measurement Criteria |
+| Latency (p95) | < 200ms | requirements.md → Measurement Criteria |
+| Error Rate | < 0.1% | requirements.md → Measurement Criteria |
 
 ### Logs
 
@@ -195,11 +249,18 @@ configured: {timestamp}
 - **Query**: `service="{unit}"`
 - **Retention**: {days}
 
-### Runbooks
+### Playbooks (AI-Integrated)
+
+Location: `memory-bank/operations/playbooks/`
+
+| Playbook | Trigger | AI Action |
+|----------|---------|-----------|
+| `high-error-rate.md` | Error > 1% | Propose rollback or fix |
+| `high-latency.md` | p95 > SLO | Propose scaling or optimization |
+| `service-down.md` | Health failing | Propose restart or failover |
+| `resource-exhaustion.md` | CPU/Mem > 90% | Propose scale-up |
 
-- **High Error Rate**: `runbook/high-error-rate.md`
-- **Performance Degradation**: `runbook/performance.md`
-- **Service Recovery**: `runbook/recovery.md`
+AI will reference these playbooks to propose actionable recommendations during incidents.
 ```
 
 ---

package/flows/aidlc/skills/operations/rollback.md

@@ -0,0 +1,239 @@
+# Skill: Rollback Deployment
+
+---
+
+## 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 rollback target version clearly
+- ⚠️ **ALWAYS** display warnings prominently for production rollbacks
+- 🛑 **STOP** at rollback confirmation - require explicit approval
+
+## Success Metrics
+
+- ✅ Previous stable version identified
+- ✅ Rollback executed successfully
+- ✅ Verification completed after rollback
+- ✅ Incident documented
+
+## Failure Modes
+
+- ❌ Rollback without confirmation
+- ❌ Missing verification after rollback
+- ❌ Not documenting the incident
+
+---
+
+## Goal
+
+Safely rollback a deployment to a previous stable version when issues are detected.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to rollback
+- **Required**: `--env` - Environment to rollback (dev, staging, production)
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--version` - Specific version to rollback to (default: previous stable)
+
+---
+
+## Process
+
+### 1. Verify Current State
+
+Check deployment status:
+
+- [ ] **Current version**: Identify deployed version
+- [ ] **Issue detected**: Document the problem triggering rollback
+- [ ] **Previous versions**: List available rollback targets
+
+### 2. Identify Rollback Target
+
+```markdown
+## Rollback Target
+
+**Current Version**: {current-version}
+**Issue**: {issue-description}
+
+### Available Rollback Targets
+
+1 - **{previous-version}**: Deployed {timestamp} - Status: stable
+2 - **{older-version}**: Deployed {timestamp} - Status: stable
+
+### Recommended Target
+
+→ **{previous-version}** - Last known stable version
+```
+
+### 3. Rollback Confirmation
+
+**Checkpoint**: Ask user to confirm rollback:
+
+```text
+⚠️ Rollback Confirmation Required
+
+Environment: {env}
+Current Version: {current-version}
+Target Version: {target-version}
+
+This will:
+1. Stop current deployment
+2. Deploy previous version
+3. Verify rollback success
+
+Proceed with rollback?
+1 - Yes, rollback
+2 - Cancel
+```
+
+**Wait for user response.**
+
+### 4. Execute Rollback
+
+Perform rollback steps:
+
+1. **Stop current deployment**: Graceful shutdown
+2. **Deploy target version**: Use existing deployment artifacts
+3. **Health check**: Verify service is responding
+4. **Traffic routing**: Restore traffic to rolled-back version
+
+### 5. Verify Rollback
+
+Run verification checks:
+
+- [ ] **Health endpoints**: All responding
+- [ ] **Smoke tests**: Critical paths working
+- [ ] **Error rates**: Back to baseline
+- [ ] **Latency**: Within acceptable range
+
+### 6. Document Incident
+
+Update deployment history in `memory-bank/operations/deployment-units/{unit-name}.md`:
+
+```markdown
+## Rollback Record
+
+| Date | From | To | Environment | Reason | Status |
+|------|------|------|-------------|--------|--------|
+| {timestamp} | {from-version} | {to-version} | {env} | {reason} | ✅ success |
+```
+
+Create incident record if production:
+
+```markdown
+## Incident: {timestamp}
+
+### Summary
+Rollback from {from-version} to {to-version} in {env}
+
+### Root Cause
+{description of issue}
+
+### Timeline
+- {time}: Issue detected
+- {time}: Rollback initiated
+- {time}: Rollback completed
+- {time}: Verification passed
+
+### Action Items
+- [ ] Investigate root cause
+- [ ] Fix issue in codebase
+- [ ] Re-deploy when fixed
+```
+
+---
+
+## Output
+
+```markdown
+## Rollback Complete: {unit-name}
+
+### Status: ✅ SUCCESS
+
+### Details
+
+- **Environment**: {env}
+- **Previous Version**: {from-version}
+- **Current Version**: {to-version}
+- **Rollback Time**: {duration}
+
+### Verification Results
+
+- ✅ Health checks passing
+- ✅ Smoke tests passing
+- ✅ Error rate normal
+- ✅ Latency within bounds
+
+### Documentation Updated
+
+- `memory-bank/operations/deployment-units/{unit-name}.md`
+
+### Actions
+
+1 - **investigate**: Review logs for root cause
+2 - **redeploy**: Attempt deployment again after fix
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+
+→ **investigate** - Review logs to identify root cause
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Output (Rollback Failed)
+
+```markdown
+## Rollback Failed: {unit-name}
+
+### Error
+```text
+{error message}
+```
+
+### Current State
+
+- **Environment**: {env}
+- **Attempted Target**: {target-version}
+- **Actual State**: {current-state}
+
+### Immediate Actions
+
+1. Check infrastructure status
+2. Review deployment logs
+3. Consider manual intervention
+4. Escalate if needed
+
+### Emergency Contacts
+
+{From project configuration or runbooks}
+```
+
+---
+
+## Transition
+
+After rollback:
+
+- → **investigate**: Review logs for root cause
+- → **menu**: Return to operations menu
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, environment, target version (optional)
+output:
+  - Rolled back deployment
+  - Updated deployment history
+  - Incident documentation (if production)
+checkpoints: 1
+  - Rollback confirmation by user
+```

package/flows/aidlc/templates/README.md

@@ -0,0 +1,128 @@
+# AI-DLC Templates
+
+Templates provide consistent structure for artifacts created during the AI-DLC workflow. Each template corresponds to an artifact type defined in `../memory-bank.yaml`.
+
+## Directory Structure
+
+```text
+templates/
+├── inception/                           # Inception phase templates
+│   ├── requirements-template.md         # Requirements document
+│   ├── prfaq-template.md                # Press Release / FAQ
+│   ├── risks-template.md                # Risk assessment
+│   ├── system-context-template.md       # System context diagram
+│   ├── units-template.md                # Unit decomposition overview
+│   ├── unit-brief-template.md           # Individual unit brief
+│   ├── stories-template.md              # Stories collection
+│   ├── story-template.md                # Individual user story
+│   └── inception-log-template.md        # Inception progress log
+│
+├── construction/                        # Construction phase templates
+│   ├── bolt-template.md                 # Bolt instance metadata
+│   ├── construction-guide.md            # Construction workflow guide
+│   ├── construction-log-template.md     # Construction progress log
+│   ├── elevation-static-model-template.md   # Brownfield static model
+│   ├── elevation-dynamic-model-template.md  # Brownfield dynamic model
+│   │
+│   ├── bolt-types/                      # Bolt type definitions
+│   │   ├── ddd-construction-bolt.md     # DDD bolt (5 stages)
+│   │   ├── simple-construction-bolt.md  # Simple bolt (3 stages)
+│   │   ├── spike-bolt.md                # Research/exploration bolt
+│   │   │
+│   │   └── ddd-construction-bolt/       # DDD bolt stage templates
+│   │       ├── ddd-01-domain-design-template.md    # Domain design
+│   │       ├── ddd-02-logical-design-template.md   # Logical design
+│   │       ├── ddd-03-test-report-template.md      # Test report
+│   │       └── adr-template.md                     # ADR template
+│   │
+│   └── standards/                       # Standards templates
+│       ├── tech-stack.md                # Tech stack template
+│       ├── coding-standards.md          # Coding standards template
+│       └── system-architecture.md       # Architecture template
+│
+├── operations/                          # Operations phase templates
+│   └── deployment-unit-template.md      # Deployment unit documentation
+│
+└── standards/                           # Standards facilitation
+    ├── catalog.yaml                     # Standards registry
+    ├── tech-stack.guide.md              # Tech stack guide
+    ├── coding-standards.guide.md        # Coding standards guide
+    └── data-stack.guide.md              # Data stack guide
+```
+
+## Template Usage
+
+### Inception Templates
+Used by Inception Agent skills to create planning artifacts:
+- **requirements-template.md**: Captures functional and non-functional requirements
+- **prfaq-template.md**: Documents business intent and expected benefits
+- **risks-template.md**: Identifies and assesses project risks
+- **unit-brief-template.md**: Defines scope and details for each unit
+
+### Construction Templates
+Used by Construction Agent during bolt execution:
+
+**Bolt Types** define the stages and checkpoints for different types of work:
+- **ddd-construction-bolt.md**: For complex business logic (5 stages)
+  1. Domain Design
+  2. Logical Design
+  3. ADR Analysis (optional)
+  4. Code Generation
+  5. Testing
+
+- **simple-construction-bolt.md**: For UI/integrations (3 stages)
+  1. Plan
+  2. Code Generation
+  3. Testing
+
+- **spike-bolt.md**: For research and exploration
+
+**Stage Templates** (in `bolt-types/ddd-construction-bolt/`):
+- **ddd-01-domain-design-template.md**: Entities, value objects, aggregates
+- **ddd-02-logical-design-template.md**: APIs, schemas, cloud resources
+- **ddd-03-test-report-template.md**: Test results and coverage
+
+### Operations Templates
+Used by Operations Agent for deployment:
+- **deployment-unit-template.md**: Documents deployment artifacts, configurations, and infrastructure
+
+### Standards Templates
+Used by Master Agent during project initialization:
+- Facilitation guides help agents gather project standards through conversation
+- Standards are saved to `memory-bank/standards/`
+
+## Template Structure
+
+Templates use YAML frontmatter for metadata and markdown for content:
+
+```markdown
+---
+unit: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+status: draft | complete
+---
+
+# {Artifact Title}
+
+## Section 1
+{Content with placeholders like {placeholder}}
+
+## Section 2
+{More content}
+```
+
+## Key Conventions
+
+1. **Placeholders**: Use `{placeholder-name}` for values to be filled in
+2. **Numbering**: Use `{NNN}` for 3-digit intent numbers, `{UUU}` for unit numbers, `{BBB}` for bolt numbers
+3. **Timestamps**: Use ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
+4. **Status values**: Consistent across templates (draft, complete, in-progress, etc.)
+
+## Adding New Templates
+
+1. Create template in the appropriate phase folder
+2. Include YAML frontmatter with required fields
+3. Use consistent placeholder naming
+4. Document the template's purpose in the header
+5. Reference the template in relevant skill files

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

@@ -15,8 +15,8 @@ Use this template when creating new bolt instances during bolt planning.
 ```text
 memory-bank/bolts/{bolt-id}/
 ├── bolt.md                      # Bolt instance metadata (this template)
-├── ddd-01-domain-model.md       # Stage 1 artifact (created during execution)
-├── ddd-02-technical-design.md   # Stage 2 artifact (created during execution)
+├── ddd-01-domain-design.md      # Stage 1 artifact (created during execution)
+├── ddd-02-logical-design.md     # Stage 2 artifact (created during execution)
 └── ddd-03-test-report.md        # Stage 4 artifact (created during execution)
 ```
 
@@ -167,7 +167,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
 
 requires_bolts: []
 enables_bolts:
@@ -204,8 +204,8 @@ Implement core authentication functionality including user registration with ema
 
 ## Stages
 
-- ✅ **1. model**: Complete → ddd-01-domain-model.md
-- ⏳ **2. design**: In Progress → ddd-02-technical-design.md ← current
+- ✅ **1. model**: Complete → ddd-01-domain-design.md
+- ⏳ **2. design**: In Progress → ddd-02-logical-design.md ← current
 - [ ] **3. implement**: Pending → src/auth-service/
 - [ ] **4. test**: Pending → ddd-03-test-report.md
 

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/{ddd-02-technical-design-template.md → ddd-02-logical-design-template.md}

@@ -6,7 +6,7 @@ status: complete
 updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
-# Technical Design - {Unit Name}
+# Logical Design - {Unit Name}
 
 ## Architecture Pattern