@howlil/ez-agents 3.5.0 → 4.0.0

package/ez-agents/workflows/complete-milestone.md

@@ -24,7 +24,7 @@ When a milestone completes:
 4. Delete REQUIREMENTS.md (fresh one for next milestone)
 5. Perform full PROJECT.md evolution review
 6. Offer to create next milestone inline
-7. Archive UI artifacts (`*-UI-SPEC.md`, `*-UI-REVIEW.md`) alongside other phase documents
+7. Archive UI artifacts (SUMMARY.md, UAT.md) alongside other phase documents
 8. Clean up `.planning/ui-reviews/` screenshot files (binary assets, never archived)
 
 **Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.

package/ez-agents/workflows/discuss-phase.md

@@ -638,7 +638,7 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 **Also available:**
 - `/ez:plan-phase ${PHASE} --skip-research` — plan without research
-- `/ez:ui-phase ${PHASE}` — generate UI design contract before planning (if phase has frontend work)
+- Not a frontend phase → Continue without UI spec
 - Review/edit CONTEXT.md before continuing
 
 ---

package/ez-agents/workflows/execute-phase.md

@@ -131,7 +131,29 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2. **Spawn executor agents:**
+2. **Batch execution (resource-aware):**
+
+   Read `maxParallel` from config (default: 5). If wave has {N} plans:
+   - Batch size = maxParallel
+   - Number of batches = Math.ceil(N / maxParallel)
+   - Execute each batch sequentially, wait for all agents in batch to complete before next batch
+
+   ```bash
+   # Read maxParallel from config
+   MAX_PARALLEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get workflow.maxParallel 2>/dev/null || echo "5")
+
+   # Calculate batches
+   WAVE_PLAN_COUNT={N}
+   BATCH_COUNT=$(( (WAVE_PLAN_COUNT + MAX_PARALLEL - 1) / MAX_PARALLEL ))
+   ```
+
+   **Loop through batches:**
+   - Batch 1: Spawn min(remaining, maxParallel) agents
+   - Wait for all agents in batch to complete
+   - Check for failures before proceeding to next batch
+   - Repeat until all batches complete
+
+3. **Spawn executor agents:**
 
    Pass paths only — executors read files themselves with their fresh 200k context.
    This keeps orchestrator context lean (~10-15%).
@@ -262,20 +284,27 @@ After all waves:
 ```markdown
 ## Phase {X}: {Name} Execution Complete
 
-**Waves:** {N} | **Plans:** {M}/{total} complete
+**Waves:** {N} | **Plans:** {M}/{total} complete | **Blocked:** {B}
 
 | Wave | Plans | Status |
 |------|-------|--------|
 | 1 | plan-01, plan-02 | ✓ Complete |
 | CP | plan-03 | ✓ Verified |
 | 2 | plan-04 | ✓ Complete |
+| 3 | plan-05 | ⚠ Blocked (depends on failed plan-02) |
 
 ### Plan Details
 1. **03-01**: [one-liner from SUMMARY.md]
 2. **03-02**: [one-liner from SUMMARY.md]
 
+### Blocked Plans
+- **{plan-id}**: Blocked — depends on {failed-plan-id} (Wave {N})
+
 ### Issues Encountered
 [Aggregate from SUMMARYs, or "None"]
+
+### Failed Plans
+[List failed plans with error summary, or "None"]
 ```
 </step>
 
