@howlil/ez-agents 3.4.2 → 3.5.0

package/ez-agents/templates/discussion.md

@@ -0,0 +1,68 @@
+---
+phase: {phase-number}-{phase-slug}
+status: open
+participants: [ez-requirements-agent, ez-tech-lead-agent, ez-observer-agent, ez-scrum-master-agent]
+opened: {timestamp}
+consensus: pending
+---
+
+# Phase {X}: {Name} — Pre-Execution Discussion
+
+**Purpose:** Parallel agent perspectives before phase execution. Orchestrator reads consensus before spawning executors.
+
+---
+
+## Requirements Perspective (ez-requirements-agent)
+
+> *Populated by ez-requirements-agent during phase kickoff*
+
+{Populated during gather-requirements or plan-phase kickoff}
+
+---
+
+## Tech Lead Perspective (ez-tech-lead-agent)
+
+> *Populated by ez-tech-lead-agent during plan-phase review*
+
+{Populated during arch-review after plan creation}
+
+---
+
+## Observer Perspective (ez-observer-agent)
+
+> *Populated by ez-observer-agent during execute-phase pre-flight*
+
+{Populated during execute-phase pre-flight}
+
+---
+
+## Scrum Master Perspective (ez-scrum-master-agent)
+
+> *Populated by ez-scrum-master-agent during phase kickoff*
+
+{Populated during standup or phase kickoff}
+
+---
+
+## Consensus
+
+> *Synthesized by orchestrator from above perspectives*
+
+**Status:** {open | consensus-reached | needs-human}
+
+### Blockers
+{List any hard blockers from any agent, or "None"}
+
+### Key Warnings
+{List significant warnings, or "None"}
+
+### Go / No-Go
+{GO — proceed to execution | NO-GO — resolve blockers first | HUMAN-NEEDED — requires user input}
+
+### Rationale
+{1-2 sentences explaining the consensus decision}
+
+---
+
+*Discussion opened: {timestamp}*
+*Last updated: {timestamp}*

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}*

package/ez-agents/templates/release-checklist.md

@@ -0,0 +1,133 @@
+# Release Checklist Template
+
+Tier-parameterized checklist for `/ez:release`. Items marked `[AUTO]` can be checked programmatically. Items marked `[HUMAN]` require manual verification.
+
+---
+
+## MVP Checklist (6 items)
+
+Use when: First public release, early access, startup MVP
+
+```
+Release: v{version} — MVP Tier
+Date: {date}
+```
+
+| # | Item | Type | Result |
+|---|------|------|--------|
+| 1 | All @must BDD scenarios passing | AUTO | |
+| 2 | `npm audit` — no critical vulnerabilities | AUTO | |
+| 3 | Health endpoint returns 200 (if applicable) | AUTO | |
+| 4 | No secrets in committed files | AUTO | |
+| 5 | Application starts without errors (`npm start` or equivalent) | AUTO | |
+| 6 | Rollback procedure documented | AUTO | |
+
+**Gate:** All 6 items must pass for MVP release.
+
+---
+
+## Medium Checklist (18 items)
+
+Use when: General availability, paying customers, production SLA
+
+```
+Release: v{version} — Medium Tier
+Date: {date}
+```
+
+*Includes all MVP items plus:*
+
+| # | Item | Type | Result |
+|---|------|------|--------|
+| 1-6 | All MVP items | AUTO | |
+| 7 | All @should BDD scenarios passing | AUTO | |
+| 8 | Test coverage ≥ 80% | AUTO | |
+| 9 | Staging environment parity verified | HUMAN | |
+| 10 | Monitoring/alerts configured (uptime, error rate) | HUMAN | |
+| 11 | Structured logging in place (no console.log in prod) | AUTO | |
+| 12 | Performance baseline documented | HUMAN | |
+| 13 | Error tracking configured (Sentry, Rollbar, or equivalent) | HUMAN | |
+| 14 | Database migrations tested on staging copy | HUMAN | |
+| 15 | API documentation current (README or OpenAPI) | HUMAN | |
+| 16 | Environment variables documented (.env.example up to date) | AUTO | |
+| 17 | Graceful shutdown handled (SIGTERM, connection draining) | AUTO | |
+| 18 | Rate limiting on public API endpoints | AUTO | |
+
+**Gate:** Items 1-12 must pass. Items 13-18 advisory for Medium.
+
+---
+
+## Enterprise Checklist (30 items)
+
+Use when: Enterprise customers, regulated industries, compliance requirements
+
+```
+Release: v{version} — Enterprise Tier
+Date: {date}
+```
+
+*Includes all Medium items plus:*
+
+| # | Item | Type | Result |
+|---|------|------|--------|
+| 1-18 | All Medium items | MIXED | |
+| 19 | All @could BDD scenarios passing | AUTO | |
+| 20 | Test coverage ≥ 95% | AUTO | |
+| 21 | Security audit completed (internal or third-party) | HUMAN | |
+| 22 | Compliance documentation updated (SOC2/GDPR controls) | HUMAN | |
+| 23 | Load test results documented (target: 2x expected peak) | HUMAN | |
+| 24 | Disaster recovery tested (backup restore procedure) | HUMAN | |
+| 25 | Data retention policy configured | HUMAN | |
+| 26 | Audit logging enabled (who did what, when) | AUTO | |
+| 27 | Penetration test completed or scheduled | HUMAN | |
+| 28 | SOC2/GDPR controls validated | HUMAN | |
+| 29 | Change management ticket filed | HUMAN | |
+| 30 | Incident runbook up to date | HUMAN | |
+
+**Gate:** All items 1-26 must pass. Items 27-30 must be scheduled/documented.
+
+---
+
+## Security Gates (All Tiers)
+
+These run before ANY release regardless of tier:
+
+```bash
+# Gate 1: No secrets
+git grep -i -E "(api[_-]?key|password|secret)['\"]?\s*[=:]\s*['\"]?[a-zA-Z0-9+/]{20,}" HEAD
+
+# Gate 2: npm audit
+npm audit --audit-level=critical
+
+# Gate 3: Production TODO/FIXME
+grep -rn "TODO\|FIXME\|HACK" src/ --include="*.ts" --include="*.js" | grep -v test
+
+# Gate 4: .env protected
+grep -q "^\.env" .gitignore
+```
+
+**Any gate failure = BLOCKED regardless of tier.**
+
+---
+
+## Production Readiness Score
+
+```
+Score = 100 - (blocking_failures × 10) - (advisory_failures × 2)
+
+READY:        90-100
+CONDITIONAL:  70-89
+NOT READY:    <70
+```
+
+---
+
+## Rollback Criteria
+
+**Roll back immediately if (within 1 hour of release):**
+
+| Tier | Trigger | Response Time |
+|------|---------|---------------|
+| MVP | App won't start OR error rate >20% | 30 minutes |
+| Medium | Error rate >5% above baseline OR P95 >500ms increase | 15 minutes |
+| Enterprise | Any SLA breach OR compliance violation | 5 minutes |

