@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/templates/handoff-protocol.md

@@ -0,0 +1,294 @@
+# Handoff Protocol Template
+
+**Phase:** 39
+**Plan:** 39-05
+**Requirement:** POOL-05, ORCH-07
+
+This template defines the standardized handoff protocol for transferring skills and context between agents.
+
+---
+
+## Skill Handoff Record Format
+
+```markdown
+## Skill Handoff Record
+
+**From Agent:** {agent-name}
+**To Agent:** {next-agent-name}
+**Phase:** {phase-number}
+**Task:** {task-id}
+**Timestamp:** {ISO timestamp}
+
+### Context Transferred
+- **Project State:** {STATE.md snapshot reference}
+- **Decisions Made:** {DECISIONS.md entries}
+- **Skills Active:** [list of skill IDs]
+- **Artifacts Produced:** [file paths]
+
+### Continuity Requirements
+- **Must Maintain:** {specific patterns/approaches}
+- **Must Not Change:** {locked decisions}
+- **Must Validate:** {specific checks}
+
+### Handoff Checkpoint
+**Type:** {checkpoint-type: sequential|parallel|interrupted}
+**Status:** {ready-for-handoff|pending|blocked}
+**Verification:** {self-check results}
+
+### Skill Transfer
+- **Inherited Skills:** [skills from previous agent]
+- **Recommended Skills:** [skills for next agent]
+- **Consistent Skills:** [skills used consistently in project]
+```
+
+---
+
+## Handoff Types
+
+### Sequential Handoff
+
+Standard flow: Architect → Backend → Frontend → QA → DevOps
+
+**Characteristics:**
+- Clear handoff boundaries
+- Complete context transfer
+- Validation before handoff
+
+**Example:**
+```markdown
+## Handoff: Architect Agent → Backend Agent
+
+**Phase:** 39
+**Task:** User Authentication Feature
+**Type:** sequential
+
+### From Architect Agent
+**Decisions:**
+1. JWT-based authentication
+2. PostgreSQL for user data
+3. Redis for token blacklist
+
+**Skills Applied:**
+- modular_monolith_pattern_skill_v1
+- authentication_jwt_skill_v1
+- postgresql_schema_design_skill_v1
+
+**Artifacts:**
+- ARCHITECTURE.md
+- API-CONTRACTS.md
+- DB-SCHEMA.md
+
+### To Backend Agent
+**Must Implement:**
+- JWT auth endpoints (login, register, refresh, logout)
+- Password hashing with bcrypt
+- Token blacklist in Redis
+
+**Skills Activated:**
+- laravel_11_structure_skill_v2 (stack)
+- api_design_rest_skill_v1 (architecture)
+- authentication_jwt_skill_v1 (domain — inherited)
+- redis_caching_pattern_skill_v1 (infrastructure)
+- testing_unit_phpunit_skill_v1 (operational)
+
+**Continuity Requirements:**
+- Must follow JWT approach from Architect decision
+- Must use modular structure
+- Must implement token blacklist
+```
+
+### Parallel Handoff
+
+Backend + Frontend work on same feature with shared context
+
+**Characteristics:**
+- Shared context between agents
+- Coordinated implementation
+- Regular sync points
+
+**Example:**
+```markdown
+## Handoff: Architect Agent → Backend + Frontend Agents (Parallel)
+
+**Phase:** 39
+**Task:** Dashboard Feature
+**Type:** parallel
+
+### Shared Context
+**Architecture:**
+- Client-server architecture
+- WebSocket for real-time updates
+- Zustand for state management
+
+**API Contracts:**
+- GET /api/dashboard/metrics
+- GET /api/dashboard/charts
+- WebSocket: dashboard-updates
+
+### Backend Agent Responsibilities
+- Implement API endpoints
+- Set up WebSocket server
+- Data aggregation logic
+
+### Frontend Agent Responsibilities
+- Build dashboard components
+- Set up Zustand store
+- WebSocket client integration
+
+### Coordination Points
+- API contract alignment
+- Data model consistency
+- Error handling patterns
+```
+
+### Interrupted Handoff
+
+Agent A stops at checkpoint, Agent B continues (recovery)
+
+**Characteristics:**
+- Recovery from interruption
+- Complete state capture
+- Clear resumption point
+
+**Example:**
+```markdown
+## Handoff: Backend Agent → Frontend Agent (Interrupted)
+
+**Phase:** 39
+**Task:** User Profile Feature
+**Type:** interrupted
+
+### Interruption Point
+**Stopped At:** API implementation complete, tests pending
+**Reason:** Blocker - external API dependency
+
+### State Captured
+**Completed:**
+- User model created
+- API endpoints implemented
+- Database migrations run
+
+**Pending:**
+- Unit tests (blocked by external API)
+- Integration tests
+
+### Resumption
+**Frontend Agent Can:**
+- Start UI implementation with mock data
+- Use API contracts for integration
+- Implement error states
+
+**Continuity:**
+- Must use implemented API endpoints
+- Must handle loading/error states
+- Must match data models
+```
+
+---
+
+## Continuity Requirements Format
+
+```markdown
+### Continuity Requirements
+
+**Must Maintain:**
+- [Pattern/approach that must continue]
+- [Example: JWT authentication approach]
+
+**Must Not Change:**
+- [Locked decision that cannot be changed]
+- [Example: PostgreSQL as database]
+
+**Must Validate:**
+- [Specific checks receiving agent must perform]
+- [Example: API contract compliance]
+```
+
+---
+
+## Skill Memory Format
+
+Skill memory tracks skills used across the project for consistency:
+
+```javascript
+{
+  "projectId": "project-xyz",
+  "skills": [
+    {
+      "phase": "39",
+      "task": "user-auth",
+      "skills": [
+        {"id": "laravel_11_structure_skill_v2", "category": "Stack"},
+        {"id": "authentication_jwt_skill_v1", "category": "Domain"}
+      ],
+      "timestamp": "2026-03-21T10:00:00Z",
+      "agent": "ez-backend-agent"
+    }
+  ],
+  "lastUpdated": "2026-03-21T10:00:00Z"
+}
+```
+
+---
+
+## Handoff Validation
+
+Before handoff, validate:
+
+```javascript
+const validation = validateHandoff(handoff);
+
+if (!validation.valid) {
+  // Block handoff
+  console.error('Handoff blocked:', validation.violations);
+  return;
+}
+
+if (validation.warnings.length > 0) {
+  // Log warnings
+  console.warn('Handoff warnings:', validation.warnings);
+}
+
+// Proceed with handoff
+```
+
+**Validation Checks:**
+- [ ] fromAgent specified
+- [ ] toAgent specified
+- [ ] Skills active transferred
+- [ ] Artifacts listed
+- [ ] Continuity requirements specified
+- [ ] Checkpoint status is READY
+
+---
+
+## Integration with Context Manager
+
+The Context Manager agent manages handoffs:
+
+1. **Creates handoff records** using `createHandoff()`
+2. **Tracks skill memory** using `recordSkillUsage()`
+3. **Ensures continuity** by validating requirements
+4. **Updates STATE.md** with handoff status
+
+---
+
+## Handoff Checklist
+
+Before initiating handoff:
+
+- [ ] All artifacts produced and committed
+- [ ] Decision log complete
+- [ ] Skills documented (3-7 activated)
+- [ ] Verification status complete
+- [ ] Continuity requirements defined
+- [ ] Handoff record created
+- [ ] Validation passed
+
+After handoff complete:
+
+- [ ] Receiving agent acknowledges receipt
+- [ ] Skills transferred successfully
+- [ ] Context understood
+- [ ] Continuity requirements accepted
+- [ ] Task execution begins

