@howlil/ez-agents 3.5.0 → 4.0.0

package/commands/ez/map-codebase.md

@@ -1,71 +1,71 @@
----
-name: ez:map-codebase
-description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
-argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-<objective>
-Analyze existing codebase using parallel ez-codebase-mapper agents to produce structured codebase documents.
-
-Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
-
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/map-codebase.md
-</execution_context>
-
-<context>
-Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
-
-**Load project state if exists:**
-Check for .planning/STATE.md - loads context if project already initialized
-
-**This command can run:**
-- Before /ez:new-project (brownfield codebases) - creates codebase map first
-- After /ez:new-project (greenfield codebases) - updates codebase map as code evolves
-- Anytime to refresh codebase understanding
-</context>
-
-<when_to_use>
-**Use map-codebase for:**
-- Brownfield projects before initialization (understand existing code first)
-- Refreshing codebase map after significant changes
-- Onboarding to an unfamiliar codebase
-- Before major refactoring (understand current state)
-- When STATE.md references outdated codebase info
-
-**Skip map-codebase for:**
-- Greenfield projects with no code yet (nothing to map)
-- Trivial codebases (<5 files)
-</when_to_use>
-
-<process>
-1. Check if .planning/codebase/ already exists (offer to refresh or skip)
-2. Create .planning/codebase/ directory structure
-3. Spawn 4 parallel ez-codebase-mapper agents:
-   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
-   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
-   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
-   - Agent 4: concerns focus → writes CONCERNS.md
-4. Wait for agents to complete, collect confirmations (NOT document contents)
-5. Verify all 7 documents exist with line counts
-6. Commit codebase map
-7. Offer next steps (typically: /ez:new-project or /ez:plan-phase)
-</process>
-
-<success_criteria>
-- [ ] .planning/codebase/ directory created
-- [ ] All 7 codebase documents written by mapper agents
-- [ ] Documents follow template structure
-- [ ] Parallel agents completed without errors
-- [ ] User knows next steps
-</success_criteria>
+---
+name: ez:map-codebase
+description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel ez-codebase-mapper agents to produce structured codebase documents.
+
+Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/map-codebase.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /ez:new-project (brownfield codebases) - creates codebase map first
+- After /ez:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel ez-codebase-mapper agents:
+   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
+   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
+   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
+   - Agent 4: concerns focus → writes CONCERNS.md
+4. Wait for agents to complete, collect confirmations (NOT document contents)
+5. Verify all 7 documents exist with line counts
+6. Commit codebase map
+7. Offer next steps (typically: /ez:new-project or /ez:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written by mapper agents
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/ez/new-milestone.md

@@ -1,44 +1,44 @@
----
-name: ez:new-milestone
-description: Start a new milestone cycle — update PROJECT.md and route to requirements
-argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Task
-  - AskUserQuestion
----
-<objective>
-Start a new milestone: questioning → research (optional) → requirements → roadmap.
-
-Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Gathers "what's next", updates PROJECT.md, then runs requirements → roadmap cycle.
-
-**Creates/Updates:**
-- `.planning/PROJECT.md` — updated with new milestone goals
-- `.planning/research/` — domain research (optional, NEW features only)
-- `.planning/REQUIREMENTS.md` — scoped requirements for this milestone
-- `.planning/ROADMAP.md` — phase structure (continues numbering)
-- `.planning/STATE.md` — reset for new milestone
-
-**After:** `/ez:plan-phase [N]` to start execution.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/new-milestone.md
-@~/.claude/ez-agents/references/questioning.md
-@~/.claude/ez-agents/references/ui-brand.md
-@~/.claude/ez-agents/templates/project.md
-@~/.claude/ez-agents/templates/requirements.md
-</execution_context>
-
-<context>
-Milestone name: $ARGUMENTS (optional - will prompt if not provided)
-
-Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
-</context>
-
-<process>
-Execute the new-milestone workflow from @~/.claude/ez-agents/workflows/new-milestone.md end-to-end.
-Preserve all workflow gates (validation, questioning, research, requirements, roadmap approval, commits).
-</process>
+---
+name: ez:new-milestone
+description: Start a new milestone cycle — update PROJECT.md and route to requirements
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Start a new milestone: questioning → research (optional) → requirements → roadmap.
+
+Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Gathers "what's next", updates PROJECT.md, then runs requirements → roadmap cycle.
+
+**Creates/Updates:**
+- `.planning/PROJECT.md` — updated with new milestone goals
+- `.planning/research/` — domain research (optional, NEW features only)
+- `.planning/REQUIREMENTS.md` — scoped requirements for this milestone
+- `.planning/ROADMAP.md` — phase structure (continues numbering)
+- `.planning/STATE.md` — reset for new milestone
+
+**After:** `/ez:plan-phase [N]` to start execution.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/new-milestone.md
+@~/.claude/ez-agents/references/questioning.md
+@~/.claude/ez-agents/references/ui-brand.md
+@~/.claude/ez-agents/templates/project.md
+@~/.claude/ez-agents/templates/requirements.md
+</execution_context>
+
+<context>
+Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+
+Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
+</context>
+
+<process>
+Execute the new-milestone workflow from @~/.claude/ez-agents/workflows/new-milestone.md end-to-end.
+Preserve all workflow gates (validation, questioning, research, requirements, roadmap approval, commits).
+</process>

package/commands/ez/new-project.md

@@ -1,42 +1,51 @@
----
-name: ez:new-project
-description: Initialize a new project with deep context gathering and PROJECT.md
-argument-hint: "[--auto]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Task
-  - AskUserQuestion
----
-<context>
-**Flags:**
-- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
-</context>
-
-<objective>
-Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
-
-**Creates:**
-- `.planning/PROJECT.md` — project context
-- `.planning/config.json` — workflow preferences
-- `.planning/research/` — domain research (optional)
-- `.planning/REQUIREMENTS.md` — scoped requirements
-- `.planning/ROADMAP.md` — phase structure
-- `.planning/STATE.md` — project memory
-
-**After this command:** Run `/ez:plan-phase 1` to start execution.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/new-project.md
-@~/.claude/ez-agents/references/questioning.md
-@~/.claude/ez-agents/references/ui-brand.md
-@~/.claude/ez-agents/templates/project.md
-@~/.claude/ez-agents/templates/requirements.md
-</execution_context>
-
-<process>
-Execute the new-project workflow from @~/.claude/ez-agents/workflows/new-project.md end-to-end.
-Preserve all workflow gates (validation, approvals, commits, routing).
-</process>
+---
+name: ez:new-project
+description: Initialize a new project with deep context gathering and PROJECT.md
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<context>
+**Flags:**
+- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
+</context>
+
+<objective>
+Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
+
+**Creates:**
+- `.planning/PROJECT.md` — project context
+- `.planning/config.json` — workflow preferences
+- `.planning/research/` — domain research (optional)
+- `.planning/REQUIREMENTS.md` — scoped requirements
+- `.planning/ROADMAP.md` — phase structure
+- `.planning/STATE.md` — project memory
+- `.planning/ADR/` — Architecture Decision Records (optional)
+
+**Architecture Decision:**
+Uses `principal_engineer_decision_v1` skill to recommend:
+- Architecture pattern (monolith, modular monolith, microservices)
+- Tech stack (backend, frontend, database)
+- Infrastructure (deployment, scaling strategy)
+Based on team size, timeline, budget, and complexity.
+
+**After this command:** Run `/ez:plan-phase 1` to start execution.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/new-project.md
+@~/.claude/ez-agents/references/questioning.md
+@~/.claude/ez-agents/references/ui-brand.md
+@~/.claude/ez-agents/templates/project.md
+@~/.claude/ez-agents/templates/requirements.md
+@skills/architecture/principal-engineer-decision/principal_engineer_decision_v1/SKILL.md
+</execution_context>
+
+<process>
+Execute the new-project workflow from @~/.claude/ez-agents/workflows/new-project.md end-to-end.
+Preserve all workflow gates (validation, approvals, commits, routing).
+</process>

package/commands/ez/plan-phase.md

@@ -1,53 +1,53 @@
----
-name: ez:plan-phase
-description: Create detailed phase plan (PLAN.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--no-auto] [--verbose]"
-agent: ez-planner
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - WebFetch
-  - mcp__context7__*
----
-<objective>
-Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.
-
-**Default flow:** Research (if needed) → Plan → Verify → Done
-
-**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn ez-planner, verify with ez-plan-checker, iterate until pass or max iterations, present results.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/plan-phase.md
-@~/.claude/ez-agents/references/ui-brand.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
-
-**Flags:**
-- `--research` — Force re-research even if RESEARCH.md exists
-- `--skip-research` — Skip research, go straight to planning
-- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
-- `--skip-verify` — Skip verification loop
-- `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
-- `--no-auto` — Disable smart orchestration (skip auto discuss-phase for sensitive areas).
-- `--verbose` — Show detail for every auto-invocation step.
-- `--skip-discussion` — Skip auto discuss-phase only (more granular than --no-auto).
-
-**Smart Orchestration (auto, unless --no-auto):**
-- Detects sensitive area keywords in phase name/goal: `auth`, `login`, `jwt`, `oauth`, `database`, `migration`, `schema`, `payment`, `billing`, `security`
-- If detected AND no CONTEXT.md exists: auto-runs `discuss-phase --auto` before planning
-- All auto-invocations appear with `[auto]` prefix in output
-
-Normalize phase input in step 2 before any directory lookups.
-</context>
-
-<process>
-Execute the plan-phase workflow from @~/.claude/ez-agents/workflows/plan-phase.md end-to-end.
-Preserve all workflow gates (validation, research, planning, verification loop, routing).
-</process>
+---
+name: ez:plan-phase
+description: Create detailed phase plan (PLAN.md) with verification loop
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--no-auto] [--verbose]"
+agent: ez-planner
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - mcp__context7__*
+---
+<objective>
+Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.
+
+**Default flow:** Research (if needed) → Plan → Verify → Done
+
+**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn ez-planner, verify with ez-plan-checker, iterate until pass or max iterations, present results.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/plan-phase.md
+@~/.claude/ez-agents/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
+
+**Flags:**
+- `--research` — Force re-research even if RESEARCH.md exists
+- `--skip-research` — Skip research, go straight to planning
+- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
+- `--skip-verify` — Skip verification loop
+- `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
+- `--no-auto` — Disable smart orchestration (skip auto discuss-phase for sensitive areas).
+- `--verbose` — Show detail for every auto-invocation step.
+- `--skip-discussion` — Skip auto discuss-phase only (more granular than --no-auto).
+
+**Smart Orchestration (auto, unless --no-auto):**
+- Detects sensitive area keywords in phase name/goal: `auth`, `login`, `jwt`, `oauth`, `database`, `migration`, `schema`, `payment`, `billing`, `security`
+- If detected AND no CONTEXT.md exists: auto-runs `discuss-phase --auto` before planning
+- All auto-invocations appear with `[auto]` prefix in output
+
+Normalize phase input in step 2 before any directory lookups.
+</context>
+
+<process>
+Execute the plan-phase workflow from @~/.claude/ez-agents/workflows/plan-phase.md end-to-end.
+Preserve all workflow gates (validation, research, planning, verification loop, routing).
+</process>

package/commands/ez/progress.md

@@ -1,36 +1,36 @@
----
-name: ez:progress
-description: Check project progress, show context, and route to next action (execute or plan)
-argument-hint: "[--no-auto]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-<objective>
-Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
-
-Provides situational awareness before continuing work.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/progress.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Flags:**
-- `--no-auto` — Disable silent health check auto-invocation.
-
-**Smart Orchestration (auto, unless --no-auto):**
-- Pre: health check (warns in report on FAIL, does not stop progress)
-
-Health check result is silent on pass. Only shown in output if health fails.
-</context>
-
-<process>
-Execute the progress workflow from @~/.claude/ez-agents/workflows/progress.md end-to-end.
-Preserve all routing logic (Routes A through F) and edge case handling.
-</process>
+---
+name: ez:progress
+description: Check project progress, show context, and route to next action (execute or plan)
+argument-hint: "[--no-auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+<objective>
+Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
+
+Provides situational awareness before continuing work.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/progress.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Flags:**
+- `--no-auto` — Disable silent health check auto-invocation.
+
+**Smart Orchestration (auto, unless --no-auto):**
+- Pre: health check (warns in report on FAIL, does not stop progress)
+
+Health check result is silent on pass. Only shown in output if health fails.
+</context>
+
+<process>
+Execute the progress workflow from @~/.claude/ez-agents/workflows/progress.md end-to-end.
+Preserve all routing logic (Routes A through F) and edge case handling.
+</process>

package/commands/ez/quick.md

@@ -1,45 +1,45 @@
----
-name: ez:quick
-description: Execute a quick task with EZ Agents guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full] [--discuss]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - Bash
-  - Task
-  - AskUserQuestion
----
-<objective>
-Execute small, ad-hoc tasks with EZ Agents guarantees (atomic commits, STATE.md tracking).
-
-Quick mode is the same system with a shorter path:
-- Spawns ez-planner (quick mode) + ez-executor(s)
-- Quick tasks live in `.planning/quick/` separate from planned phases
-- Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
-
-**Default:** Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do.
-
-**`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
-
-**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
-
-Flags are composable: `--discuss --full` gives discussion + plan-checking + verification.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/quick.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-
-Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
-</context>
-
-<process>
-Execute the quick workflow from @~/.claude/ez-agents/workflows/quick.md end-to-end.
-Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
-</process>
+---
+name: ez:quick
+description: Execute a quick task with EZ Agents guarantees (atomic commits, state tracking) but skip optional agents
+argument-hint: "[--full] [--discuss]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Execute small, ad-hoc tasks with EZ Agents guarantees (atomic commits, STATE.md tracking).
+
+Quick mode is the same system with a shorter path:
+- Spawns ez-planner (quick mode) + ez-executor(s)
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
+
+**Default:** Skips research, discussion, plan-checker, verifier. Use when you know exactly what to do.
+
+**`--discuss` flag:** Lightweight discussion phase before planning. Surfaces assumptions, clarifies gray areas, captures decisions in CONTEXT.md. Use when the task has ambiguity worth resolving upfront.
+
+**`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
+
+Flags are composable: `--discuss --full` gives discussion + plan-checking + verification.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the quick workflow from @~/.claude/ez-agents/workflows/quick.md end-to-end.
+Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
+</process>