project-iris 0.0.12 → 0.0.14

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

@@ -0,0 +1,259 @@
+# Skill: Deploy to Environment
+
+---
+
+## Progress Display
+
+Show at start of this skill (varies by environment):
+
+```text
+### Operations Progress
+- [x] Build approval
+- [ ] Staging deploy  ← current (or)
+- [ ] Production deploy  ← current
+- [ ] Monitoring setup
+```
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 2 | Staging deploy approval | User confirmation |
+| Checkpoint 3 | Production deploy approval | User confirmation (⚠️ affects users) |
+
+---
+
+## Goal
+
+Deploy built artifacts to a target environment with progressive validation and rollback capability.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to deploy
+- **Required**: `--env` - Target environment (`dev`, `staging`, `prod`)
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--version` - Specific version (default: latest build)
+
+---
+
+## Process
+
+### 1. Verify Prerequisites
+
+- [ ] **Build exists**: Required for all environments
+- [ ] **Tests passing**: Required for all environments
+- [ ] **Deployed to dev**: Required for staging, prod
+- [ ] **Deployed to staging**: Required for prod
+- [ ] **Staging verification passed**: Required for prod
+
+### 2. Environment Progression
+
+```markdown
+## Deployment Progression
+
+Dev ──────► Staging ──────► Production
+ │            │               │
+ ▼            ▼               ▼
+Fast         Validation      Real users
+iteration    required        approval required
+```
+
+### 3. Pre-Deployment Checks
+
+For the target environment:
+
+- [ ] **Infrastructure**: Verify resources exist
+- [ ] **Secrets**: Confirm secrets configured
+- [ ] **Dependencies**: Check external services available
+- [ ] **Current version**: Record for rollback
+
+### 4. Execute Deployment
+
+Based on deployment type:
+
+- **Container** → Update container image
+- **Serverless** → Deploy function
+- **Static** → Sync to CDN/bucket
+- **Kubernetes** → Apply manifests
+
+### 5. Wait for Health
+
+Monitor deployment until healthy:
+
+- Health check endpoint responding
+- No crash loops
+- Readiness probes passing
+
+### 6. Document Deployment
+
+Append to `deployment/history.md`:
+
+```markdown
+---
+version: {version}
+environment: {env}
+deployed: {timestamp}
+deployed_by: {user}
+status: success
+---
+
+## Deployment: {version} → {env}
+
+### Details
+
+- **Version**: `{version}`
+- **Environment**: {env}
+- **Timestamp**: {timestamp}
+- **Duration**: {duration}
+- **Previous Version**: `{prev-version}`
+
+### Changes
+{diff summary from previous version}
+
+### Rollback Command
+```text
+deploy --unit="{unit}" --env="{env}" --version="{prev-version}"
+```
+
+---
+
+## Output
+
+```markdown
+## Deployment Complete: {unit-name}
+
+### Status
+
+- **Version**: `{version}`
+- **Environment**: {env}
+- **Status**: ✅ Deployed
+- **Health**: ✅ Healthy
+
+### Deployment Details
+- Started: {start-time}
+- Completed: {end-time}
+- Duration: {duration}
+
+### Environment State
+
+- ✅ **Development**: `{version}` - Active
+- ✅ **Staging**: `{version}` - Active
+- ⏳ **Production**: `{prev-version}` - Awaiting
+
+### Documentation Updated
+- `{unit-path}/deployment/history.md`
+
+### Actions
+
+1 - **verify**: Verify this deployment
+2 - **deploy**: Deploy to next environment
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **verify** - Verify deployment in {env}
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Output (Production Approval Required)
+
+````markdown
+## Production Deployment: {unit-name}
+
+### ⚠️ PRODUCTION DEPLOYMENT APPROVAL REQUIRED
+
+This deployment will affect real users.
+
+### Pre-Deployment Checklist
+- [x] Staging deployment successful
+- [x] Staging verification passed
+- [x] All tests passing
+- [ ] **Human approval required**
+
+### Deployment Plan
+
+- **Version**: `{version}`
+- **Current Production**: `{current-version}`
+- **Changes**: {summary}
+
+### Rollback Plan
+If issues detected:
+```text
+deploy --unit="{unit}" --env="prod" --version="{current-version}"
+```
+
+### Proceed?
+>
+> "⚠️ This will deploy to PRODUCTION. All staging checks passed. Approve deployment? (yes/no)"
+````
+
+---
+
+## Staging Deploy Confirmation
+
+**Checkpoint 2**: Ask user to confirm staging deploy:
+
+```text
+Ready to deploy to staging?
+
+Version: {version}
+Environment: Staging (production-like validation)
+
+This will update the staging environment.
+1 - Yes, deploy to staging
+2 - Cancel
+```
+
+**Wait for user response.**
+
+---
+
+## Production Deploy Confirmation
+
+**Checkpoint 3**: Ask user to confirm production deploy (⚠️ CRITICAL):
+
+```text
+⚠️ PRODUCTION DEPLOYMENT
+
+This affects real users.
+
+Version: {version}
+Current Production: {current-version}
+All staging tests: ✅ Passed
+
+Rollback command ready:
+  deploy --unit="{unit}" --env="prod" --version="{current-version}"
+
+Proceed with production deployment?
+1 - Yes, deploy to PRODUCTION
+2 - Cancel
+```
+
+**Wait for user response.**
+
+---
+
+## Transition
+
+After deploy approved and completed:
+
+- → **Verify** - verify deployment health
+- → **Monitor** - setup monitoring (after production)
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, version, environment
+output: Deployed artifact, history.md documentation
+checkpoints: 1-2
+  - Checkpoint 2: Staging deploy approved (if staging)
+  - Checkpoint 3: Production deploy approved (if production)
+```

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

