@howlil/ez-agents 3.4.1 → 3.5.0

package/ez-agents/templates/milestone-archive.md

@@ -1,123 +1,123 @@
-# Milestone Archive Template
-
-This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
-
----
-
-## File Template
-
-# Milestone v{{VERSION}}: {{MILESTONE_NAME}}
-
-**Status:** ✅ SHIPPED {{DATE}}
-**Phases:** {{PHASE_START}}-{{PHASE_END}}
-**Total Plans:** {{TOTAL_PLANS}}
-
-## Overview
-
-{{MILESTONE_DESCRIPTION}}
-
-## Phases
-
-{{PHASES_SECTION}}
-
-[For each phase in this milestone, include:]
-
-### Phase {{PHASE_NUM}}: {{PHASE_NAME}}
-
-**Goal**: {{PHASE_GOAL}}
-**Depends on**: {{DEPENDS_ON}}
-**Plans**: {{PLAN_COUNT}} plans
-
-Plans:
-
-- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
-- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
-      [... all plans ...]
-
-**Details:**
-{{PHASE_DETAILS_FROM_ROADMAP}}
-
-**For decimal phases, include (INSERTED) marker:**
-
-### Phase 2.1: Critical Security Patch (INSERTED)
-
-**Goal**: Fix authentication bypass vulnerability
-**Depends on**: Phase 2
-**Plans**: 1 plan
-
-Plans:
-
-- [x] 02.1-01: Patch auth vulnerability
-
-**Details:**
-{{PHASE_DETAILS_FROM_ROADMAP}}
-
----
-
-## Milestone Summary
-
-**Decimal Phases:**
-
-- Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix)
-- Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)
-
-**Key Decisions:**
-{{DECISIONS_FROM_PROJECT_STATE}}
-[Example:]
-
-- Decision: Use ROADMAP.md split (Rationale: Constant context cost)
-- Decision: Decimal phase numbering (Rationale: Clear insertion semantics)
-
-**Issues Resolved:**
-{{ISSUES_RESOLVED_DURING_MILESTONE}}
-[Example:]
-
-- Fixed context overflow at 100+ phases
-- Resolved phase insertion confusion
-
-**Issues Deferred:**
-{{ISSUES_DEFERRED_TO_LATER}}
-[Example:]
-
-- PROJECT-STATE.md tiering (deferred until decisions > 300)
-
-**Technical Debt Incurred:**
-{{SHORTCUTS_NEEDING_FUTURE_WORK}}
-[Example:]
-
-- Some workflows still have hardcoded paths (fix in Phase 5)
-
----
-
-_For current project status, see .planning/ROADMAP.md_
-
----
-
-## Usage Guidelines
-
-<guidelines>
-**When to create milestone archives:**
-- After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
-- Triggered by complete-milestone workflow
-- Before planning next milestone work
-
-**How to fill template:**
-
-- Replace {{PLACEHOLDERS}} with actual values
-- Extract phase details from ROADMAP.md
-- Document decimal phases with (INSERTED) marker
-- Include key decisions from PROJECT-STATE.md or SUMMARY files
-- List issues resolved vs deferred
-- Capture technical debt for future reference
-
-**Archive location:**
-
-- Save to `.planning/milestones/v{VERSION}-{NAME}.md`
-- Example: `.planning/milestones/v1.0-mvp.md`
-
-**After archiving:**
-
-- Update ROADMAP.md to collapse completed milestone in `<details>` tag
-- Update PROJECT.md to brownfield format with Current State section
-- Continue phase numbering in next milestone (never restart at 01)
-  </guidelines>
+# Milestone Archive Template
+
+This template is used by the complete-milestone workflow to create archive files in `.planning/milestones/`.
+
+---
+
+## File Template
+
+# Milestone v{{VERSION}}: {{MILESTONE_NAME}}
+
+**Status:** ✅ SHIPPED {{DATE}}
+**Phases:** {{PHASE_START}}-{{PHASE_END}}
+**Total Plans:** {{TOTAL_PLANS}}
+
+## Overview
+
+{{MILESTONE_DESCRIPTION}}
+
+## Phases
+
+{{PHASES_SECTION}}
+
+[For each phase in this milestone, include:]
+
+### Phase {{PHASE_NUM}}: {{PHASE_NAME}}
+
+**Goal**: {{PHASE_GOAL}}
+**Depends on**: {{DEPENDS_ON}}
+**Plans**: {{PLAN_COUNT}} plans
+
+Plans:
+
+- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
+- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
+      [... all plans ...]
+
+**Details:**
+{{PHASE_DETAILS_FROM_ROADMAP}}
+
+**For decimal phases, include (INSERTED) marker:**
+
+### Phase 2.1: Critical Security Patch (INSERTED)
+
+**Goal**: Fix authentication bypass vulnerability
+**Depends on**: Phase 2
+**Plans**: 1 plan
+
+Plans:
+
+- [x] 02.1-01: Patch auth vulnerability
+
+**Details:**
+{{PHASE_DETAILS_FROM_ROADMAP}}
+
+---
+
+## Milestone Summary
+
+**Decimal Phases:**
+
+- Phase 2.1: Critical Security Patch (inserted after Phase 2 for urgent fix)
+- Phase 5.1: Performance Hotfix (inserted after Phase 5 for production issue)
+
+**Key Decisions:**
+{{DECISIONS_FROM_PROJECT_STATE}}
+[Example:]
+
+- Decision: Use ROADMAP.md split (Rationale: Constant context cost)
+- Decision: Decimal phase numbering (Rationale: Clear insertion semantics)
+
+**Issues Resolved:**
+{{ISSUES_RESOLVED_DURING_MILESTONE}}
+[Example:]
+
+- Fixed context overflow at 100+ phases
+- Resolved phase insertion confusion
+
+**Issues Deferred:**
+{{ISSUES_DEFERRED_TO_LATER}}
+[Example:]
+
+- PROJECT-STATE.md tiering (deferred until decisions > 300)
+
+**Technical Debt Incurred:**
+{{SHORTCUTS_NEEDING_FUTURE_WORK}}
+[Example:]
+
+- Some workflows still have hardcoded paths (fix in Phase 5)
+
+---
+
+_For current project status, see .planning/ROADMAP.md_
+
+---
+
+## Usage Guidelines
+
+<guidelines>
+**When to create milestone archives:**
+- After completing all phases in a milestone (v1.0, v1.1, v2.0, etc.)
+- Triggered by complete-milestone workflow
+- Before planning next milestone work
+
+**How to fill template:**
+
+- Replace {{PLACEHOLDERS}} with actual values
+- Extract phase details from ROADMAP.md
+- Document decimal phases with (INSERTED) marker
+- Include key decisions from PROJECT-STATE.md or SUMMARY files
+- List issues resolved vs deferred
+- Capture technical debt for future reference
+
+**Archive location:**
+
+- Save to `.planning/milestones/v{VERSION}-{NAME}.md`
+- Example: `.planning/milestones/v1.0-mvp.md`
+
+**After archiving:**
+
+- Update ROADMAP.md to collapse completed milestone in `<details>` tag
+- Update PROJECT.md to brownfield format with Current State section
+- Continue phase numbering in next milestone (never restart at 01)
+  </guidelines>