package/ez-agents/templates/rollback-plan.md

@@ -0,0 +1,201 @@
+# Rollback Plan: v{version}
+
+**Released:** {date}
+**Tier:** {tier}
+**Previous version:** {previous_version}
+**Previous tag:** {previous_tag}
+**Author:** EZ Agents release-agent
+
+---
+
+## Rollback Decision Criteria
+
+Roll back **immediately** if any of the following occur within {rollback_window} of release:
+
+### MVP Tier (30-minute window)
+- [ ] Application fails to start
+- [ ] Error rate exceeds 20%
+- [ ] Health endpoint returns non-200
+- [ ] Critical functionality broken (login, core user flow)
+
+### Medium Tier (15-minute window)
+- All MVP criteria plus:
+- [ ] Error rate increases >5% above pre-release baseline
+- [ ] P95 response time increases >200ms
+- [ ] Payment/auth system errors
+
+### Enterprise Tier (5-minute window)
+- All Medium criteria plus:
+- [ ] Any SLA breach
+- [ ] Any compliance-related failure
+- [ ] Security alert triggered
+- [ ] Data integrity issue detected
+
+---
+
+## Rollback Procedure
+
+### Step 1: Decision (T+0)
+
+Whoever observes a rollback trigger calls rollback immediately.
+
+**Do NOT wait** to gather more data. Roll back, then investigate.
+
+Contact: {oncall_contact or "N/A"}
+
+### Step 2: Application Rollback (T+2 minutes)
+
+Choose rollback method based on deployment platform:
+
+**Vercel:**
+```bash
+vercel rollback
+# Or use Vercel dashboard → Deployments → select previous → Promote
+```
+
+**Netlify:**
+```bash
+# Netlify dashboard → Deploys → select previous deploy → Publish deploy
+```
+
+**Railway:**
+```bash
+# Railway dashboard → Deployments → select previous → Rollback
+```
+
+**Heroku:**
+```bash
+heroku releases
+heroku rollback v{previous_release_number}
+```
+
+**Generic (git-based deploy):**
+```bash
+git revert HEAD --no-edit
+git push origin main
+# Triggers your CI/CD to redeploy previous version
+```
+
+**Docker:**
+```bash
+docker pull {registry}/{image}:{previous_version}
+docker tag {registry}/{image}:{previous_version} {registry}/{image}:latest
+docker push {registry}/{image}:latest
+# Restart containers
+```
+
+### Step 3: Database Rollback (if applicable)
+
+{If database migrations were run:}
+
+**Check if rollback is needed:**
+Was a database migration applied as part of this release? Check migration history:
+```bash
+npx prisma migrate status 2>/dev/null
+# Or: cat .planning/releases/v{version}-migrations.md
+```
+
+**If migration must be rolled back:**
+
+```bash
+# Prisma
+npx prisma migrate resolve --rolled-back {migration_name}
+
+# Django
+python manage.py migrate {app_name} {previous_migration}
+
+# Rails
+rails db:rollback STEP=1
+
+# Flyway
+flyway undo
+```
+
+**WARNING:** Only roll back migrations if the data model change is backward-compatible OR no new data has been written. When in doubt: roll back application first, keep database as-is, hotfix forward.
+
+### Step 4: Verify Rollback (T+5 minutes)
+
+```bash
+# Check health
+curl -f https://{your-domain}/health || echo "HEALTH_CHECK_FAILED"
+
+# Check error rate
+# View in your monitoring dashboard — should return to pre-release baseline
+
+# Smoke test key flows
+# 1. Visit {your-domain}
+# 2. Log in with test account
+# 3. Perform core user action
+```
+
+Expected state after successful rollback:
+- Application responds to all requests
+- Error rate returns to pre-release baseline
+- Health endpoint returns 200
+- Core user flows work
+
+### Step 5: Post-Rollback Communication
+
+Notify relevant parties (team, users if customer-facing):
+
+```
+[Status Update]
+We rolled back v{version} due to [brief description].
+Service is restored. Root cause investigation in progress.
+ETA for fix: [estimate]
+```
+
+### Step 6: Post-Mortem
+
+After rollback is complete and service is stable:
+
+1. **Root cause analysis** — What caused the issue?
+2. **Timeline** — When detected, when rolled back, total impact duration
+3. **Fix plan** — How to fix before re-releasing
+4. **Process improvement** — What check could have caught this?
+
+Write post-mortem to: `.planning/releases/v{version}-POSTMORTEM.md`
+
+Update CHANGELOG.md:
+```markdown
+## [v{version}] — ROLLED BACK
+Released {date}, rolled back {rollback_date}.
+Reason: {brief reason}
+Fix scheduled for v{next_version}
+```
+
+---
+
+## Forward Fix Procedure
+
+After rolling back, create a hotfix:
+
+```bash
+/ez:hotfix start {fix-description}
+# Make the fix
+/ez:hotfix complete {fix-description} {new_version}
+```
+
+Or plan a new phase if the fix is larger:
+
+```bash
+/ez:plan-phase {next_phase} --gaps
+```
+
+---
+
+## Emergency Contacts
+
+{Fill in before going to production:}
+
+| Role | Contact | When to Call |
+|------|---------|--------------|
+| On-call developer | {name/handle} | Any rollback decision |
+| Database admin | {name/handle} | If DB rollback needed |
+| Customer success | {name/handle} | If customer impact >5 min |
+
+---
+
+*Generated by EZ Agents release-agent*
+*Release: v{version} — {tier} tier*
+*Created: {timestamp}*

