@garethdaine/agentops 0.9.0

package/templates/communication/post-mortem.md

@@ -0,0 +1,109 @@
+# Communication Template: Post-Mortem / RCA
+
+*Distinct from the incident response template — this is the after-action review conducted 2-5 days after an incident is resolved.*
+
+```markdown
+# Post-Mortem: [Incident Title]
+
+**Incident date:** [date]
+**Post-mortem date:** [date]
+**Severity:** P1 / P2 / P3
+**Duration:** [hours/minutes from detection to resolution]
+**Author:** [name]
+**Attendees:** [names of post-mortem participants]
+
+---
+
+## Summary
+
+[2-3 sentences: what happened, who was affected, how it was resolved]
+
+---
+
+## Timeline
+
+| Time (UTC) | Event |
+|-----------|-------|
+| [HH:MM] | [First sign of issue — alert, user report, monitoring] |
+| [HH:MM] | [Issue acknowledged by on-call] |
+| [HH:MM] | [Investigation started] |
+| [HH:MM] | [Root cause identified] |
+| [HH:MM] | [Fix deployed] |
+| [HH:MM] | [Monitoring confirms resolution] |
+| [HH:MM] | [All-clear communicated to stakeholders] |
+
+---
+
+## Root Cause Analysis
+
+### What happened?
+[Factual description of the failure chain]
+
+### 5 Whys
+1. **Why** did [symptom] occur? → Because [cause 1]
+2. **Why** did [cause 1] happen? → Because [cause 2]
+3. **Why** did [cause 2] happen? → Because [cause 3]
+4. **Why** did [cause 3] happen? → Because [cause 4]
+5. **Why** did [cause 4] happen? → Because [root cause]
+
+### Contributing Factors
+- [Factor that made the impact worse or detection slower]
+- [Factor — e.g., missing monitoring, documentation gap, test gap]
+
+---
+
+## Impact
+
+| Metric | Value |
+|--------|-------|
+| Users affected | [count or percentage] |
+| Duration | [time] |
+| Revenue impact | [if applicable] |
+| Data affected | [any data loss/corruption — be specific] |
+| SLA breach | Yes/No — [details] |
+
+---
+
+## What Went Well
+
+1. [Thing that worked — detection, response, communication]
+2. [Thing that worked]
+3. [Thing that worked]
+
+## What Went Poorly
+
+1. [Thing that didn't work — slow detection, unclear runbook, missing test]
+2. [Thing that didn't work]
+3. [Thing that didn't work]
+
+## Where We Got Lucky
+
+1. [Thing that could have been worse but wasn't — acknowledge luck explicitly]
+
+---
+
+## Action Items
+
+| # | Action | Type | Owner | Due Date | Status |
+|---|--------|------|-------|----------|--------|
+| 1 | [preventive action] | Prevention | [name] | [date] | Open |
+| 2 | [detective action — better monitoring] | Detection | [name] | [date] | Open |
+| 3 | [process improvement] | Process | [name] | [date] | Open |
+
+**Types:**
+- **Prevention** — stop this from happening again
+- **Detection** — catch it faster next time
+- **Mitigation** — reduce impact if it does happen
+- **Process** — improve response procedures
+
+---
+
+## Follow-up Review
+
+**Scheduled:** [date, 2-4 weeks after post-mortem]
+**Purpose:** Verify all action items are completed and effective
+
+---
+
+*This post-mortem is blameless. We focus on systems and processes, not individuals. The goal is to learn and improve, not to assign fault.*
+```

package/templates/communication/risk-register.md

@@ -0,0 +1,43 @@
+# Communication Template: Risk Register
+
+```markdown
+# Risk Register — [Project Name]
+
+**Last updated:** [date]
+**Owner:** [name]
+
+## Active Risks
+
+| ID | Risk | Category | Likelihood | Impact | Score | Owner | Mitigation | Status |
+|----|------|----------|-----------|--------|-------|-------|------------|--------|
+| R-001 | [description] | Technical/Business/Resource/External | H/M/L | H/M/L | [H*I] | [name] | [mitigation plan] | Open/Mitigated/Closed |
+
+## Risk Scoring
+
+- **High (H):** 3 points
+- **Medium (M):** 2 points
+- **Low (L):** 1 point
+- **Score:** Likelihood x Impact (1-9 scale)
+- **Critical:** Score >= 6
+- **Significant:** Score 4-5
+- **Manageable:** Score <= 3
+
+## Risk Categories
+
+- **Technical:** Architecture, performance, security, integration
+- **Business:** Scope change, stakeholder alignment, market shifts
+- **Resource:** Team availability, skill gaps, dependencies
+- **External:** Vendor dependencies, regulatory, third-party APIs
+
+## Escalation Thresholds
+
+- **Score >= 6:** Escalate to project sponsor immediately
+- **Score 4-5:** Review in weekly status meeting
+- **Score <= 3:** Monitor, review monthly
+
+## Closed Risks
+
+| ID | Risk | Resolution | Closed Date |
+|----|------|-----------|-------------|
+| [id] | [description] | [how it was resolved] | [date] |
+```