package/ez-agents/templates/milestone.md

@@ -1,115 +1,115 @@
-# Milestone Entry Template
-
-Add this entry to `.planning/MILESTONES.md` when completing a milestone:
-
-```markdown
-## v[X.Y] [Name] (Shipped: YYYY-MM-DD)
-
-**Delivered:** [One sentence describing what shipped]
-
-**Phases completed:** [X-Y] ([Z] plans total)
-
-**Key accomplishments:**
-- [Major achievement 1]
-- [Major achievement 2]
-- [Major achievement 3]
-- [Major achievement 4]
-
-**Stats:**
-- [X] files created/modified
-- [Y] lines of code (primary language)
-- [Z] phases, [N] plans, [M] tasks
-- [D] days from start to ship (or milestone to milestone)
-
-**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
-
-**What's next:** [Brief description of next milestone goals, or "Project complete"]
-
----
-```
-
-<structure>
-If MILESTONES.md doesn't exist, create it with header:
-
-```markdown
-# Project Milestones: [Project Name]
-
-[Entries in reverse chronological order - newest first]
-```
-</structure>
-
-<guidelines>
-**When to create milestones:**
-- Initial v1.0 MVP shipped
-- Major version releases (v2.0, v3.0)
-- Significant feature milestones (v1.1, v1.2)
-- Before archiving planning (capture what was shipped)
-
-**Don't create milestones for:**
-- Individual phase completions (normal workflow)
-- Work in progress (wait until shipped)
-- Minor bug fixes that don't constitute a release
-
-**Stats to include:**
-- Count modified files: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
-- Count LOC: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (or relevant extension)
-- Phase/plan/task counts from ROADMAP
-- Timeline from first phase commit to last phase commit
-
-**Git range format:**
-- First commit of milestone → last commit of milestone
-- Example: `feat(01-01)` → `feat(04-01)` for phases 1-4
-</guidelines>
-
-<example>
-```markdown
-# Project Milestones: WeatherBar
-
-## v1.1 Security & Polish (Shipped: 2025-12-10)
-
-**Delivered:** Security hardening with Keychain integration and comprehensive error handling
-
-**Phases completed:** 5-6 (3 plans total)
-
-**Key accomplishments:**
-- Migrated API key storage from plaintext to macOS Keychain
-- Implemented comprehensive error handling for network failures
-- Added Sentry crash reporting integration
-- Fixed memory leak in auto-refresh timer
-
-**Stats:**
-- 23 files modified
-- 650 lines of Swift added
-- 2 phases, 3 plans, 12 tasks
-- 8 days from v1.0 to v1.1
-
-**Git range:** `feat(05-01)` → `feat(06-02)`
-
-**What's next:** v2.0 SwiftUI redesign with widget support
-
----
-
-## v1.0 MVP (Shipped: 2025-11-25)
-
-**Delivered:** Menu bar weather app with current conditions and 3-day forecast
-
-**Phases completed:** 1-4 (7 plans total)
-
-**Key accomplishments:**
-- Menu bar app with popover UI (AppKit)
-- OpenWeather API integration with auto-refresh
-- Current weather display with conditions icon
-- 3-day forecast list with high/low temperatures
-- Code signed and notarized for distribution
-
-**Stats:**
-- 47 files created
-- 2,450 lines of Swift
-- 4 phases, 7 plans, 28 tasks
-- 12 days from start to ship
-
-**Git range:** `feat(01-01)` → `feat(04-01)`
-
-**What's next:** Security audit and hardening for v1.1
-```
-</example>
+# Milestone Entry Template
+
+Add this entry to `.planning/MILESTONES.md` when completing a milestone:
+
+```markdown
+## v[X.Y] [Name] (Shipped: YYYY-MM-DD)
+
+**Delivered:** [One sentence describing what shipped]
+
+**Phases completed:** [X-Y] ([Z] plans total)
+
+**Key accomplishments:**
+- [Major achievement 1]
+- [Major achievement 2]
+- [Major achievement 3]
+- [Major achievement 4]
+
+**Stats:**
+- [X] files created/modified
+- [Y] lines of code (primary language)
+- [Z] phases, [N] plans, [M] tasks
+- [D] days from start to ship (or milestone to milestone)
+
+**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
+
+**What's next:** [Brief description of next milestone goals, or "Project complete"]
+
+---
+```
+
+<structure>
+If MILESTONES.md doesn't exist, create it with header:
+
+```markdown
+# Project Milestones: [Project Name]
+
+[Entries in reverse chronological order - newest first]
+```
+</structure>
+
+<guidelines>
+**When to create milestones:**
+- Initial v1.0 MVP shipped
+- Major version releases (v2.0, v3.0)
+- Significant feature milestones (v1.1, v1.2)
+- Before archiving planning (capture what was shipped)
+
+**Don't create milestones for:**
+- Individual phase completions (normal workflow)
+- Work in progress (wait until shipped)
+- Minor bug fixes that don't constitute a release
+
+**Stats to include:**
+- Count modified files: `git diff --stat feat(XX-XX)..feat(YY-YY) | tail -1`
+- Count LOC: `find . -name "*.swift" -o -name "*.ts" | xargs wc -l` (or relevant extension)
+- Phase/plan/task counts from ROADMAP
+- Timeline from first phase commit to last phase commit
+
+**Git range format:**
+- First commit of milestone → last commit of milestone
+- Example: `feat(01-01)` → `feat(04-01)` for phases 1-4
+</guidelines>
+
+<example>
+```markdown
+# Project Milestones: WeatherBar
+
+## v1.1 Security & Polish (Shipped: 2025-12-10)
+
+**Delivered:** Security hardening with Keychain integration and comprehensive error handling
+
+**Phases completed:** 5-6 (3 plans total)
+
+**Key accomplishments:**
+- Migrated API key storage from plaintext to macOS Keychain
+- Implemented comprehensive error handling for network failures
+- Added Sentry crash reporting integration
+- Fixed memory leak in auto-refresh timer
+
+**Stats:**
+- 23 files modified
+- 650 lines of Swift added
+- 2 phases, 3 plans, 12 tasks
+- 8 days from v1.0 to v1.1
+
+**Git range:** `feat(05-01)` → `feat(06-02)`
+
+**What's next:** v2.0 SwiftUI redesign with widget support
+
+---
+
+## v1.0 MVP (Shipped: 2025-11-25)
+
+**Delivered:** Menu bar weather app with current conditions and 3-day forecast
+
+**Phases completed:** 1-4 (7 plans total)
+
+**Key accomplishments:**
+- Menu bar app with popover UI (AppKit)
+- OpenWeather API integration with auto-refresh
+- Current weather display with conditions icon
+- 3-day forecast list with high/low temperatures
+- Code signed and notarized for distribution
+
+**Stats:**
+- 47 files created
+- 2,450 lines of Swift
+- 4 phases, 7 plans, 28 tasks
+- 12 days from start to ship
+
+**Git range:** `feat(01-01)` → `feat(04-01)`
+
+**What's next:** Security audit and hardening for v1.1
+```
+</example>

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 |