@@ -0,0 +1,265 @@
+# Skill: Setup Monitoring
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Operations Progress
+- [x] Build approval
+- [x] Staging deploy
+- [x] Production deploy
+- [ ] Monitoring setup  ← current
+```
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 4 | Monitoring setup approval | User confirmation |
+
+---
+
+## Goal
+
+Configure observability (metrics, logging, alerting) for the unit and document operational runbooks.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to monitor
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--env` - Specific environment (default: all)
+
+---
+
+## Process
+
+### 1. Identify Key Metrics
+
+Implement RED method (Rate, Errors, Duration):
+
+- **Rate**: Requests/sec → Traffic patterns
+- **Errors**: Error rate, error types → Health indicator
+- **Duration**: Latency percentiles → Performance
+- **Saturation**: CPU, Memory, Connections → Capacity
+
+### 2. Define SLIs/SLOs
+
+Service Level Indicators and Objectives:
+
+- **Availability**: 99.9% (measured by uptime)
+- **Latency**: p95 < 200ms (measured by response time)
+- **Error Rate**: < 0.1% (measured by 5xx responses)
+- **Throughput**: > 1000 req/s (measured by requests per second)
+
+### 3. Configure Alerting
+
+Set up alerts for SLO violations:
+
+- **High Error Rate**: > 1% for 5min → Critical → Page on-call
+- **High Latency**: p95 > 500ms for 10min → Warning → Investigate
+- **Service Down**: Health check failing → Critical → Page on-call
+- **Resource Exhaustion**: CPU/Memory > 90% → Warning → Scale up
+
+### 4. Setup Logging
+
+Configure structured logging:
+
+```markdown
+### Log Configuration
+
+**Format**: JSON structured logs
+**Fields**:
+- timestamp
+- level
+- service
+- trace_id
+- message
+- context
+
+**Aggregation**: {log service}
+**Retention**: {days}
+```
+
+### 5. Create Dashboards
+
+Dashboard layout recommendation:
+
+```markdown
+### Dashboard Sections
+
+1. **Overview Panel**
+   - Request rate
+   - Error rate
+   - p50/p95/p99 latency
+   - Active instances
+
+2. **Errors Panel**
+   - Error breakdown by type
+   - Error rate trend
+   - Recent error logs
+
+3. **Performance Panel**
+   - Latency distribution
+   - Throughput trend
+   - Slow endpoints
+
+4. **Resources Panel**
+   - CPU usage
+   - Memory usage
+   - Connection pools
+```
+
+### 6. Document Runbooks
+
+Create operational runbooks:
+
+```markdown
+### Runbook: High Error Rate
+
+**Trigger**: Error rate > 1% for 5 minutes
+
+**Steps**:
+1. Check recent deployments
+2. Review error logs for patterns
+3. Check external dependencies
+4. If deployment-related: rollback
+5. If external: check status pages
+
+**Escalation**: If unresolved in 15 min, escalate to {team}
+```
+
+### 7. Document Configuration
+
+Create/update `deployment/monitoring.md`:
+
+```markdown
+---
+unit: {UUU}-{unit-name}
+configured: {timestamp}
+---
+
+## Monitoring Configuration: {unit-name}
+
+### Dashboards
+
+- **Overview**: {url} - General health
+- **Errors**: {url} - Error analysis
+- **Performance**: {url} - Latency tracking
+
+### Alerts
+
+- **High Error Rate**: > 1% → PagerDuty
+- **High Latency**: p95 > 500ms → Slack
+- **Service Down**: Health failing → PagerDuty
+
+### SLOs
+
+- **Availability**: 99.9% (30-day window)
+- **Latency (p95)**: < 200ms (30-day window)
+
+### Logs
+
+- **Location**: {log aggregator URL}
+- **Query**: `service="{unit}"`
+- **Retention**: {days}
+
+### Runbooks
+
+- **High Error Rate**: `runbook/high-error-rate.md`
+- **Performance Degradation**: `runbook/performance.md`
+- **Service Recovery**: `runbook/recovery.md`
+```
+
+---
+
+## Output
+
+```markdown
+## Monitoring Configured: {unit-name}
+
+### Status: ✅ COMPLETE
+
+### Observability Stack
+
+- ✅ **Metrics**: Configured at {metrics-url}
+- ✅ **Logging**: Configured at {logs-url}
+- ✅ **Alerting**: Configured at {alerts-url}
+- ✅ **Dashboards**: Created at {dashboard-url}
+
+### Alert Channels
+
+- **Critical**: PagerDuty
+- **Warning**: Slack
+- **Info**: Email
+
+### SLOs Defined
+
+- **Availability**: 99.9%
+- **Latency (p95)**: < 200ms
+- **Error Rate**: < 0.1%
+
+### Documentation Created
+- `{unit-path}/deployment/monitoring.md`
+
+### Operations Complete
+✅ Unit `{unit-name}` is now fully operational with monitoring.
+
+### Actions
+
+1 - **adjust**: Fine-tune alert thresholds
+2 - **runbook**: Create additional runbooks
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **menu** - Monitor for 24-48 hours, then return for adjustments
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Monitoring Setup Confirmation
+
+**Checkpoint 4**: Ask user to confirm monitoring setup:
+
+```text
+Ready to configure monitoring?
+
+This will set up:
+1. Dashboards (Overview, Errors, Performance)
+2. Alerts (Error rate, Latency, Health)
+3. SLOs (Availability, Latency targets)
+4. Runbooks (Incident response)
+
+Proceed with monitoring setup?
+1 - Yes, configure monitoring
+2 - Skip (not recommended for production)
+```
+
+**Wait for user response.**
+
+---
+
+## Transition
+
+After monitoring approved and completed:
+
+- → **Operations Complete** - unit is fully deployed and monitored
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, environment
+output: Dashboards, alerts, SLOs, runbooks, monitoring.md
+checkpoints: 1
+  - Checkpoint 4: Monitoring setup approved by user
+```

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

