@howlil/ez-agents 3.4.1 → 3.5.0

package/ez-agents/references/continuation-format.md

@@ -1,249 +1,249 @@
-# Continuation Format
-
-Standard format for presenting next steps after completing a command or workflow.
-
-## Core Structure
-
-```
----
-
-## ▶ Next Up
-
-**{identifier}: {name}** — {one-line description}
-
-`{command to copy-paste}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `{alternative option 1}` — description
-- `{alternative option 2}` — description
-
----
-```
-
-## Format Rules
-
-1. **Always show what it is** — name + description, never just a command path
-2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
-3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
-4. **`/clear` explanation** — always include, keeps it concise but explains why
-5. **"Also available" not "Other options"** — sounds more app-like
-6. **Visual separators** — `---` above and below to make it stand out
-
-## Variants
-
-### Execute Next Plan
-
-```
----
-
-## ▶ Next Up
-
-**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
-
-`/ez:execute-phase 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Review plan before executing
-- `/ez:list-phase-assumptions 2` — check assumptions
-
----
-```
-
-### Execute Final Plan in Phase
-
-Add note that this is the last plan and what comes after:
-
-```
----
-
-## ▶ Next Up
-
-**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
-<sub>Final plan in Phase 2</sub>
-
-`/ez:execute-phase 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**After this completes:**
-- Phase 2 → Phase 3 transition
-- Next: **Phase 3: Core Features** — User dashboard and settings
-
----
-```
-
-### Plan a Phase
-
-```
----
-
-## ▶ Next Up
-
-**Phase 2: Authentication** — JWT login flow with refresh tokens
-
-`/ez:plan-phase 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ez:discuss-phase 2` — gather context first
-- `/ez:research-phase 2` — investigate unknowns
-- Review roadmap
-
----
-```
-
-### Phase Complete, Ready for Next
-
-Show completion status before next action:
-
-```
----
-
-## ✓ Phase 2 Complete
-
-3/3 plans executed
-
-## ▶ Next Up
-
-**Phase 3: Core Features** — User dashboard, settings, and data export
-
-`/ez:plan-phase 3`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ez:discuss-phase 3` — gather context first
-- `/ez:research-phase 3` — investigate unknowns
-- Review what Phase 2 built
-
----
-```
-
-### Multiple Equal Options
-
-When there's no clear primary action:
-
-```
----
-
-## ▶ Next Up
-
-**Phase 3: Core Features** — User dashboard, settings, and data export
-
-**To plan directly:** `/ez:plan-phase 3`
-
-**To discuss context first:** `/ez:discuss-phase 3`
-
-**To research unknowns:** `/ez:research-phase 3`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-### Milestone Complete
-
-```
----
-
-## 🎉 Milestone v1.0 Complete
-
-All 4 phases shipped
-
-## ▶ Next Up
-
-**Start v1.1** — questioning → research → requirements → roadmap
-
-`/ez:new-milestone`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-## Pulling Context
-
-### For phases (from ROADMAP.md):
-
-```markdown
-### Phase 2: Authentication
-**Goal**: JWT login flow with refresh tokens
-```
-
-Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
-
-### For plans (from ROADMAP.md):
-
-```markdown
-Plans:
-- [ ] 02-03: Add refresh token rotation
-```
-
-Or from PLAN.md `<objective>`:
-
-```xml
-<objective>
-Add refresh token rotation with sliding expiry window.
-
-Purpose: Extend session lifetime without compromising security.
-</objective>
-```
-
-Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
-
-## Anti-Patterns
-
-### Don't: Command-only (no context)
-
-```
-## To Continue
-
-Run `/clear`, then paste:
-/ez:execute-phase 2
-```
-
-User has no idea what 02-03 is about.
-
-### Don't: Missing /clear explanation
-
-```
-`/ez:plan-phase 3`
-
-Run /clear first.
-```
-
-Doesn't explain why. User might skip it.
-
-### Don't: "Other options" language
-
-```
-Other options:
-- Review roadmap
-```
-
-Sounds like an afterthought. Use "Also available:" instead.
-
-### Don't: Fenced code blocks for commands
-
-```
-```
-/ez:plan-phase 3
-```
-```
-
-Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/ez:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/ez:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/ez:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/ez:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ez:discuss-phase 2` — gather context first
+- `/ez:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/ez:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ez:discuss-phase 3` — gather context first
+- `/ez:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/ez:plan-phase 3`
+
+**To discuss context first:** `/ez:discuss-phase 3`
+
+**To research unknowns:** `/ez:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/ez:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/ez:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/ez:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/ez:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/ez-agents/references/metrics-schema.md