package/templates/communication/sprint-demo-checklist.md

@@ -0,0 +1,64 @@
+# Communication Template: Sprint Demo Checklist
+
+## Pre-Demo Preparation (day before)
+
+### Environment
+- [ ] Demo environment stable and accessible
+- [ ] Test data seeded and representative
+- [ ] All features deployed and verified
+- [ ] No pending database migrations
+- [ ] Environment matches production closely enough for credibility
+
+### Content
+- [ ] Feature list for demo confirmed with product owner
+- [ ] Demo script written with exact steps
+- [ ] Backup plan for each feature (what if it fails?)
+- [ ] Screenshots captured in case of live demo failure
+- [ ] No debug logging or test data visible
+
+### Logistics
+- [ ] Meeting invite sent with agenda
+- [ ] Screen sharing tested
+- [ ] Recording set up (if applicable)
+- [ ] Time allocated: 5 min per feature + 10 min Q&A
+
+## Demo Script Structure
+
+```markdown
+### 1. Opening (2 minutes)
+- Sprint goal reminder
+- What was committed vs delivered
+
+### 2. Feature Walkthrough (5 min per feature)
+For each feature:
+- **Context:** Why this matters (business value, not technical detail)
+- **Demo:** Show the working feature (happy path)
+- **Edge case:** Show one error case handled gracefully
+- **Questions:** Pause for stakeholder input
+
+### 3. Technical Highlights (3 minutes)
+- Architecture decisions made this sprint
+- Technical debt addressed
+- Performance improvements (with metrics if available)
+
+### 4. Blockers & Risks (2 minutes)
+- Any unresolved blockers
+- Risks to upcoming work
+- Decisions needed from stakeholders
+
+### 5. Next Sprint Preview (3 minutes)
+- Planned work for next sprint
+- Dependencies or input needed from client
+
+### 6. Q&A (10 minutes)
+- Open floor for questions
+- Capture action items
+```
+
+## Post-Demo Follow-up
+
+- [ ] Send demo recording (if recorded)
+- [ ] Send summary email with key decisions and action items
+- [ ] Update task tracker with any scope changes discussed
+- [ ] Log new requirements or feedback captured during Q&A
+- [ ] Schedule follow-up meetings for decisions needed

package/templates/communication/stakeholder-presentation-outline.md

@@ -0,0 +1,84 @@
+# Communication Template: Stakeholder Presentation Outline
+
+```markdown
+# [Project Name] — Progress Update
+
+**Date:** [date]
+**Presented by:** [name]
+**Audience:** [stakeholder names/roles]
+
+---
+
+## Executive Summary (1 slide / 3 sentences max)
+
+[What was delivered, what's the current status, what decisions are needed]
+
+---
+
+## Progress Update
+
+### Delivered This Period
+| Deliverable | Business Impact | Status |
+|-------------|----------------|--------|
+| [feature/milestone] | [how it helps the business] | Complete |
+
+### In Progress
+| Item | Progress | ETA | Risk Level |
+|------|----------|-----|-----------|
+| [item] | [%] or On Track/At Risk | [date] | Green/Amber/Red |
+
+### Planned Next
+| Item | Priority | Dependencies |
+|------|----------|-------------|
+| [item] | Must/Should/Could | [what's needed] |
+
+---
+
+## Key Decisions Needed
+
+| # | Decision | Options | Recommendation | Impact of Delay |
+|---|----------|---------|---------------|----------------|
+| 1 | [what needs deciding] | A: [option] / B: [option] | [recommendation with rationale] | [what happens if we don't decide now] |
+
+*Frame decisions as options with clear recommendations. Make it easy for stakeholders to say yes.*
+
+---
+
+## Risks & Mitigations
+
+| Risk | Status | Mitigation | Owner |
+|------|--------|------------|-------|
+| [risk] | New/Active/Mitigated | [action] | [name] |
+
+---
+
+## Budget & Timeline
+
+| Metric | Planned | Actual | Variance |
+|--------|---------|--------|----------|
+| Timeline | [end date] | [projected] | [+/- weeks] |
+| Budget (effort) | [days] | [actual] | [+/- days] |
+
+---
+
+## Next Steps
+
+| Action | Owner | Due Date |
+|--------|-------|----------|
+| [action from this meeting] | [name] | [date] |
+
+---
+
+## Appendix (if needed)
+- Technical architecture diagram
+- Detailed metrics
+- Demo environment access
+```
+
+## Presentation Tips
+
+- **Lead with outcomes, not activities** — "Users can now X" not "We built Y"
+- **3 sentences per slide max** — stakeholders read ahead, not listen
+- **Red/Amber/Green status** — universally understood, no explanation needed
+- **One decision per slide** — don't bundle decisions, they get lost
+- **End with clear next steps** — every meeting should produce actions

