specsmd 0.0.1

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**: `.specsmd/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: {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**: `.specsmd/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)
+```

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

@@ -0,0 +1,224 @@
+# Skill: Verify Deployment
+
+---
+
+## Role
+
+Post-deployment validation skill. Runs health checks and smoke tests.
+
+**NO Checkpoint** - Verification is an automated check, not a decision point.
+
+Verification happens after each deploy skill checkpoint. If verification fails, recommend rollback.
+
+---
+
+## Goal
+
+Confirm that a deployment is healthy, functional, and meeting acceptance criteria before proceeding to next environment.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to verify
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--env` - Target environment (default: last deployed)
+- **Optional**: `--version` - Specific version (default: currently deployed)
+
+---
+
+## Process
+
+### 1. Load Deployment Context
+
+From `deployment/history.md`:
+
+- Current deployed version
+- Deployment timestamp
+- Previous version (for comparison)
+
+### 2. Execute Health Checks
+
+- [ ] **Endpoint Health**: GET `/health` → 200 OK
+- [ ] **Readiness**: GET `/ready` → 200 OK
+- [ ] **Database**: Connection test → Connected
+- [ ] **Cache**: Connection test → Connected
+- [ ] **External APIs**: Connectivity check → Reachable
+
+### 3. Run Smoke Tests
+
+Execute critical path tests:
+
+- [ ] **Authentication**: Login flow works (if applicable)
+- [ ] **Core CRUD**: Basic operations work (required)
+- [ ] **API Endpoints**: Key endpoints respond (required)
+- [ ] **Error Handling**: Errors handled gracefully (required)
+
+### 4. Check Metrics
+
+Verify operational metrics are within bounds:
+
+- [ ] **Response Time**: < SLA (p95 latency)
+- [ ] **Error Rate**: < 1% (4xx/5xx responses)
+- [ ] **CPU**: < 80% (resource utilization)
+- [ ] **Memory**: < 80% (resource utilization)
+
+### 5. Compare to Baseline
+
+If previous version exists:
+
+- Error rate comparison
+- Latency comparison
+- Resource usage comparison
+
+### 6. Document Results
+
+Create `deployment/verification-{version}.md`:
+
+```markdown
+---
+version: {version}
+environment: {env}
+verified: {timestamp}
+status: passed|failed
+---
+
+## Verification Report: {version}
+
+### Health Checks
+
+- ✅ **Endpoint**: 200 OK, 15ms
+- ✅ **Database**: Connected
+- ✅ **Cache**: Connected
+
+### Smoke Tests
+
+- ✅ **Login Flow**: 234ms
+- ✅ **Create Item**: 156ms
+- ✅ **API Health**: 12ms
+
+### Metrics
+
+- ✅ **p95 Latency**: 145ms (threshold: <200ms)
+- ✅ **Error Rate**: 0.02% (threshold: <1%)
+
+### Baseline Comparison
+
+- **p95 Latency**: 142ms → 145ms (+2%)
+- **Error Rate**: 0.01% → 0.02% (+0.01%)
+
+### Conclusion
+{passed|failed}: {summary}
+```
+
+---
+
+## Output (Verification Passed)
+
+```markdown
+## Verification Passed: {unit-name}
+
+### Status: ✅ VERIFIED
+
+### Results Summary
+
+- ✅ **Health Checks**: {n}/{n} passed
+- ✅ **Smoke Tests**: {n}/{n} passed
+- ✅ **Metric Checks**: {n}/{n} passed
+
+### Key Metrics
+
+- ✅ **Response Time (p95)**: {value}ms
+- ✅ **Error Rate**: {value}%
+- ✅ **Uptime**: 100%
+
+### Environment Status
+
+- ✅ **{env}**: `{version}` - Verified
+
+### Documentation Created
+- `{unit-path}/deployment/verification-{version}.md`
+
+### Actions
+
+1 - **monitor**: Setup monitoring for this unit
+2 - **deploy**: Deploy to next environment
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **monitor** - Setup monitoring for `{unit-name}`
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Output (Verification Failed)
+
+```markdown
+## Verification Failed: {unit-name}
+
+### Status: ❌ FAILED
+
+### Failed Checks
+
+- ❌ **{check1}**: Expected {expected}, got {actual}
+- ❌ **{check2}**: Expected {expected}, got {actual}
+
+### Error Details
+{error messages or logs}
+
+### Impact Assessment
+
+- **Severity**: {critical|high|medium|low}
+- **Affected**: {what's broken}
+
+### Recommended Action
+⚠️ **ROLLBACK RECOMMENDED**
+
+Previous stable version: `{prev-version}`
+
+Rollback command:
+deploy --unit="{unit}" --env="{env}" --version="{prev-version}"
+
+### Actions
+
+1 - **rollback**: Rollback to previous version
+2 - **investigate**: Investigate root cause
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **rollback** - Restore `{prev-version}` immediately
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+On success:
+> "Verification passed for `{unit}` v`{version}` in {env}. All {n} checks passed. Ready to proceed to {next-action}?"
+
+On failure:
+> "⚠️ Verification FAILED for `{unit}` v`{version}`. {n} checks failed. Recommend rollback to `{prev-version}`. Proceed with rollback?"
+
+---
+
+## Transition
+
+After verification:
+
+- → **Monitor** (`.specsmd/skills/operations/monitor.md`) - if verified and final environment
+- → **Deploy** (`.specsmd/skills/operations/deploy.md`) - to next environment if verified
+- → **Rollback** - if verification fails (deploy previous version)
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, environment, version
+output: Verification report with health checks, smoke tests, metrics
+checkpoints: 0 (automated validation only)
+```