@@ -332,6 +361,76 @@ node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs(phase-${PARENT_PHAS
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
+## Design Review Gate (Frontend Phases Only)
+
+**If phase has frontend/UI work:** Spawn ez-design-expert BEFORE verifier.
+
+```bash
+# Check if phase has frontend indicators
+PHASE_SECTION=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE_NUMBER}" 2>/dev/null)
+echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
+HAS_UI=$?
+```
+
+**If `HAS_UI` is 0 (frontend found):**
+
+```
+Task(
+  prompt="Review UI design quality for phase {phase_number}.
+Phase directory: {phase_dir}
+Check: design token consistency, AI slop patterns, visual hierarchy.
+Report: PASS/PASS_WITH_WARNINGS/FAIL with specific fixes.
+Output: DESIGN-REVIEW.md",
+  subagent_type="ez-design-expert",
+  model="{planner_model}"
+)
+```
+
+**Read verdict:**
+```bash
+grep "^**Status:**" "$PHASE_DIR"/DESIGN-REVIEW.md | cut -d: -f2 | tr -d ' '
+```
+
+| Verdict | Action |
+|---------|--------|
+| `PASS` | → Continue to verifier |
+| `PASS_WITH_WARNINGS` | → Show warnings, continue to verifier |
+| `FAIL` | → Show critical issues, offer `/ez:plan-phase {N} --design-fixes` |
+
+**If FAIL:**
+```
+## ❌ Design Review Failed — Phase {X}: {Name}
+
+**AI Slop Detected:** {specific patterns found}
+
+### Critical Issues
+{List from DESIGN-REVIEW.md}
+
+---
+## ▶ Next Up
+
+`/ez:plan-phase {X} --design-fixes`
+
+<sub>`/clear` first → fresh context window</sub>
+
+Also: `cat {phase_dir}/DESIGN-REVIEW.md` — full report
+```
+
+**If PASS or PASS_WITH_WARNINGS:**
+```
+## ✅ Design Review Complete
+
+**Status:** {PASS | PASS_WITH_WARNINGS}
+
+{Warnings list if any}
+
+Continuing to verification...
+```
+
+---
+
+## Standard Verification
+
 ```
 Task(
   prompt="Verify phase {phase_number} goal achievement.
@@ -499,9 +598,31 @@ Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task bloc
 </context_efficiency>
 
 <failure_handling>
+**Failure classification:**
+
+- **Transient failures** (API timeout, rate limit 429, network error):
+  - Auto-retry up to 2 times with exponential backoff (1s, 2s, 4s delays)
+  - If retry succeeds: continue execution
+  - If retry fails after 2 attempts: classify as permanent
+
+- **Permanent failures** (logic error, missing file, validation failure):
+  - Stop immediately, do not retry
+  - Report to user with error details
+  - Mark plan as failed
+
+**Dependency-aware failure handling:**
+
+1. After each wave completes, collect failed plan IDs
+2. Before starting next wave, check each plan's `depends_on`:
+   - If depends_on includes any failed plan: mark as **blocked** (skip execution)
+   - If depends_on is clear: execute normally
+3. Track blocked plans in summary output
+
+**Specific scenarios:**
+
 - **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not EZ. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
 - **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
-- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
+- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents are **blocked** → report blocked plans, user chooses attempt remaining or skip
 - **All agents in wave fail:** Systemic issue → stop, report for investigation
 - **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
 </failure_handling>

package/ez-agents/workflows/help.md

@@ -9,22 +9,29 @@ Display the complete EZ Agents command reference. Output ONLY the reference cont
 
 ## Quick Start
 
-1. `/ez:new-project` - Initialize project (includes research, requirements, roadmap)
-2. `/ez:plan-phase 1` - Create detailed plan for first phase
-3. `/ez:execute-phase 1` - Execute the phase
+### Lean Agile Flow (Recommended)
+1. `/ez:new-project` - Initialize project (requirements + roadmap)
+2. `/ez:run-phase 1` - Run all phases iteratively with pause points
+3. `/ez:audit-milestone` - Verify all requirements met
+4. `/ez:complete-milestone` - Archive and tag release
+
+### Manual Control Flow
+1. `/ez:new-project` - Initialize project
+2. `/ez:discuss-phase 1` - Optional: clarify approach
+3. `/ez:plan-phase 1` - Create task breakdown
+4. `/ez:execute-phase 1` - Build the plan
+5. `/ez:verify-work 1` - Test it works
 
-## Staying Updated
-
-EZ Agents evolves fast. Update periodically:
+## Core Workflow
 
-```bash
-npx ez-agents@latest
+```
+/ez:new-project → /ez:run-phase → /ez:audit-milestone → /ez:complete-milestone
 ```
 
-## Core Workflow
+Or with manual control:
 
 ```
-/ez:new-project → /ez:plan-phase → /ez:execute-phase → repeat
+/ez:new-project → /ez:discuss-phase → /ez:plan-phase → /ez:execute-phase → /ez:verify-work → repeat
 ```
 
 ### Project Initialization
@@ -58,6 +65,31 @@ Map an existing codebase for brownfield projects.
 
 Usage: `/ez:map-codebase`
 
+### Iterative Execution (NEW!)
+
+**`/ez:run-phase [start-phase]`**
+**NEW!** Run all phases iteratively with pause points for approval.
+
+Execute all phases from a starting point: discuss → plan → execute → verify, with user approval between each step. Auto-advances to next phase after completion.
+
+- **Pause points** (unless `--yolo`):
+  - After discuss: "Continue to plan?"
+  - After plan: "Continue to execute?"
+  - After execute: "Continue to verify?"
+  - After verify: "Continue to next phase?"
+- **Auto-tracks progress** in STATE.md and ROADMAP.md
+- **Resume support**: Stop anytime, resume with `/ez:run-phase [N]`
+
+**Flags:**
+- `--no-discuss` — Skip discuss-phase for all phases
+- `--no-verify` — Skip verify-work for all phases
+- `--yolo` — No pause points, fully autonomous (use at own risk)
+
+Usage: `/ez:run-phase` (start from first incomplete phase)
+Usage: `/ez:run-phase 1` (start from phase 1)
+Usage: `/ez:run-phase 2 --no-discuss` (skip discussion)
+Usage: `/ez:run-phase 1 --yolo` (fully autonomous)
+
 ### Phase Planning
 
 **`/ez:discuss-phase <number>`**
@@ -72,25 +104,6 @@ Usage: `/ez:discuss-phase 2`
 Usage: `/ez:discuss-phase 2 --batch`
 Usage: `/ez:discuss-phase 2 --batch=3`
 
-**`/ez:research-phase <number>`**
-Comprehensive ecosystem research for niche/complex domains.
-
-- Discovers standard stack, architecture patterns, pitfalls
-- Creates RESEARCH.md with "how experts build this" knowledge
-- Use for 3D, games, audio, shaders, ML, and other specialized domains
-- Goes beyond "which library" to ecosystem knowledge
-
-Usage: `/ez:research-phase 3`
-
-**`/ez:list-phase-assumptions <number>`**
-See what Claude is planning to do before it starts.
-
-- Shows Claude's intended approach for a phase
-- Lets you course-correct if Claude misunderstood your vision
-- No files created - conversational output only
-
-Usage: `/ez:list-phase-assumptions 3`
-
 **`/ez:plan-phase <number>`**
 Create detailed execution plan for a specific phase.
 
@@ -131,38 +144,6 @@ Use when you know exactly what to do and the task is small enough to not need re
 Usage: `/ez:quick`
 Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
 
-### Roadmap Management
-
-**`/ez:add-phase <description>`**
-Add new phase to end of current milestone.
-
-- Appends to ROADMAP.md
-- Uses next sequential number
-- Updates phase directory structure
-
-Usage: `/ez:add-phase "Add admin dashboard"`
-
-**`/ez:insert-phase <after> <description>`**
-Insert urgent work as decimal phase between existing phases.
-
-- Creates intermediate phase (e.g., 7.1 between 7 and 8)
-- Useful for discovered work that must happen mid-milestone
-- Maintains phase ordering
-
-Usage: `/ez:insert-phase 7 "Fix critical auth bug"`
-Result: Creates Phase 7.1
-
-**`/ez:remove-phase <number>`**
-Remove a future phase and renumber subsequent phases.
-
-- Deletes phase directory and all references
-- Renumbers all subsequent phases to close the gap
-- Only works on future (unstarted) phases
-- Git commit preserves historical record
-
-Usage: `/ez:remove-phase 17`
-Result: Phase 17 deleted, phases 18-20 become 17-19
-
 ### Milestone Management
 
 **`/ez:new-milestone <name>`**
@@ -212,63 +193,6 @@ Resume work from previous session with full context restoration.
 
 Usage: `/ez:resume-work`
 
-**`/ez:pause-work`**
-Create context handoff when pausing work mid-phase.
-
-- Creates .continue-here file with current state
-- Updates STATE.md session continuity section
-- Captures in-progress work context
-
-Usage: `/ez:pause-work`
-
-**`/ez:resume`**
-Resume from last session or navigate session chain (Phase 18+).
-
-- Loads most recent session from `.planning/sessions/`
-- Shows formatted summary with model, phase, plan, duration
-- Displays incomplete items, decisions, file changes
-- Offers options: Continue, Show transcript, Export, Navigate chain, Start fresh
-- Supports navigation: `--previous`, `--next`, `--chain`
-
-Usage: `/ez:resume`
-Usage: `/ez:resume session-20260319-143052`
-Usage: `/ez:resume --previous`
-
-**`/ez:export-session`**
-Export session for model handoff or archival.
-
-- Exports last session by default (or specified session)
-- Supports markdown (human-readable) and JSON formats
-- Includes: summary, tasks, decisions, file changes, open questions, blockers
-- Output to `.planning/sessions/export-{session_id}.{ext}`
-
-Usage: `/ez:export-session`
-Usage: `/ez:export-session session-20260319-143052 --format json`
-Usage: `/ez:export-session --output /path/to/file.md`
-
-**`/ez:import-session`**
-Import session from exported file.
-
-- Validates session structure and chain integrity
-- Supports model-specific adapters (claude, qwen, openai, kimi)
-- Creates new session with imported context
-- Offers to resume imported session
-
-Usage: `/ez:import-session /path/to/session.json`
-Usage: `/ez:import-session session.json --source-model claude`
-
-**`/ez:list-sessions`**
-List all sessions with metadata and disk usage.
-
-- Shows: session_id, started_at, ended_at, model, phase, plan, status
-- Sorted by date (newest first)
-- Displays disk usage summary
-- Supports `--limit N` and `--json` flags
-
-Usage: `/ez:list-sessions`
-Usage: `/ez:list-sessions --limit 10`
-Usage: `/ez:list-sessions --json`
-
 ### Debugging
 
 **`/ez:debug [issue description]`**
@@ -283,32 +207,6 @@ Systematic debugging with persistent state across context resets.
 Usage: `/ez:debug "login button doesn't work"`
 Usage: `/ez:debug` (resume active session)
 
-### Todo Management
-
-**`/ez:add-todo [description]`**
-Capture idea or task as todo from current conversation.
-
-- Extracts context from conversation (or uses provided description)
-- Creates structured todo file in `.planning/todos/pending/`
-- Infers area from file paths for grouping
-- Checks for duplicates before creating
-- Updates STATE.md todo count
-
-Usage: `/ez:add-todo` (infers from conversation)
-Usage: `/ez:add-todo Add auth token refresh`
-
-**`/ez:check-todos [area]`**
-List pending todos and select one to work on.
-
-- Lists all pending todos with title, area, age
-- Optional area filter (e.g., `/ez:check-todos api`)
-- Loads full context for selected todo
-- Routes to appropriate action (work now, add to phase, brainstorm)
-- Moves todo to done/ when work begins
-
-Usage: `/ez:check-todos`
-Usage: `/ez:check-todos api`
-
 ### User Acceptance Testing
 
 **`/ez:verify-work [phase]`**
@@ -333,16 +231,6 @@ Audit milestone completion against original intent.
 
 Usage: `/ez:audit-milestone`
 
-**`/ez:plan-milestone-gaps`**
-Create phases to close gaps identified by audit.
-
-- Reads MILESTONE-AUDIT.md and groups gaps into phases
-- Prioritizes by requirement priority (must/should/nice)
-- Adds gap closure phases to ROADMAP.md
-- Ready for `/ez:plan-phase` on new phases
-
-Usage: `/ez:plan-milestone-gaps`
-
 ### Configuration
 
 **`/ez:settings`**
@@ -354,27 +242,8 @@ Configure workflow toggles and model profile interactively.
 
 Usage: `/ez:settings`
 
-**`/ez:set-profile <profile>`**
-Quick switch model profile for EZ agents.
-
-- `quality` — Opus everywhere except verification
-- `balanced` — Opus for planning, Sonnet for execution (default)
-- `budget` — Sonnet for writing, Haiku for research/verification
-
-Usage: `/ez:set-profile budget`
-
 ### Utility Commands
 
-**`/ez:cleanup`**
-Archive accumulated phase directories from completed milestones.
-
-- Identifies phases from completed milestones still in `.planning/phases/`
-- Shows dry-run summary before moving anything
-- Moves phase dirs to `.planning/milestones/v{X.Y}-phases/`
-- Use after multiple milestones to reduce `.planning/phases/` clutter
-
-Usage: `/ez:cleanup`
-
 **`/ez:help`**
 Show this command reference.
 
@@ -389,14 +258,6 @@ Update EZ Agents to latest version with changelog preview.
 
 Usage: `/ez:update`
 
-**`/ez:join-discord`**
-Join the EZ Agents Discord community.
-
-- Get help, share what you're building, stay updated
-- Connect with other EZ Agents users
-
-Usage: `/ez:join-discord`
-
 ## Files & Structure
 
 ```