package/templates/communication/technical-proposal.md

@@ -0,0 +1,77 @@
+# Communication Template: Technical Proposal
+
+```markdown
+# Technical Proposal: [Project/Feature Name]
+
+**Prepared for:** [Client Name]
+**Prepared by:** [Company/Team]
+**Date:** [date]
+**Version:** [1.0]
+
+---
+
+## Executive Summary
+
+[2-3 paragraphs summarising the proposed solution, key benefits, and expected outcomes. Write for a non-technical senior stakeholder.]
+
+## Problem Statement
+
+[What problem are we solving? What is the business impact of not solving it?]
+
+## Proposed Solution
+
+### Overview
+[High-level solution description]
+
+### Architecture
+[Architecture diagram or description — keep it accessible to non-technical readers]
+
+### Key Features
+1. [Feature] — [business benefit]
+2. [Feature] — [business benefit]
+3. [Feature] — [business benefit]
+
+## Approach
+
+### Phase 1: [Name] ([duration])
+- [Deliverable]
+- [Deliverable]
+
+### Phase 2: [Name] ([duration])
+- [Deliverable]
+- [Deliverable]
+
+## Timeline
+
+| Phase | Duration | Start | End |
+|-------|----------|-------|-----|
+| Discovery | [weeks] | [date] | [date] |
+| Design | [weeks] | [date] | [date] |
+| Implementation | [weeks] | [date] | [date] |
+| QA & Testing | [weeks] | [date] | [date] |
+| Deployment | [weeks] | [date] | [date] |
+
+## Effort Estimate
+
+| Role | Effort | Rate | Cost |
+|------|--------|------|------|
+| [role] | [days/weeks] | [rate] | [cost] |
+
+**Total estimated effort:** [total]
+
+## Assumptions
+
+1. [Assumption]
+2. [Assumption]
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [risk] | H/M/L | H/M/L | [mitigation] |
+
+## Next Steps
+
+1. [Action] — [owner] — [date]
+2. [Action] — [owner] — [date]
+```

package/templates/delivery/deployment/deployment-checklist.md

@@ -0,0 +1,49 @@
+# Delivery Template: Deployment Checklist
+
+## Pre-Deployment
+
+- [ ] All tests passing in CI
+- [ ] Code review approved
+- [ ] QA check completed (`/agentops:qa-check`)
+- [ ] Environment variables configured in target environment
+- [ ] Database migrations tested in staging
+- [ ] Feature flags configured for gradual rollout
+- [ ] Rollback plan documented and tested
+- [ ] Monitoring/alerting configured
+- [ ] Stakeholders notified of deployment window
+
+## Deployment
+
+- [ ] Create deployment tag/release
+- [ ] Run database migrations
+- [ ] Deploy application
+- [ ] Verify health check endpoints respond
+- [ ] Run smoke tests against deployed environment
+- [ ] Verify key user flows work end-to-end
+- [ ] Check error rates in monitoring
+- [ ] Check response times in monitoring
+
+## Post-Deployment
+
+- [ ] Monitor error rates for 30 minutes
+- [ ] Verify no performance degradation
+- [ ] Update status page / notify stakeholders
+- [ ] Close related tickets/issues
+- [ ] Update documentation if needed
+- [ ] Schedule post-deployment review if significant changes
+
+## Rollback Procedure
+
+1. Identify the issue triggering rollback
+2. Revert to previous deployment tag
+3. Run rollback database migrations (if applicable)
+4. Verify health checks pass
+5. Notify stakeholders of rollback
+6. Document what went wrong for post-mortem
+
+## Zero-Downtime Deployment Patterns
+
+- **Blue/Green:** Maintain two identical environments, switch traffic
+- **Canary:** Route small percentage of traffic to new version, gradually increase
+- **Rolling:** Update instances one at a time behind load balancer
+- **Feature flags:** Deploy code but gate features behind flags

package/templates/delivery/design/solution-design-checklist.md