package/ez-agents/templates/incident-runbook.md

@@ -0,0 +1,205 @@
+# Incident Runbook: {service-name}
+
+**Version:** v{version} ({tier} tier)
+**Last updated:** {date}
+**Owner:** {team or individual}
+
+---
+
+## Severity Levels
+
+| Level | Description | Response Time | Example |
+|-------|-------------|---------------|---------|
+| P0 — Critical | Complete outage, data loss | Immediate | App unreachable, DB corruption |
+| P1 — High | Major feature broken, many users affected | 15 minutes | Login broken, payments failing |
+| P2 — Medium | Feature degraded, workaround exists | 1 hour | Slow responses, non-critical feature down |
+| P3 — Low | Minor issue, cosmetic | Next business day | UI glitch, non-critical error |
+
+---
+
+## On-Call Contacts
+
+| Role | Contact | When to Call |
+|------|---------|--------------|
+| Primary on-call | {name/handle} | P0 and P1 |
+| Secondary | {name/handle} | Primary unreachable |
+| Database | {name/handle} | DB issues |
+| Platform/Infra | {name/handle} | Infrastructure issues |
+
+---
+
+## Quick Diagnostics
+
+### 1. Is the app running?
+
+```bash
+curl -f https://{your-domain}/health && echo "UP" || echo "DOWN"
+```
+
+### 2. Check recent deployments
+
+```bash
+git log --oneline -5  # Recent commits
+# Or check your deployment platform dashboard
+```
+
+### 3. Check error logs
+
+```bash
+# Vercel: vercel logs
+# Railway: railway logs
+# Generic: tail -100 /var/log/app.log
+# Or: check error tracking dashboard (Sentry, etc.)
+```
+
+### 4. Check database connectivity
+
+```bash
+# Test DB connection
+node -e "
+  const { PrismaClient } = require('@prisma/client');
+  const prisma = new PrismaClient();
+  prisma.\$connect().then(() => { console.log('DB OK'); process.exit(0); })
+    .catch(e => { console.error('DB FAIL:', e.message); process.exit(1); });
+"
+```
+
+---
+
+## Common Incidents and Resolutions
+
+### App is down (P0)
+
+1. Check if recent deployment caused it: `git log --oneline -3`
+2. If yes → roll back immediately (see Rollback Procedure)
+3. If no → check infrastructure status (hosting provider status page)
+4. Check logs for error pattern
+5. If DB issue → see DB incident section
+
+### Login/Auth broken (P1)
+
+1. Check auth service logs
+2. Verify environment variables: `NEXTAUTH_SECRET`, `NEXTAUTH_URL`, OAuth credentials
+3. Check if auth provider (Google, GitHub, etc.) is having issues
+4. Test with curl: `curl -X POST /api/auth/signin`
+5. If JWT secret rotated → issue new tokens (force re-login acceptable)
+
+### Payments failing (P1)
+
+1. Check payment provider dashboard (Stripe, etc.) for service issues
+2. Check webhook delivery in provider dashboard
+3. Verify API keys are valid: check for expiry or rotation
+4. Check logs for specific Stripe error codes
+5. **Do NOT retry failed charges** until root cause identified
+
+### Database full / slow (P1)
+
+1. Check disk usage and connection count
+2. Identify slow queries: check database logs or monitoring
+3. Kill long-running queries if blocking
+4. Check for lock contention
+5. Consider read replica if load issue
+
+### High error rate (P2)
+
+1. Check error tracking for error pattern
+2. Identify affected endpoints from logs
+3. Check if recent deployment correlates
+4. Roll back if correlation found
+5. Otherwise: hotfix with `/ez:hotfix start {description}`
+
+---
+
+## Rollback Procedure
+
+```bash
+# 1. Decision: roll back if P0/P1 persists > {rollback_window}
+
+# 2. Roll back application
+vercel rollback  # Vercel
+# OR: git revert HEAD && git push  # generic
+
+# 3. Verify health
+curl -f https://{your-domain}/health
+
+# 4. Notify stakeholders
+# See communication templates below
+
+# 5. Document in post-mortem
+```
+
+Full rollback plan: `.planning/releases/v{version}-ROLLBACK-PLAN.md`
+
+---
+
+## Communication Templates
+
+### Customer-facing (P0)
+
+```
+[{service-name} Status] Service disruption
+
+We are experiencing a service disruption affecting {impact description}.
+Our team is actively working to restore service.
+
+Current status: Investigating
+ETA: Unknown (update in 30 minutes)
+
+We apologize for the inconvenience.
+```
+
+### Customer-facing (Resolved)
+
+```
+[{service-name} Status] Service restored
+
+The service disruption has been resolved at {time}.
+All systems are operating normally.
+
+Duration: {duration}
+Impact: {description}
+
+We apologize for the disruption. A full post-mortem will be published at {link}.
+```
+
+---
+
+## Post-Incident Process
+
+1. **Immediate** (within 1 hour): Write incident timeline in `.planning/incidents/{date}-{title}.md`
+2. **Short-term** (within 24 hours): Root cause analysis complete
+3. **Follow-up** (within 1 week): Prevention measures implemented
+
+### Post-Mortem Template
+
+```markdown
+# Incident Post-Mortem: {title}
+
+**Date:** {date}
+**Duration:** {start} – {end} ({total duration})
+**Severity:** P{level}
+**Impact:** {affected users/features}
+
+## Timeline
+- HH:MM — {event}
+- HH:MM — {event}
+
+## Root Cause
+{Single sentence root cause}
+
+## Contributing Factors
+{What made this possible}
+
+## What Went Well
+{Detection speed, response time, etc.}
+
+## Action Items
+| Action | Owner | Due |
+|--------|-------|-----|
+| {item} | {person} | {date} |
+```
+
+---
+
+*Generated by EZ Agents release-agent*
+*Tier: {tier} | Version: v{version}*