@@ -0,0 +1,118 @@
+# Metrics Schema Reference
+
+Schema for `.planning/metrics.json` — the EZ Agents success metrics store.
+
+## Full Schema
+
+```json
+{
+  "schema_version": "1.0",
+  "project": "project-name",
+  "updated": "2026-03-19T00:00:00Z",
+
+  "phase_metrics": [
+    {
+      "phase": 18,
+      "phase_name": "session-memory",
+      "plans_total": 4,
+      "plans_completed": 4,
+      "velocity_min": 24,
+      "defect_density": 0.12,
+      "bdd_pass_rate": 0.84,
+      "bdd_must_passing": 8,
+      "bdd_must_total": 9,
+      "deviation_count": 2,
+      "completed_at": "2026-03-19T00:00:00Z"
+    }
+  ],
+
+  "project_metrics": {
+    "requirements_coverage_pct": 78,
+    "test_coverage_pct": 74,
+    "bdd_scenarios_total": 60,
+    "bdd_scenarios_passing": 45,
+    "bdd_scenarios_must": 25,
+    "bdd_scenarios_must_passing": 24
+  },
+
+  "agent_metrics": {
+    "total_token_cost_usd": 18.40,
+    "avg_cost_per_plan": 0.27,
+    "deviation_rate": 0.15,
+    "avg_plans_per_phase": 3.2,
+    "avg_velocity_min_per_plan": 22
+  },
+
+  "business_metrics": {
+    "time_to_first_ship_days": 95,
+    "hotfixes_deployed": 0,
+    "milestones_shipped": 1,
+    "current_tier": "medium",
+    "phases_total": 29,
+    "phases_completed": 18
+  }
+}
+```
+
+## Field Definitions
+
+### phase_metrics[]
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `phase` | int | ez-executor | Phase number |
+| `plans_total` | int | ez-executor | Plans in phase |
+| `plans_completed` | int | ez-executor | Plans with SUMMARY.md |
+| `velocity_min` | int | ez-executor | Minutes from first to last commit in phase |
+| `defect_density` | float | ez-executor | Deviations / tasks executed |
+| `bdd_pass_rate` | float | ez-verifier | @must scenarios passing / total @must |
+| `deviation_count` | int | ez-executor | Auto-fix deviations logged |
+
+### project_metrics
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `requirements_coverage_pct` | int | ez-executor | % of REQUIREMENTS.md checked off |
+| `test_coverage_pct` | int | ez-verifier | From coverage tool output |
+| `bdd_scenarios_passing` | int | ez-verifier | Scenarios with green status |
+
+### agent_metrics
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `total_token_cost_usd` | float | metrics-tracker | Accumulated from state.record-metric |
+| `avg_cost_per_plan` | float | metrics-tracker | total / plans_completed |
+| `deviation_rate` | float | metrics-tracker | total_deviations / total_tasks |
+
+### business_metrics
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `time_to_first_ship_days` | int | ez-release-agent | Days from project init to first release |
+| `hotfixes_deployed` | int | ez-release-agent | Hotfixes tagged and pushed |
+| `current_tier` | string | tier-manager | mvp / medium / enterprise |
+
+## Capture Points
+
+| Metric | When Captured | Who Captures |
+|--------|---------------|--------------|
+| velocity_min | After SUMMARY.md created | ez-executor (state record-metric) |
+| deviation_count | During execution | ez-executor (per deviation Rule 1-3) |
+| defect_density | After plan completes | ez-executor (computed) |
+| bdd_pass_rate | After VERIFICATION.md | ez-verifier (metrics record-bdd) |
+| test_coverage_pct | After verification | ez-verifier (from coverage tool) |
+| requirements_coverage_pct | After mark-complete | ez-executor (computed from REQUIREMENTS.md) |
+| total_token_cost_usd | Ongoing | ez-executor (from state.record-metric cost field) |
+| hotfixes_deployed | After hotfix tag | ez-release-agent |
+
+## Dashboard Output
+
+```
+/ez:stats  →  enhanced dashboard
+
+PROGRESS:  Phase 18/29 (62%) | Requirements 78% | BDD 80%
+VELOCITY:  22 min/plan avg | Trend: ↑ IMPROVING
+QUALITY:   Coverage 74% | Defect density 0.12 | Deviation 15%
+COSTS:     $18.40 total | $0.27/plan | Est. remaining: ~$3.00
+RELEASE:   Tier: Medium | Hotfixes: 0 | Blockers: 0
+```