@@ -0,0 +1,37 @@
+# Design Template: Solution Design Checklist
+
+## Architecture
+- [ ] High-level architecture defined
+- [ ] Component boundaries clear
+- [ ] Technology choices justified
+- [ ] Integration points mapped
+- [ ] Data flow documented
+
+## Security
+- [ ] Authentication approach defined
+- [ ] Authorization model designed
+- [ ] Data protection strategy documented
+- [ ] Compliance requirements addressed
+
+## Data
+- [ ] Data model designed
+- [ ] Migration strategy defined (if applicable)
+- [ ] Backup/recovery plan
+- [ ] Data retention policy
+
+## Infrastructure
+- [ ] Hosting environment selected
+- [ ] Scaling strategy defined
+- [ ] Monitoring approach defined
+- [ ] CI/CD pipeline designed
+
+## Risk
+- [ ] Technical risks identified and mitigated
+- [ ] Business risks flagged to stakeholders
+- [ ] Fallback/rollback plans defined
+
+## Validation
+- [ ] Design reviewed by senior engineer
+- [ ] Design approved by stakeholder
+- [ ] Effort estimate produced
+- [ ] Timeline agreed

package/templates/delivery/discovery/stakeholder-questions.md

@@ -0,0 +1,33 @@
+# Discovery Template: Stakeholder Questions
+
+## Business Context
+1. What problem are we solving?
+2. Who experiences this problem? How often?
+3. What is the business impact of not solving it?
+4. What does success look like? How will we measure it?
+5. What is the budget and timeline?
+
+## Users & Stakeholders
+1. Who are the primary users? Secondary users?
+2. What are their technical capabilities?
+3. How many concurrent users expected?
+4. Who is the project sponsor?
+5. Who approves deliverables?
+
+## Existing Systems
+1. What systems exist today that are relevant?
+2. What integrations are required?
+3. What data needs to migrate?
+4. What are the current pain points?
+
+## Constraints
+1. Regulatory/compliance requirements?
+2. Technology constraints (approved vendors, existing infrastructure)?
+3. Team/skill constraints?
+4. Timeline hard deadlines?
+
+## Scope
+1. What is IN scope?
+2. What is OUT of scope?
+3. What is deferred to future phases?
+4. What are the acceptance criteria?

package/templates/delivery/handover/knowledge-transfer-checklist.md

@@ -0,0 +1,75 @@
+# Delivery Template: Knowledge Transfer Checklist
+
+```markdown
+# Knowledge Transfer Checklist — [Project Name]
+
+**From:** [delivering team]
+**To:** [receiving team/client]
+**Date:** [date]
+
+## Sessions
+
+### Session 1: Architecture Overview (1-2 hours)
+- [ ] High-level architecture walkthrough
+- [ ] Key architectural decisions explained (link to ADRs)
+- [ ] Module/service boundaries and responsibilities
+- [ ] Data flow diagrams reviewed
+- [ ] Integration points with external systems
+- [ ] Security architecture (auth, RBAC, tenant isolation)
+- [ ] Q&A
+
+### Session 2: Codebase Walkthrough (2-3 hours)
+- [ ] Repository structure and navigation
+- [ ] Key files and their purposes
+- [ ] Coding conventions and patterns
+- [ ] Build process and tooling
+- [ ] Testing approach and running tests
+- [ ] Common development tasks (add endpoint, add model, etc.)
+- [ ] Q&A
+
+### Session 3: Operations & Deployment (1-2 hours)
+- [ ] Deployment pipeline walkthrough
+- [ ] Environment configuration
+- [ ] Monitoring dashboards and alerting
+- [ ] Log access and common queries
+- [ ] Runbook walkthrough (startup, shutdown, troubleshooting)
+- [ ] Backup and recovery procedures
+- [ ] Q&A
+
+### Session 4: Incident Response (30-60 minutes)
+- [ ] Incident severity definitions
+- [ ] Escalation procedures
+- [ ] Common failure modes and their fixes
+- [ ] Rollback procedures
+- [ ] Communication templates for incidents
+- [ ] Q&A
+
+## Documentation Delivered
+- [ ] Architecture overview document
+- [ ] Operational runbook
+- [ ] API documentation
+- [ ] Environment setup guide
+- [ ] ADR archive
+- [ ] Test plan and current coverage report
+
+## Access Transferred
+- [ ] Source code repository (read + write)
+- [ ] CI/CD pipeline (admin access)
+- [ ] Cloud infrastructure console
+- [ ] Monitoring and alerting dashboards
+- [ ] Log aggregation platform
+- [ ] Secret management system
+- [ ] Domain registrar / DNS management
+- [ ] Third-party service accounts (auth, email, storage)
+
+## Knowledge Gaps Identified
+| Gap | Impact | Remediation |
+|-----|--------|-------------|
+| [gap] | [impact] | [plan to address] |
+
+## Sign-off
+| Role | Name | Confirmed | Date |
+|------|------|-----------|------|
+| Delivering lead | [name] | [ ] | [date] |
+| Receiving lead | [name] | [ ] | [date] |
+```

