@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/references/git-planning-commit.md

@@ -1,38 +1,38 @@
-# Git Planning Commit
-
-Commit planning artifacts using the ez-tools CLI, which automatically checks `commit_docs` config and gitignore status.
-
-## Commit via CLI
-
-Always use `ez-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
-```
-
-The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
-
-## Amend previous commit
-
-To fold `.planning/` file changes into the previous commit:
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "" --files .planning/codebase/*.md --amend
-```
-
-## Commit Message Patterns
-
-| Command | Scope | Example |
-|---------|-------|---------|
-| plan-phase | phase | `docs(phase-03): create authentication plans` |
-| execute-phase | phase | `docs(phase-03): complete authentication phase` |
-| new-milestone | milestone | `docs: start milestone v1.1` |
-| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
-| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
-| add-phase | phase | `docs: add phase 07 (settings page)` |
-
-## When to Skip
-
-- `commit_docs: false` in config
-- `.planning/` is gitignored
-- No changes to commit (check with `git status --porcelain .planning/`)
+# Git Planning Commit
+
+Commit planning artifacts using the ez-tools CLI, which automatically checks `commit_docs` config and gitignore status.
+
+## Commit via CLI
+
+Always use `ez-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+```
+
+The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
+
+## Amend previous commit
+
+To fold `.planning/` file changes into the previous commit:
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "" --files .planning/codebase/*.md --amend
+```
+
+## Commit Message Patterns
+
+| Command | Scope | Example |
+|---------|-------|---------|
+| plan-phase | phase | `docs(phase-03): create authentication plans` |
+| execute-phase | phase | `docs(phase-03): complete authentication phase` |
+| new-milestone | milestone | `docs: start milestone v1.1` |
+| remove-phase | chore | `chore: remove phase 17 (dashboard)` |
+| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
+| add-phase | phase | `docs: add phase 07 (settings page)` |
+
+## When to Skip
+
+- `commit_docs: false` in config
+- `.planning/` is gitignored
+- No changes to commit (check with `git status --porcelain .planning/`)

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
+```

package/ez-agents/references/model-profile-resolution.md

@@ -1,34 +1,34 @@
-# Model Profile Resolution
-
-Resolve model profile once at the start of orchestration, then use it for all Task spawns.
-
-## Resolution Pattern
-
-```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
-```
-
-Default: `balanced` if not set or config missing.
-
-## Lookup Table
-
-@~/.claude/ez-agents/references/model-profiles.md
-
-Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
-
-```
-Task(
-  prompt="...",
-  subagent_type="ez-planner",
-  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
-)
-```
-
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
-
-## Usage
-
-1. Resolve once at orchestration start
-2. Store the profile value
-3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)
+# Model Profile Resolution
+
+Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+
+## Resolution Pattern
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default: `balanced` if not set or config missing.
+
+## Lookup Table
+
+@~/.claude/ez-agents/references/model-profiles.md
+
+Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+
+```
+Task(
+  prompt="...",
+  subagent_type="ez-planner",
+  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+)
+```
+
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+
+## Usage
+
+1. Resolve once at orchestration start
+2. Store the profile value
+3. Look up each agent's model from the table when spawning
+4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)

package/ez-agents/references/model-profiles.md

@@ -1,93 +1,93 @@
-# Model Profiles
-
-Model profiles control which Claude model each EZ Agents agent uses. This allows balancing quality vs token spend.
-
-## Profile Definitions
-
-| Agent | `quality` | `balanced` | `budget` |
-|-------|-----------|------------|----------|
-| ez-planner | opus | opus | sonnet |
-| ez-roadmapper | opus | sonnet | sonnet |
-| ez-executor | opus | sonnet | sonnet |
-| ez-phase-researcher | opus | sonnet | haiku |
-| ez-project-researcher | opus | sonnet | haiku |
-| ez-research-synthesizer | sonnet | sonnet | haiku |
-| ez-debugger | opus | sonnet | sonnet |
-| ez-codebase-mapper | sonnet | haiku | haiku |
-| ez-verifier | sonnet | sonnet | haiku |
-| ez-plan-checker | sonnet | sonnet | haiku |
-| ez-integration-checker | sonnet | sonnet | haiku |
-| ez-nyquist-auditor | sonnet | sonnet | haiku |
-
-## Profile Philosophy
-
-**quality** - Maximum reasoning power
-- Opus for all decision-making agents
-- Sonnet for read-only verification
-- Use when: quota available, critical architecture work
-
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
-- Use when: normal development, good balance of quality and cost
-
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
-- Use when: conserving quota, high-volume work, less critical phases
-
-## Resolution Logic
-
-Orchestrators resolve model before spawning:
-
-```
-1. Read .planning/config.json
-2. Check model_overrides for agent-specific override
-3. If no override, look up agent in profile table
-4. Pass model parameter to Task call
-```
-
-## Per-Agent Overrides
-
-Override specific agents without changing the entire profile:
-
-```json
-{
-  "model_profile": "balanced",
-  "model_overrides": {
-    "ez-executor": "opus",
-    "ez-planner": "haiku"
-  }
-}
-```
-
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
-
-## Switching Profiles
-
-Runtime: `/ez:set-profile <profile>`
-
-Per-project default: Set in `.planning/config.json`:
-```json
-{
-  "model_profile": "balanced"
-}
-```
-
-## Design Rationale
-
-**Why Opus for ez-planner?**
-Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
-
-**Why Sonnet for ez-executor?**
-Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
-
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
-
-**Why Haiku for ez-codebase-mapper?**
-Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
-
-**Why `inherit` instead of passing `opus` directly?**
-Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. EZ Agents returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.
+# Model Profiles
+
+Model profiles control which Claude model each EZ Agents agent uses. This allows balancing quality vs token spend.
+
+## Profile Definitions
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| ez-planner | opus | opus | sonnet |
+| ez-roadmapper | opus | sonnet | sonnet |
+| ez-executor | opus | sonnet | sonnet |
+| ez-phase-researcher | opus | sonnet | haiku |
+| ez-project-researcher | opus | sonnet | haiku |
+| ez-research-synthesizer | sonnet | sonnet | haiku |
+| ez-debugger | opus | sonnet | sonnet |
+| ez-codebase-mapper | sonnet | haiku | haiku |
+| ez-verifier | sonnet | sonnet | haiku |
+| ez-plan-checker | sonnet | sonnet | haiku |
+| ez-integration-checker | sonnet | sonnet | haiku |
+| ez-nyquist-auditor | sonnet | sonnet | haiku |
+
+## Profile Philosophy
+
+**quality** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- Use when: quota available, critical architecture work
+
+**balanced** (default) - Smart allocation
+- Opus only for planning (where architecture decisions happen)
+- Sonnet for execution and research (follows explicit instructions)
+- Sonnet for verification (needs reasoning, not just pattern matching)
+- Use when: normal development, good balance of quality and cost
+
+**budget** - Minimal Opus usage
+- Sonnet for anything that writes code
+- Haiku for research and verification
+- Use when: conserving quota, high-volume work, less critical phases
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning:
+
+```
+1. Read .planning/config.json
+2. Check model_overrides for agent-specific override
+3. If no override, look up agent in profile table
+4. Pass model parameter to Task call
+```
+
+## Per-Agent Overrides
+
+Override specific agents without changing the entire profile:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "ez-executor": "opus",
+    "ez-planner": "haiku"
+  }
+}
+```
+
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
+
+## Switching Profiles
+
+Runtime: `/ez:set-profile <profile>`
+
+Per-project default: Set in `.planning/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## Design Rationale
+
+**Why Opus for ez-planner?**
+Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+
+**Why Sonnet for ez-executor?**
+Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
+
+**Why Sonnet (not Haiku) for verifiers in balanced?**
+Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+
+**Why Haiku for ez-codebase-mapper?**
+Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
+
+**Why `inherit` instead of passing `opus` directly?**
+Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. EZ Agents returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.

package/ez-agents/references/phase-argument-parsing.md

@@ -1,61 +1,61 @@
-# Phase Argument Parsing
-
-Parse and normalize phase arguments for commands that operate on phases.
-
-## Extraction
-
-From `$ARGUMENTS`:
-- Extract phase number (first numeric argument)
-- Extract flags (prefixed with `--`)
-- Remaining text is description (for insert/add commands)
-
-## Using ez-tools
-
-The `find-phase` command handles normalization and validation in one step:
-
-```bash
-PHASE_INFO=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" find-phase "${PHASE}")
-```
-
-Returns JSON with:
-- `found`: true/false
-- `directory`: Full path to phase directory
-- `phase_number`: Normalized number (e.g., "06", "06.1")
-- `phase_name`: Name portion (e.g., "foundation")
-- `plans`: Array of PLAN.md files
-- `summaries`: Array of SUMMARY.md files
-
-## Manual Normalization (Legacy)
-
-Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
-
-```bash
-# Normalize phase number
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
-fi
-```
-
-## Validation
-
-Use `roadmap get-phase` to validate phase exists:
-
-```bash
-PHASE_CHECK=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE}")
-if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
-  echo "ERROR: Phase ${PHASE} not found in roadmap"
-  exit 1
-fi
-```
-
-## Directory Lookup
-
-Use `find-phase` for directory lookup:
-
-```bash
-PHASE_DIR=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" find-phase "${PHASE}" --raw)
-```
+# Phase Argument Parsing
+
+Parse and normalize phase arguments for commands that operate on phases.
+
+## Extraction
+
+From `$ARGUMENTS`:
+- Extract phase number (first numeric argument)
+- Extract flags (prefixed with `--`)
+- Remaining text is description (for insert/add commands)
+
+## Using ez-tools
+
+The `find-phase` command handles normalization and validation in one step:
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" find-phase "${PHASE}")
+```
+
+Returns JSON with:
+- `found`: true/false
+- `directory`: Full path to phase directory
+- `phase_number`: Normalized number (e.g., "06", "06.1")
+- `phase_name`: Name portion (e.g., "foundation")
+- `plans`: Array of PLAN.md files
+- `summaries`: Array of SUMMARY.md files
+
+## Manual Normalization (Legacy)
+
+Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
+
+```bash
+# Normalize phase number
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # Integer: 8 → 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # Decimal: 2.1 → 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## Validation
+
+Use `roadmap get-phase` to validate phase exists:
+
+```bash
+PHASE_CHECK=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE}")
+if [ "$(printf '%s\n' "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
+  echo "ERROR: Phase ${PHASE} not found in roadmap"
+  exit 1
+fi
+```
+
+## Directory Lookup
+
+Use `find-phase` for directory lookup:
+
+```bash
+PHASE_DIR=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" find-phase "${PHASE}" --raw)
+```