@@ -0,0 +1,209 @@
+# Skill: Operations Navigator
+
+---
+
+## Role
+
+Entry point for Operations Agent. Routes to appropriate skill based on state.
+
+**NO Checkpoint** - Navigator is a routing skill, not a decision point.
+
+---
+
+## Progress Display
+
+Show workflow position with checkpoint markers:
+
+```text
+### Operations Workflow (4 Checkpoints)
+
+[Prerequisites] Construction complete?
+      |
+[Checkpoint 1] Build approval --> build skill
+      |
+[Build + Deploy to Dev]
+      |
+[Checkpoint 2] Staging deploy --> deploy skill
+      |
+[Deploy to Staging + Verify]
+      |
+[Checkpoint 3] Production deploy --> deploy skill
+      |
+[Deploy to Production + Verify]
+      |
+[Checkpoint 4] Monitoring setup --> monitor skill
+      |
+[Operations Complete]
+```
+
+---
+
+## Goal
+
+Present the Operations Agent's skills and guide the user through the deployment and monitoring workflow.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to operate on
+- **Required**: `.iris/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Determine Context
+
+Load current operations state:
+
+**Prerequisites** (must pass before proceeding):
+
+- **Unit exists** - Path from `schema.units` (Required)
+- **All bolts complete** - Path from `schema.bolts` (Required)
+- **Tests passing** - Bolt completion status (Required)
+
+**Deployment Status** (from `deployment/` artifacts):
+
+- Build status and version
+- Deployment history per environment
+- Verification status
+- Monitoring status
+
+### 2. Present Menu
+
+Build menu dynamically using the Output sections below based on current state.
+
+### 3. Context-Aware Suggestions
+
+Based on deployment state:
+
+- **No build** → Build artifacts
+- **Build done, not deployed** → Deploy to dev
+- **Deployed to dev, not verified** → Verify dev
+- **Dev verified, not in staging** → Deploy to staging
+- **Staging verified, not in prod** → Deploy to production
+- **Prod deployed, not verified** → Verify production
+- **Prod verified, no monitoring** → Setup monitoring
+- **All complete** → Operations complete
+
+### 4. Handle Selection
+
+When user selects an option:
+
+1. Acknowledge the selection
+2. Load the corresponding skill file
+3. Execute with current context
+
+---
+
+## Output (Ready for Operations)
+
+```markdown
+## Operations Agent
+
+### Unit: `{unit-name}`
+**Construction Status**: ✅ Complete ({n} bolts)
+**Stories Delivered**: {n}
+
+### Deployment Status
+
+- [ ] Development: Not deployed
+- [ ] Staging: Not deployed
+- [ ] Production: Not deployed
+
+### Quick Actions
+
+1 - **Build artifacts**: Create deployment package (`build --unit="{unit}"`)
+2 - **View build history**: See previous builds (`build --unit="{unit}" --history`)
+
+### Workflow
+Build → Dev → Verify → Staging → Verify → Prod → Verify → Monitor
+
+### Suggested Next Step
+→ **Build deployment artifacts** to start the deployment pipeline
+
+**Type a number to continue.**
+```
+
+---
+
+## Output (Partially Deployed)
+
+```markdown
+## Operations Agent
+
+### Unit: `{unit-name}`
+**Latest Build**: `v{version}`
+
+### Deployment Status
+
+- ✅ Development: `v{version}` - Deployed, Verified
+- ⏳ Staging: `v{version}` - Deployed, Pending verification ← current
+- ⚠️ Production: `v{prev}` - Outdated, Verified
+
+### Quick Actions
+
+1 - **Verify staging**: Validate deployment (`verify --unit="{unit}" --env="staging"`)
+2 - **Deploy to prod**: Promote to production (`deploy --unit="{unit}" --env="prod"`)
+3 - **View history**: See deployment history (`history --unit="{unit}"`)
+
+### Suggested Next Step
+→ **Verify staging deployment** before promoting to production
+
+**Type a number to continue.**
+```
+
+---
+
+## Output (Fully Deployed)
+
+```markdown
+## Operations Agent
+
+### Unit: `{unit-name}`
+**Status**: ✅ FULLY OPERATIONAL
+
+### All Environments
+
+- ✅ Development: `v{version}` - Verified, Monitored
+- ✅ Staging: `v{version}` - Verified, Monitored
+- ✅ Production: `v{version}` - Verified, Monitored
+
+### Resources
+- Dashboard: {dashboard-url}
+- Logs: {logs-url}
+- Alerts: {alerts-url}
+
+### Available Actions
+
+1 - **View metrics**: Open monitoring dashboard
+2 - **View logs**: Open log aggregator
+3 - **Rollback**: Deploy previous version
+4 - **Deploy new version**: When code changes
+
+### Unit Complete
+✅ Unit `{unit-name}` is fully deployed and monitored.
+
+**Type a number or return to Master Agent.**
+```
+
+---
+
+## Transition
+
+After user selection:
+
+- → Load selected skill
+- → Skill contains the Checkpoint markers
+- → Execute skill process
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit state, deployment status
+output: Menu with skill options, suggested next step
+checkpoints: 0 (routing only)
+```