package/templates/delivery/handover/operational-runbook.md

@@ -0,0 +1,117 @@
+# Delivery Template: Operational Runbook
+
+```markdown
+# Operational Runbook — [Project Name]
+
+**Last Updated:** [date]
+**Owner:** [team/person]
+**Version:** [1.0]
+
+## 1. System Overview
+
+**Architecture:** [brief description — e.g., Next.js frontend, Express API, PostgreSQL, Redis, deployed on AWS ECS]
+
+| Component | Technology | URL/Endpoint | Health Check |
+|-----------|-----------|-------------|-------------|
+| Frontend | [tech] | [URL] | [health URL] |
+| API | [tech] | [URL] | [health URL] |
+| Database | [tech] | [connection string ref] | [query] |
+| Cache | [tech] | [connection string ref] | PING |
+
+## 2. Startup / Shutdown
+
+### Start Services
+```bash
+# Start database
+docker compose up -d postgres redis
+
+# Run migrations
+npx prisma migrate deploy
+
+# Start application
+pnpm start
+```
+
+### Stop Services
+```bash
+# Graceful shutdown (drains connections)
+kill -SIGTERM <pid>
+
+# Or via Docker
+docker compose down
+```
+
+### Restart Procedure
+1. Notify stakeholders of planned restart
+2. Stop accepting new connections (remove from load balancer)
+3. Wait for in-flight requests to complete (30s grace period)
+4. Stop services
+5. Start services
+6. Verify health checks pass
+7. Add back to load balancer
+
+## 3. Monitoring & Alerting
+
+| Metric | Warning Threshold | Critical Threshold | Dashboard |
+|--------|------------------|-------------------|-----------|
+| API response time (p95) | >500ms | >2000ms | [link] |
+| Error rate | >1% | >5% | [link] |
+| CPU utilisation | >70% | >90% | [link] |
+| Memory usage | >75% | >90% | [link] |
+| Database connections | >80% pool | >95% pool | [link] |
+| Disk usage | >80% | >90% | [link] |
+
+## 4. Common Troubleshooting
+
+### API returning 500 errors
+1. Check application logs: `docker logs <container> --tail 100`
+2. Check database connectivity: `SELECT 1` via psql
+3. Check Redis connectivity: `redis-cli PING`
+4. Check recent deployments: `git log --oneline -5`
+5. If caused by recent deployment: rollback
+
+### Database connection pool exhausted
+1. Check current connections: `SELECT count(*) FROM pg_stat_activity`
+2. Kill idle connections if needed
+3. Review connection pool settings
+4. Check for connection leaks (unclosed transactions)
+
+### High memory usage
+1. Check for memory leaks: monitor heap growth over time
+2. Review recent code changes for unbounded caches or collections
+3. Restart service if immediate relief needed
+4. Profile with Node.js inspector if recurring
+
+## 5. Backup & Recovery
+
+| Data | Frequency | Retention | Location | Recovery Time |
+|------|-----------|-----------|----------|--------------|
+| Database | Daily + WAL | 30 days | [S3 bucket] | <1 hour |
+| File uploads | Real-time (S3) | Indefinite | [S3 bucket] | <30 min |
+| Application config | Git | Indefinite | Repository | <5 min |
+
+### Recovery Procedure
+1. Identify point-in-time for recovery
+2. Restore database from backup
+3. Verify data integrity
+4. Replay WAL logs if needed for point-in-time recovery
+5. Verify application functions correctly
+6. Notify stakeholders
+
+## 6. Scaling
+
+| Trigger | Action | Limit |
+|---------|--------|-------|
+| CPU >70% sustained 5min | Add API instance | Max 10 instances |
+| Memory >80% | Add API instance | Max 10 instances |
+| Database connections >80% | Increase pool size | Max 100 |
+| Response time p95 >1s | Add API instance + review queries | — |
+
+## 7. Contacts
+
+| Role | Name | Contact | Escalation |
+|------|------|---------|------------|
+| On-call engineer | [name] | [phone/slack] | Level 1 |
+| Tech lead | [name] | [phone/slack] | Level 2 |
+| Infrastructure | [name] | [phone/slack] | Level 3 |
+```