@howlil/ez-agents 3.4.1 → 3.5.0

package/ez-agents/templates/roadmap.md

@@ -1,202 +1,202 @@
-# Roadmap Template
-
-Template for `.planning/ROADMAP.md`.
-
-## Initial Roadmap (v1.0 Greenfield)
-
-```markdown
-# Roadmap: [Project Name]
-
-## Overview
-
-[One paragraph describing the journey from start to finish]
-
-## Phases
-
-**Phase Numbering:**
-- Integer phases (1, 2, 3): Planned milestone work
-- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
-
-Decimal phases appear between their surrounding integers in numeric order.
-
-- [ ] **Phase 1: [Name]** - [One-line description]
-- [ ] **Phase 2: [Name]** - [One-line description]
-- [ ] **Phase 3: [Name]** - [One-line description]
-- [ ] **Phase 4: [Name]** - [One-line description]
-
-## Phase Details
-
-### Phase 1: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Nothing (first phase)
-**Requirements**: [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
-**Success Criteria** (what must be TRUE):
-  1. [Observable behavior from user perspective]
-  2. [Observable behavior from user perspective]
-  3. [Observable behavior from user perspective]
-**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
-
-Plans:
-- [ ] 01-01: [Brief description of first plan]
-- [ ] 01-02: [Brief description of second plan]
-- [ ] 01-03: [Brief description of third plan]
-
-### Phase 2: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 1
-**Requirements**: [REQ-04, REQ-05]
-**Success Criteria** (what must be TRUE):
-  1. [Observable behavior from user perspective]
-  2. [Observable behavior from user perspective]
-**Plans**: [Number of plans]
-
-Plans:
-- [ ] 02-01: [Brief description]
-- [ ] 02-02: [Brief description]
-
-### Phase 2.1: Critical Fix (INSERTED)
-**Goal**: [Urgent work inserted between phases]
-**Depends on**: Phase 2
-**Success Criteria** (what must be TRUE):
-  1. [What the fix achieves]
-**Plans**: 1 plan
-
-Plans:
-- [ ] 02.1-01: [Description]
-
-### Phase 3: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 2
-**Requirements**: [REQ-06, REQ-07, REQ-08]
-**Success Criteria** (what must be TRUE):
-  1. [Observable behavior from user perspective]
-  2. [Observable behavior from user perspective]
-  3. [Observable behavior from user perspective]
-**Plans**: [Number of plans]
-
-Plans:
-- [ ] 03-01: [Brief description]
-- [ ] 03-02: [Brief description]
-
-### Phase 4: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 3
-**Requirements**: [REQ-09, REQ-10]
-**Success Criteria** (what must be TRUE):
-  1. [Observable behavior from user perspective]
-  2. [Observable behavior from user perspective]
-**Plans**: [Number of plans]
-
-Plans:
-- [ ] 04-01: [Brief description]
-
-## Progress
-
-**Execution Order:**
-Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
-
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 1. [Name] | 0/3 | Not started | - |
-| 2. [Name] | 0/2 | Not started | - |
-| 3. [Name] | 0/2 | Not started | - |
-| 4. [Name] | 0/1 | Not started | - |
-```
-
-<guidelines>
-**Initial planning (v1.0):**
-- Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12)
-- Each phase delivers something coherent
-- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
-- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
-- No time estimates (this isn't enterprise PM)
-- Progress table updated by execute workflow
-- Plan count can be "TBD" initially, refined during planning
-
-**Success criteria:**
-- 2-5 observable behaviors per phase (from user's perspective)
-- Cross-checked against requirements during roadmap creation
-- Flow downstream to `must_haves` in plan-phase
-- Verified by verify-phase after execution
-- Format: "User can [action]" or "[Thing] works/exists"
-
-**After milestones ship:**
-- Collapse completed milestones in `<details>` tags
-- Add new milestone sections for upcoming work
-- Keep continuous phase numbering (never restart at 01)
-</guidelines>
-
-<status_values>
-- `Not started` - Haven't begun
-- `In progress` - Currently working
-- `Complete` - Done (add completion date)
-- `Deferred` - Pushed to later (with reason)
-</status_values>
-
-## Milestone-Grouped Roadmap (After v1.0 Ships)
-
-After completing first milestone, reorganize with milestone groupings:
-
-```markdown
-# Roadmap: [Project Name]
-
-## Milestones
-
-- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
-- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
-- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
-
-## Phases
-
-<details>
-<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
-
-### Phase 1: [Name]
-**Goal**: [What this phase delivers]
-**Plans**: 3 plans
-
-Plans:
-- [x] 01-01: [Brief description]
-- [x] 01-02: [Brief description]
-- [x] 01-03: [Brief description]
-
-[... remaining v1.0 phases ...]
-
-</details>
-
-### 🚧 v1.1 [Name] (In Progress)
-
-**Milestone Goal:** [What v1.1 delivers]
-
-#### Phase 5: [Name]
-**Goal**: [What this phase delivers]
-**Depends on**: Phase 4
-**Plans**: 2 plans
-
-Plans:
-- [ ] 05-01: [Brief description]
-- [ ] 05-02: [Brief description]
-
-[... remaining v1.1 phases ...]
-
-### 📋 v2.0 [Name] (Planned)
-
-**Milestone Goal:** [What v2.0 delivers]
-
-[... v2.0 phases ...]
-
-## Progress
-
-| Phase | Milestone | Plans Complete | Status | Completed |
-|-------|-----------|----------------|--------|-----------|
-| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
-| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
-| 5. Security | v1.1 | 0/2 | Not started | - |
-```
-
-**Notes:**
-- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
-- Completed milestones collapsed in `<details>` for readability
-- Current/future milestones expanded
-- Continuous phase numbering (01-99)
-- Progress table includes milestone column
+# Roadmap Template
+
+Template for `.planning/ROADMAP.md`.
+
+## Initial Roadmap (v1.0 Greenfield)
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph describing the journey from start to finish]
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: [Name]** - [One-line description]
+- [ ] **Phase 2: [Name]** - [One-line description]
+- [ ] **Phase 3: [Name]** - [One-line description]
+- [ ] **Phase 4: [Name]** - [One-line description]
+
+## Phase Details
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Nothing (first phase)
+**Requirements**: [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
+
+Plans:
+- [ ] 01-01: [Brief description of first plan]
+- [ ] 01-02: [Brief description of second plan]
+- [ ] 01-03: [Brief description of third plan]
+
+### Phase 2: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+**Requirements**: [REQ-04, REQ-05]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+### Phase 2.1: Critical Fix (INSERTED)
+**Goal**: [Urgent work inserted between phases]
+**Depends on**: Phase 2
+**Success Criteria** (what must be TRUE):
+  1. [What the fix achieves]
+**Plans**: 1 plan
+
+Plans:
+- [ ] 02.1-01: [Description]
+
+### Phase 3: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Requirements**: [REQ-06, REQ-07, REQ-08]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+### Phase 4: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 3
+**Requirements**: [REQ-09, REQ-10]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 04-01: [Brief description]
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. [Name] | 0/3 | Not started | - |
+| 2. [Name] | 0/2 | Not started | - |
+| 3. [Name] | 0/2 | Not started | - |
+| 4. [Name] | 0/1 | Not started | - |
+```
+
+<guidelines>
+**Initial planning (v1.0):**
+- Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12)
+- Each phase delivers something coherent
+- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
+- No time estimates (this isn't enterprise PM)
+- Progress table updated by execute workflow
+- Plan count can be "TBD" initially, refined during planning
+
+**Success criteria:**
+- 2-5 observable behaviors per phase (from user's perspective)
+- Cross-checked against requirements during roadmap creation
+- Flow downstream to `must_haves` in plan-phase
+- Verified by verify-phase after execution
+- Format: "User can [action]" or "[Thing] works/exists"
+
+**After milestones ship:**
+- Collapse completed milestones in `<details>` tags
+- Add new milestone sections for upcoming work
+- Keep continuous phase numbering (never restart at 01)
+</guidelines>
+
+<status_values>
+- `Not started` - Haven't begun
+- `In progress` - Currently working
+- `Complete` - Done (add completion date)
+- `Deferred` - Pushed to later (with reason)
+</status_values>
+
+## Milestone-Grouped Roadmap (After v1.0 Ships)
+
+After completing first milestone, reorganize with milestone groupings:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
+- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: [Brief description]
+- [x] 01-02: [Brief description]
+- [x] 01-03: [Brief description]
+
+[... remaining v1.0 phases ...]
+
+</details>
+
+### 🚧 v1.1 [Name] (In Progress)
+
+**Milestone Goal:** [What v1.1 delivers]
+
+#### Phase 5: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 4
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: [Brief description]
+- [ ] 05-02: [Brief description]
+
+[... remaining v1.1 phases ...]
+
+### 📋 v2.0 [Name] (Planned)
+
+**Milestone Goal:** [What v2.0 delivers]
+
+[... v2.0 phases ...]
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | v1.1 | 0/2 | Not started | - |
+```
+
+**Notes:**
+- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
+- Completed milestones collapsed in `<details>` for readability
+- Current/future milestones expanded
+- Continuous phase numbering (01-99)
+- Progress table includes milestone column

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/templates/summary-minimal.md

@@ -1,41 +1,41 @@
----
-phase: XX-name
-plan: YY
-subsystem: [primary category]
-tags: [searchable tech]
-provides:
-  - [bullet list of what was built/delivered]
-affects: [list of phase names or keywords]
-tech-stack:
-  added: [libraries/tools]
-  patterns: [architectural/code patterns]
-key-files:
-  created: [important files created]
-  modified: [important files modified]
-key-decisions: []
-duration: Xmin
-completed: YYYY-MM-DD
----
-
-# Phase [X]: [Name] Summary (Minimal)
-
-**[Substantive one-liner describing outcome]**
-
-## Performance
-- **Duration:** [time]
-- **Tasks:** [count]
-- **Files modified:** [count]
-
-## Accomplishments
-- [Most important outcome]
-- [Second key accomplishment]
-
-## Task Commits
-1. **Task 1: [task name]** - `hash`
-2. **Task 2: [task name]** - `hash`
-
-## Files Created/Modified
-- `path/to/file.ts` - What it does
-
-## Next Phase Readiness
-[Ready for next phase]
+---
+phase: XX-name
+plan: YY
+subsystem: [primary category]
+tags: [searchable tech]
+provides:
+  - [bullet list of what was built/delivered]
+affects: [list of phase names or keywords]
+tech-stack:
+  added: [libraries/tools]
+  patterns: [architectural/code patterns]
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+key-decisions: []
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] Summary (Minimal)
+
+**[Substantive one-liner describing outcome]**
+
+## Performance
+- **Duration:** [time]
+- **Tasks:** [count]
+- **Files modified:** [count]
+
+## Accomplishments
+- [Most important outcome]
+- [Second key accomplishment]
+
+## Task Commits
+1. **Task 1: [task name]** - `hash`
+2. **Task 2: [task name]** - `hash`
+
+## Files Created/Modified
+- `path/to/file.ts` - What it does
+
+## Next Phase Readiness
+[Ready for next phase]