package/ez-agents/workflows/arch-review.md

@@ -0,0 +1,54 @@
+<purpose>
+Run a Tech Lead architecture review on phase plans. Reads phase PLAN.md files and checks for pattern drift, technical debt, security issues, and design conflicts.
+</purpose>
+
+<process>
+
+## 1. Initialize
+
+Parse $ARGUMENTS for phase number.
+
+```bash
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract: `phase_dir`, `phase_number`, `phase_name`, `planner_model`.
+
+## 2. Validate
+
+Check phase directory and plans exist. If no PLAN.md found: error "No plans found for phase {N}. Run /ez:plan-phase first."
+
+## 3. Spawn Tech Lead Review
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► ARCH REVIEW — Phase {N}: {Name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+```
+Task(
+  prompt="Review architecture of Phase {phase_number}: {phase_name}.
+  Read all PLAN.md files in {phase_dir}.
+  Check: pattern consistency, technical debt, security, cross-phase conflicts, dependencies.
+  Report: BLOCKERS (must fix), WARNINGS (should fix), ADVISORY (consider).
+  Output: ## Tech Lead Review: Phase {N} — {status}",
+  subagent_type="ez-tech-lead-agent",
+  model="{planner_model}"
+)
+```
+
+## 4. Present Results
+
+Display agent output directly. If BLOCKER found: highlight "Fix before /ez:execute-phase". If APPROVE: confirm safe to execute.
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated
+- [ ] Tech lead agent spawned
+- [ ] Findings presented with severity
+- [ ] Clear go/no-go for execution
+</success_criteria>