@howlil/ez-agents 3.4.2 → 4.0.0

package/README.md

@@ -1,462 +1,735 @@
-<div align="center">
-
-# EZ Agents
-
-**Turn AI coding assistants into reliable development teammates.**
-
-[![npm](https://img.shields.io/npm/v/@howlil/ez-agents?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@howlil/ez-agents)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/howlil/ez-agents?style=for-the-badge&logo=github)](https://github.com/howlil/ez-agents/stargazers)
-
-```bash
-npm i -g @howlil/ez-agents@latest
-```
-
-**Works with:** Claude Code · OpenCode · Gemini CLI · Codex · Copilot · Qwen · Kimi
-
-[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Commands](#commands) · [Setup](#setup) · [Docs](docs/)
-
-</div>
-
----
-
-> **What is this?** EZ Agents adds structure to AI coding. Instead of asking Claude to "build a login system" and hoping for the best, you get a repeatable workflow: plan it out, build it in pieces, verify it works. Every change is committed with context, so you (or your team) can pick up where the AI left off.
-
----
-
-## Why EZ Agents Exists
-
-AI coding tools are great at writing code. But real development work needs more than that:
-
-- **Context gets lost** between sessions
-- **No one reviews** whether the code actually fits the plan
-- **Important decisions** about architecture happen implicitly
-- **Testing is an afterthought**
-
-EZ Agents fixes this by adding a lightweight orchestration layer. Think of it as a project manager for your AI assistants.
-
----
-
-## Quick Start
-
-### 1. Install
-
-```bash
-npm i -g @howlil/ez-agents@latest
-```
-
-### 2. Setup for Your AI Tool
-
-```bash
-# For Claude Code
-ez-agents --claude --global
-
-# For OpenCode
-ez-agents --opencode --global
-
-# For Gemini CLI
-ez-agents --gemini --global
-
-# See all options
-ez-agents --help
-```
-
-### 3. Start a Project
-
-```bash
-# In your project directory
-/ez:new-project
-```
-
-You'll answer a few questions about what you're building, then EZ Agents generates a roadmap. From there, you work through phases:
-
-```bash
-/ez:discuss-phase 1    # Lock in how you want it built
-/ez:plan-phase 1       # Break it into specific tasks
-/ez:execute-phase 1    # Build it (one task per commit)
-/ez:verify-work 1      # Check it actually works
-```
-
----
-
-## How It Works
-
-### The Workflow
-
-```
-┌─────────────────┐
-│  Start Project  │
-│  /ez:new-project│
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────────────────────────────────────┐
-│  For Each Phase:                                │
-│                                                 │
-│  1. /ez:discuss-phase  → Decide HOW to build   │
-│  2. /ez:plan-phase     → Break into tasks      │
-│  3. /ez:execute-phase  → Build (one commit/task)│
-│  4. /ez:verify-work    → Test it works         │
-└─────────────────────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│  /ez:audit-milestone    │
-│  /ez:complete-milestone │
-└─────────────────────────┘
-```
-
-### Parallel Execution with Git Commits
-
-Setiap task dijalankan secara paralel (jika tidak ada dependensi), dengan fresh context dan atomic commit:
-
-```
-Phase 1: Foundation
-│
-├─ Wave 1 (Parallel) ───────────────────────────┐
-│  ┌─────────────────┐  ┌─────────────────┐     │
-│  │ Task 1.1:       │  │ Task 1.2:       │     │
-│  │ Database Schema │  │ Next.js Setup   │     │
-│  │                 │  │                 │     │
-│  │ Fresh 200K ctx  │  │ Fresh 200K ctx  │     │
-│  │     ↓           │  │     ↓           │     │
-│  │ git commit      │  │ git commit      │     │
-│  │ "feat: schema"  │  │ "feat: setup"   │     │
-│  └─────────────────┘  └─────────────────┘     │
-└────────────────────────────────────────────────┘
-         │
-         ▼
-├─ Wave 2 (Depends on Wave 1) ──────────────────┐
-│  ┌─────────────────┐                          │
-│  │ Task 1.3:       │                          │
-│  │ Auth Endpoints  │  ← Needs schema + setup  │
-│  │                 │                          │
-│  │ Fresh 200K ctx  │                          │
-│  │     ↓           │                          │
-│  │ git commit      │                          │
-│  │ "feat: auth"    │                          │
-│  └─────────────────┘                          │
-└────────────────────────────────────────────────┘
-```
-
-**Keuntungan:**
-- **Fresh context per task** — AI tidak kehilangan context karena window penuh
-- **Atomic commits** — Setiap commit = satu task, mudah di-revert jika ada masalah
-- **Parallel execution** — Task independen jalan barengan, lebih cepat
-- **Clean git history** — Commit message deskriptif, jelas apa yang berubah
-
-### What Makes It Different
-
-| Problem | Without EZ Agents | With EZ Agents |
-|---------|------------------|----------------|
-| **Lost context** | "What was I working on again?" | STATE.md tracks decisions, blockers, next steps |
-| **Vague plans** | "Build the API" | Specific tasks: "Create POST /users endpoint with validation" |
-| **No verification** | Code written, but does it work? | Each phase has explicit verification criteria |
-| **Messy git history** | "WIP", "fix", "asdf" | One commit per task, meaningful messages |
-| **Scope creep** | Features added ad-hoc | ROADMAP.md tracks what's in/out of scope |
-
----
-
-## Features
-
-### Core
-
-- **Multi-Model Support** — Use Qwen, Kimi, OpenAI, or Anthropic. Mix providers per task.
-- **Wave Execution** — Independent tasks run in parallel; dependent tasks wait their turn
-- **Context Engineering** — PROJECT.md, STATE.md, SUMMARY.md preserve decisions across sessions
-- **Atomic Commits** — Each task gets its own commit with context about what changed and why
-- **Milestone Tracking** — Version releases with requirements audit and git tagging
-
-### Built for Production
-
-- **Security** — Command injection prevention, path validation, audit logging
-- **Cross-Platform** — Pure JavaScript. Works on Windows, macOS, Linux (no Unix dependencies)
-- **Error Handling** — Retry logic with backoff, circuit breaker for failing operations
-- **Git Safety** — Atomic commits, branch automation, merge strategies
-
-### For Existing Codebases
-
-```bash
-# Analyze what you have
-/ez:map-codebase
-
-# Then plan what to add
-/ez:new-project
-```
-
-Parallel agents analyze your stack, architecture, conventions, and pain points. The output: structured docs that inform the roadmap.
-
----
-
-## Commands
-
-### Starting Out
-
-| Command | What It Does |
-|---------|-------------|
-| `/ez:new-project` | Initialize: answer questions, get research, requirements, and roadmap |
-| `/ez:map-codebase` | Analyze existing codebase (before `/ez:new-project`) |
-| `/ez:quick` | Small task without full phase workflow (bug fixes, config changes) |
-
-### Phase Workflow
-
-| Command | What It Does |
-|---------|-------------|
-| `/ez:discuss-phase [N]` | Clarify implementation approach before planning |
-| `/ez:plan-phase [N]` | Research domain, create task breakdown, define verification |
-| `/ez:execute-phase [N]` | Build the plan (parallel waves, one commit per task) |
-| `/ez:verify-work [N]` | Manual testing with auto-diagnosis of failures |
-
-### Managing Scope
-
-| Command | What It Does |
-|---------|-------------|
-| `/ez:add-phase` | Append new phase to roadmap |
-| `/ez:insert-phase [N]` | Insert urgent work between existing phases |
-| `/ez:remove-phase [N]` | Remove a phase and renumber |
-| `/ez:progress` | See where you are and what's next |
-
-### Wrapping Up
-
-| Command | What It Does |
-|---------|-------------|
-| `/ez:audit-milestone` | Verify all requirements are met |
-| `/ez:complete-milestone` | Archive milestone, create git tag |
-| `/ez:new-milestone` | Start next version cycle |
-
-### Utilities
-
-| Command | What It Does |
-|---------|-------------|
-| `/ez:resume-work` | Restore context from last session |
-| `/ez:settings` | Configure workflow, model profile, git strategy |
-| `/ez:update` | Update EZ Agents (with changelog preview) |
-| `/ez:help` | Show all commands |
-
----
-
-## Setup
-
-### Prerequisites
-
-- Node.js >= 16.7.0
-- One of: Claude Code, OpenCode, Gemini CLI, Codex, Copilot, Qwen Code, Kimi Code
-
-### Installation
-
-```bash
-npm i -g @howlil/ez-agents@latest
-ez-agents --claude --global
-```
-
-### Updating
-
-```bash
-npm update -g @howlil/ez-agents
-```
-
-**Development Install** (for contributing)
-
-```bash
-git clone https://github.com/howlil/ez-agents.git
-cd ez-agents
-npm install -g .
-ez-agents --claude --local
-```
-
----
-
-## Configuration
-
-EZ Agents stores settings in `.planning/config.json`. You configure this during `/ez:new-project` or adjust later with `/ez:settings`.
-
-### Key Settings
-
-| Setting | Options | Default | What It Does |
-|---------|---------|---------|-------------|
-| `mode` | `interactive`, `yolo` | `interactive` | `yolo` skips confirmation prompts |
-| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Controls which model tier each agent uses |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | How many phases (3-5, 5-8, or 8-12) |
-
-### Model Profiles
-
-| Agent | `quality` | `balanced` | `budget` |
-|-------|-----------|------------|----------|
-| Planner | Opus | Opus | Sonnet |
-| Executor | Opus | Sonnet | Sonnet |
-| Researcher | Opus | Sonnet | Haiku |
-| Verifier | Sonnet | Sonnet | Haiku |
-
-**When to use each:**
-- **quality** — Critical work, complex decisions, you have quota
-- **balanced** — Day-to-day development (the default for a reason)
-- **budget** — High-volume work, familiar domains, prototyping
-
-### Multi-Provider Setup
-
-Different providers for different tasks:
-
-```json
-{
-  "provider": {
-    "default": "alibaba",
-    "anthropic": {
-      "api_key": "env:ANTHROPIC_API_KEY"
-    },
-    "alibaba": {
-      "api_key": "env:DASHSCOPE_API_KEY"
-    }
-  },
-  "agent_overrides": {
-    "ez-planner": { "provider": "alibaba", "model": "qwen-max" },
-    "ez-executor": { "provider": "anthropic", "model": "sonnet" }
-  }
-}
-```
-
----
-
-## Project Structure
-
-After running `/ez:new-project`, you'll have:
-
-```
-.planning/
-  PROJECT.md           # What you're building and why
-  REQUIREMENTS.md      # Scoped requirements with IDs
-  ROADMAP.md           # Phase breakdown with status
-  STATE.md             # Current decisions, blockers, next steps
-  config.json          # Your configuration
-  phases/
-    01-phase-name/
-      01-01-PLAN.md    # Tasks to execute
-      01-01-SUMMARY.md # What was built and why
-      CONTEXT.md       # Your implementation preferences
-      RESEARCH.md      # Domain research
-      VERIFICATION.md  # Test results
-```
-
-**Note:** You can add `.planning/` to `.gitignore` if you don't want planning docs in your repo. Set `commit_docs: false` in `/ez:settings`.
-
----
-
-## Example: Building a Task App
-
-Let's say you want to build "a task management app with team collaboration."
-
-### 1. Initialize
-
-```bash
-/ez:new-project
-```
-
-You answer questions:
-- Tech stack? → "Next.js + PostgreSQL"
-- Auth method? → "Email + OAuth (Google, GitHub)"
-- First milestone? → "MVP: user accounts, create/edit tasks, share with team"
-
-EZ Agents generates research, requirements, and a roadmap with ~6 phases.
-
-### 2. Phase 1: Foundation
-
-```bash
-/ez:discuss-phase 1
-```
-
-You clarify: "Use Next.js App Router, Prisma for DB, next-auth for OAuth."
-
-```bash
-/ez:plan-phase 1
-```
-
-Research runs (auth patterns, Prisma schema design). Plan is created:
-- Task 1: Database schema (users, tasks, teams)
-- Task 2: Next.js setup with next-auth
-- Task 3: User model and auth endpoints
-
-```bash
-/ez:execute-phase 1
-```
-
-Three tasks, three commits. Each task gets fresh context.
-
-```bash
-/ez:verify-work 1
-```
-
-You test: Can register? Can login? Can connect to DB? All pass.
-
-### 3. Repeat for Each Phase
-
-```bash
-/ez:discuss-phase 2
-/ez:plan-phase 2
-/ez:execute-phase 2
-/ez:verify-work 2
-```
-
-### 4. Complete Milestone
-
-```bash
-/ez:audit-milestone     # Checks all requirements are met
-/ez:complete-milestone  # Archives, tags v1.0
-```
-
----
-
-## Documentation
-
-| Doc | What's Inside |
-|-----|---------------|
-| [User Guide](docs/USER-GUIDE.md) | Full command reference, workflows, troubleshooting |
-| [Workflows](docs/WORKFLOWS.md) | Complete workflow diagrams for all use cases |
-| [Provider Behaviors](docs/PROVIDER-BEHAVIORS.md) | Differences between Claude, OpenCode, Gemini, etc. |
-| [Qwen Code Install](docs/QWEN-CODE-INSTALL.md) | Fix for Qwen Code CLI installation issues |
-
----
-
-## Contributing
-
-Contributions welcome! A few guidelines:
-
-1. **Test your changes** — Run `npm test` before submitting
-2. **Keep it cross-platform** — No Unix-specific commands (use `fs-utils.cjs`)
-3. **Document behavior** — Update USER-GUIDE.md for new commands
-4. **Respect the workflow** — EZ Agents is about structure; don't break existing patterns
-
-### Development Setup
-
-```bash
-git clone https://github.com/howlil/ez-agents.git
-cd ez-agents
-npm install
-npm run build:hooks
-npm link
-```
-
-### Running Tests
-
-```bash
-npm test              # Run all tests
-npm run test:coverage # With coverage report
-```
-
----
-
-## Acknowledgments
-
-EZ Agents is a fork of the original project by [TÂCHES](https://github.com/glittercowboy). This fork adds multi-model support (Qwen, Kimi, OpenAI), enterprise-grade security, and cross-platform reliability. Not affiliated with the upstream repository.
-
----
-
-## License
-
-MIT — see [LICENSE](LICENSE)
-
----
-
-## Getting Help
-
-- **Issues:** [GitHub Issues](https://github.com/howlil/ez-agents/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/howlil/ez-agents/discussions)
-- **npm:** [@howlil/ez-agents](https://www.npmjs.com/package/@howlil/ez-agents)
+<div align="center">
+
+# EZ Agents
+
+**Build any app — from MVP to enterprise — with coordinated AI agents.**
+
+[![CI Pipeline](https://github.com/howlil/ez-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/howlil/ez-agents/actions/workflows/ci.yml)
+[![Tests](https://github.com/howlil/ez-agents/actions/workflows/test.yml/badge.svg)](https://github.com/howlil/ez-agents/actions/workflows/test.yml)
+[![CodeQL](https://github.com/howlil/ez-agents/actions/workflows/codeql.yml/badge.svg)](https://github.com/howlil/ez-agents/actions/workflows/codeql.yml)
+[![npm](https://img.shields.io/npm/v/@howlil/ez-agents?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@howlil/ez-agents)
+[![npm](https://img.shields.io/npm/dm/@howlil/ez-agents.svg)](https://npmjs.com/package/@howlil/ez-agents)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/howlil/ez-agents?style=for-the-badge&logo=github)](https://github.com/howlil/ez-agents/stargazers)
+
+```bash
+npm i -g @howlil/ez-agents@latest
+```
+
+**Works with:** Claude Code · OpenCode · Gemini CLI · Codex · Copilot · Qwen · Kimi
+
+[Quick Start](#quick-start) · [Lean Workflow](#lean-agile-workflow-v360) · [Commands](#commands) · [Setup](#setup) · [Docs](docs/) · [Lean Guide](docs/LEAN-GUIDE.md)
+
+</div>
+
+---
+
+> **What is this?** EZ Agents is an AI App Builder. An Orchestrator (Chief Strategist) takes your project brief, decomposes it into a dependency-aware task graph, delegates work to Specialist Agents in parallel, enforces quality gates, and delivers implementation-ready output — code, tests, docs, and release artifacts. Works for new projects, existing codebases, rapid MVPs, and enterprise-scale products.
+
+---
+
+## Why EZ Agents Exists
+
+AI agents are capable — but capability without coordination produces chaos. Real software delivery requires:
+
+- **Coordination** — agents need to share state and hand off work cleanly
+- **Context discipline** — decisions, contracts, and requirements must persist across sessions
+- **Quality gates** — code that passes tests is not the same as code that ships safely
+- **Structure without ceremony** — the right amount of process for the project size
+
+EZ Agents provides a Chief Strategist Orchestrator that coordinates a pool of Specialist Agents through a 10-phase SDLC workflow — from intake to post-release loop. Stack-agnostic and requirement-driven.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm i -g @howlil/ez-agents@latest
+```
+
+### 2. Setup for Your AI Tool
+
+```bash
+# For Claude Code
+ez-agents --claude --global
+
+# For OpenCode
+ez-agents --opencode --global
+
+# For Gemini CLI
+ez-agents --gemini --global
+
+# See all options
+ez-agents --help
+```
+
+### 3. Start a Project
+
+```bash
+# In your project directory
+/ez:new-project
+```
+
+You'll answer a few questions about what you're building, then EZ Agents generates a roadmap. From there, use the **lean agile flow**:
+
+```bash
+# ⚡ FAST PATH: Single command for all phases (recommended)
+/ez:run-phase 1              # 35-55 min per phase
+/ez:run-phase 1 --yolo       # Fully autonomous, no pauses
+
+# 🎯 MANUAL CONTROL: Per phase
+/ez:discuss-phase 1          # Optional — clarify approach (15 min)
+/ez:plan-phase 1             # Create task breakdown (20 min)
+/ez:execute-phase 1          # Build (one task per commit) (30 min)
+/ez:verify-work 1            # Test it works (10 min)
+```
+
+### 4. Complete Milestone
+
+```bash
+/ez:audit-milestone          # Verify all requirements met (10 min)
+/ez:complete-milestone 1.0.0 # Archive and tag release (5 min)
+```
+
+**Total time from idea to MVP: 2-3 days** 🚀
+
+---
+
+## How It Works
+
+### System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           EZ AGENTS ORCHESTRATION SYSTEM                     │
+│                                                                              │
+│  A multi-agent coordination system for building software with AI agents      │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                                    USER
+                                      │
+                                      ▼
+                          ┌───────────────────────┐
+                          │   ez-chief-strategist │ ◄── Orchestrator
+                          │   (Chief Strategist)  │      (Work classification,
+                          └───────────┬───────────┘       routing, state machine)
+                                      │
+              ┌───────────────────────┼───────────────────────┐
+              │                       │                       │
+              ▼                       ▼                       ▼
+    ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
+    │  Specialist     │   │  Specialist     │   │  Specialist     │
+    │  Agents         │   │  Agents         │   │  Agents         │
+    │                 │   │                 │   │                 │
+    │ • ez-planner    │   │ • ez-executor   │   │ • ez-verifier   │
+    │ • ez-researcher │   │ • ez-debugger   │   │ • ez-auditor    │
+    │ • ez-mapper     │   │ • ez-qa-agent   │   │ • ez-roadmapper │
+    │ • ez-architect  │   │ • ez-devops     │   │                 │
+    └─────────────────┘   └─────────────────┘   └─────────────────┘
+```
+
+### The Phase Workflow
+
+```
+┌─────────────────┐
+│  Start Project  │
+│  /ez:new-project│
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────┐
+│  For Each Phase:                                │
+│                                                 │
+│  1. /ez:discuss-phase  → Decide HOW to build   │
+│  2. /ez:plan-phase     → Break into tasks      │
+│  3. /ez:execute-phase  → Build (one commit/task)│
+│  4. /ez:verify-work    → Test it works         │
+└─────────────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────┐
+│  /ez:audit-milestone    │
+│  /ez:complete-milestone │
+└─────────────────────────┘
+```
+
+### Chief Strategist State Machine
+
+```
+TASK RECEIVED
+     │
+     ▼
+┌─────────────┐
+│ 1. TRIAGE   │ ──► Classify: feature/bug/refactor/incident
+└──────┬──────┘
+       │
+       ▼
+┌───────────────────┐
+│ 2. RETRIVE_CTX    │ ──► Load project context
+└──────┬────────────┘
+       │
+       ▼
+┌───────────────────┐
+│ 3. PROPOSE_ACTION │ ──► Select agent + skills
+└──────┬────────────┘
+       │
+       ▼
+┌───────────────────┐
+│ 4. POLICY_CHECK   │ ──► Validate constraints
+└──────┬────────────┘
+       │
+       ▼
+┌───────────────────┐
+│ 5. EXECUTE        │ ──► Route to specialist agent
+└──────┬────────────┘
+       │
+       ▼
+┌───────────────────┐
+│ 6. VERIFY         │ ──► Validate results
+└──────┬────────────┘
+       │
+       ▼
+┌───────────────────┐
+│ 7. COMPLETE       │ ──► Log audit trail
+└───────────────────┘
+```
+
+### Smart Orchestration
+
+Core commands automatically invoke helper commands based on context — so you don't have to remember to run them. All auto-invocations are visible with an `[auto]` prefix.
+
+| Command | Auto Pre | Auto Post | Conditional |
+|---------|----------|-----------|-------------|
+| `/ez:execute-phase` | health check | verify-work | discuss-phase (medium/enterprise, no CONTEXT.md) · add-todo (scope creep) |
+| `/ez:plan-phase` | — | — | discuss-phase (phase touches auth/DB/payment/security area) |
+| `/ez:release medium` | — | — | verify-work |
+| `/ez:release enterprise` | — | — | verify-work → audit-milestone → arch-review |
+| `/ez:progress` | health check (silent) | — | — |
+
+**Override flags:**
+
+| Flag | Effect |
+|------|--------|
+| `--no-auto` | Disable all auto-invocations for that run |
+| `--verbose` | Show detail for every auto-invocation step |
+| `--skip-discussion` | Skip only the auto discuss-phase trigger |
+
+Disable globally: set `"smart_orchestration": { "enabled": false }` in `.planning/config.json`.
+
+### Wave-Based Parallel Execution
+
+Tasks are grouped into waves based on dependencies. Independent tasks run in parallel; dependent tasks wait for prerequisites.
+
+```
+Phase 1: Foundation
+│
+├─ Wave 1 (Parallel) ───────────────────────────┐
+│  ┌─────────────────┐  ┌─────────────────┐     │
+│  │ Task 1.1:       │  │ Task 1.2:       │     │
+│  │ Database Schema │  │ Next.js Setup   │     │
+│  │                 │  │                 │     │
+│  │ Fresh 200K ctx  │  │ Fresh 200K ctx  │     │
+│  │     ↓           │  │     ↓           │     │
+│  │ git commit      │  │ git commit      │     │
+│  │ "feat: schema"  │  │ "feat: setup"   │     │
+│  └─────────────────┘  └─────────────────┘     │
+└────────────────────────────────────────────────┘
+         │
+         ▼
+├─ Wave 2 (Depends on Wave 1) ──────────────────┐
+│  ┌─────────────────┐                          │
+│  │ Task 1.3:       │                          │
+│  │ Auth Endpoints  │  ← Needs schema + setup  │
+│  │                 │                          │
+│  │ Fresh 200K ctx  │                          │
+│  │     ↓           │                          │
+│  │ git commit      │                          │
+│  │ "feat: auth"    │                          │
+│  └─────────────────┘                          │
+└────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- **Fresh context per task** — AI doesn't lose context due to window limits
+- **Atomic commits** — Each task = one commit, easy to revert if issues arise
+- **Parallel execution** — Independent tasks run together, faster delivery
+- **Clean git history** — Descriptive commit messages, clear what changed
+
+### What Makes It Different
+
+| Problem | Without EZ Agents | With EZ Agents |
+|---------|------------------|----------------|
+| **Lost context** | "What was I working on again?" | STATE.md tracks decisions, blockers, next steps |
+| **Vague plans** | "Build the API" | Specific tasks: "Create POST /users endpoint with validation" |
+| **No verification** | Code written, but does it work? | Each phase has explicit verification criteria |
+| **Messy git history** | "WIP", "fix", "asdf" | One commit per task, meaningful messages |
+| **Scope creep** | Features added ad-hoc | ROADMAP.md tracks what's in/out of scope |
+
+---
+
+## Features
+
+### Core
+
+- **Multi-Model Support** — Use Qwen, Kimi, OpenAI, or Anthropic. Mix providers per task.
+- **Wave Execution** — Independent tasks run in parallel; dependent tasks wait their turn
+- **Context Engineering** — PROJECT.md, STATE.md, SUMMARY.md preserve decisions across sessions
+- **Atomic Commits** — Each task gets its own commit with context about what changed and why
+- **Milestone Tracking** — Version releases with requirements audit and git tagging
+- **Smart Orchestration** — Core commands auto-invoke helpers (health, verify-work, discuss-phase) based on context. All visible with `[auto]` prefix. Override with `--no-auto`.
+
+### Built for Production
+
+- **Security** — Command injection prevention, path validation, audit logging
+- **Cross-Platform** — Pure JavaScript. Works on Windows, macOS, Linux (no Unix dependencies)
+- **Error Handling** — Retry logic with backoff, circuit breaker for failing operations
+- **Git Safety** — Atomic commits, branch automation, merge strategies
+
+### CI/CD Pipeline
+
+EZ Agents includes comprehensive CI/CD automation for enterprise-grade quality:
+
+**Pipeline Stages:**
+```
+Push → Lint → Test → Security Scan → Build → Deploy Staging → Deploy Production
+```
+
+**Security Scanning:**
+- **CodeQL** - Semantic code analysis for vulnerabilities (SAST)
+- **Semgrep** - Fast pattern-based security scanning
+- **npm audit** - Dependency vulnerability detection
+- **Dependabot** - Automated dependency updates
+
+**Environment Promotion:**
+- **Develop branch** → Auto-deploy to staging
+- **Main branch** → Deploy to production (requires manual approval)
+- **Health checks** - Post-deployment validation
+- **Auto-rollback** - Automatic rollback on health check failure
+
+**Coverage Enforcement:**
+- Minimum 70% code coverage threshold
+- Coverage reports uploaded as artifacts
+- Optional Codecov integration
+
+**View Pipeline Status:**
+- [CI Pipeline](https://github.com/howlil/ez-agents/actions/workflows/ci.yml)
+- [Tests](https://github.com/howlil/ez-agents/actions/workflows/test.yml)
+- [CodeQL](https://github.com/howlil/ez-agents/actions/workflows/codeql.yml)
+- [Security Scan](https://github.com/howlil/ez-agents/actions/workflows/security-scan.yml)
+
+### For Existing Codebases
+
+```bash
+# Analyze what you have
+/ez:map-codebase
+
+# Then plan what to add
+/ez:new-project
+```
+
+Parallel agents analyze your stack, architecture, conventions, and pain points. The output: structured docs that inform the roadmap.
+
+---
+
+## Lean Agile Workflow (v3.6.0)
+
+### 🚀 Fast Path (Recommended)
+
+Single command to run all phases iteratively:
+
+```bash
+/ez:run-phase 1              # Start from first incomplete phase
+/ez:run-phase 2              # Start from specific phase
+/ez:run-phase 1 --yolo       # Fully autonomous (no pauses)
+/ez:run-phase 1 --no-discuss # Skip discussion (if CONTEXT.md exists)
+```
+
+**What it does:**
+1. Discovers phases from ROADMAP.md
+2. For each phase: discuss → plan → execute → verify
+3. Pause points for approval (unless --yolo)
+4. Auto-advances to next phase
+5. Updates STATE.md and ROADMAP.md automatically
+
+**Time:** 35-55 minutes per phase
+
+### 🎯 Manual Control
+
+Step-by-step control for each phase:
+
+```bash
+# Step 1: Discuss (Optional)
+/ez:discuss-phase 1
+# Creates: CONTEXT.md (vision, decisions, boundaries)
+
+# Step 2: Plan
+/ez:plan-phase 1
+# Creates: 01-01-PLAN.md (tasks with verification criteria)
+
+# Step 3: Execute
+/ez:execute-phase 1
+# Creates: 01-01-SUMMARY.md + git commits
+
+# Step 4: Verify
+/ez:verify-work 1
+# Creates: UAT results, diagnoses failures
+```
+
+**Time:** 75-105 minutes per phase
+
+### 📁 Documentation Strategy
+
+**Essential Files (4 only):**
+
+| File | Purpose | Max Lines |
+|------|---------|-----------|
+| `STATE.md` | Single source of truth | 200 |
+| `ROADMAP.md` | Phase structure & progress | 300 |
+| `REQUIREMENTS.md` | What to build (MoSCoW) | 500 |
+| `SUMMARY.md` | What was built | 50 |
+
+**Deprecated (No longer required):**
+- ❌ CONTEXT.md → Merge decisions into STATE.md
+- ❌ RESEARCH.md → Inline research in PLAN.md
+- ❌ VERIFICATION.md → Inline in SUMMARY.md
+- ❌ UAT.md → Merge into SUMMARY.md
+- ❌ DISCUSSION.md → Removed entirely
+
+### 🔄 Git Strategy
+
+**One commit per plan** (not per task):
+
+```bash
+# Good
+git commit -m "Phase 1 Plan 1: User authentication"
+git commit -m "Phase 1 complete: Foundation"
+
+# Avoid (too granular)
+git commit -m "feat: add login endpoint"
+git commit -m "feat: add jwt middleware"
+git commit -m "feat: add auth tests"
+```
+
+**Result:** 2-3 commits per phase (not 10-20)
+
+---
+
+## Commands
+
+### Core Workflow (Lean Agile)
+
+| Command | What It Does |
+|---------|-------------|
+| `/ez:new-project` | Initialize: answer questions, get requirements and roadmap |
+| `/ez:run-phase [N]` | **NEW!** Run all phases iteratively with pause points. Use `--yolo` for fully autonomous. |
+| `/ez:quick` | Small task without full phase workflow (bug fixes, config changes) |
+
+### Phase Workflow (Manual Control)
+
+| Command | What It Does |
+|---------|-------------|
+| `/ez:discuss-phase [N]` | Optional — Clarify implementation approach before planning |
+| `/ez:plan-phase [N]` | Create task breakdown with verification criteria |
+| `/ez:execute-phase [N]` | Build the plan (parallel waves, one commit per task) |
+| `/ez:verify-work [N]` | Manual testing with auto-diagnosis of failures |
+
+### Milestone Management
+
+| Command | What It Does |
+|---------|-------------|
+| `/ez:audit-milestone` | Verify all requirements are met |
+| `/ez:complete-milestone` | Archive milestone, create git tag |
+| `/ez:new-milestone` | Start next version cycle |
+
+### Utilities
+
+| Command | What It Does |
+|---------|-------------|
+| `/ez:map-codebase` | Analyze existing codebase (before `/ez:new-project`) |
+| `/ez:progress` | See where you are and what's next |
+| `/ez:resume-work` | Restore context from last session |
+| `/ez:settings` | Configure workflow, model profile, git strategy |
+| `/ez:update` | Update EZ Agents (with changelog preview) |
+| `/ez:help` | Show all commands |
+
+---
+
+## Context Access Commands
+
+EZ Agents provides commands for gathering context from local files and remote URLs during planning phases.
+
+### `ez-tools context read <pattern>`
+
+Read local files using glob patterns.
+
+**Examples:**
+```bash
+node ez-tools.cjs context read "README.md"
+node ez-tools.cjs context read "src/**/*.ts"
+node ez-tools.cjs context read "*.json" "!package-lock.json"
+```
+
+**Supported patterns:**
+- Single files: `README.md`
+- Glob patterns: `src/**/*.ts`
+- Brace expansion: `*.{ts,js}`
+- Negation: `!*.test.ts`
+
+### `ez-tools context fetch <url>`
+
+Fetch content from URL (HTTPS only, requires user confirmation).
+
+**Examples:**
+```bash
+node ez-tools.cjs context fetch https://example.com/spec.md
+node ez-tools.cjs context fetch https://raw.githubusercontent.com/user/repo/main/README.md
+```
+
+**Security:**
+- Only HTTPS URLs allowed
+- User confirmation required before fetching
+- Content scanned for XSS/malware before use
+
+### `ez-tools context request`
+
+Interactive mode for requesting multiple context sources. Enter file patterns or URLs one per line, then press Enter on an empty line to finish.
+
+**Example:**
+```bash
+node ez-tools.cjs context request
+> README.md
+> src/**/*.ts
+> https://example.com/api-docs.md
+> 
+```
+
+---
+
+## Setup
+
+### Prerequisites
+
+- Node.js >= 16.7.0
+- One of: Claude Code, OpenCode, Gemini CLI, Codex, Copilot, Qwen Code, Kimi Code
+
+### Installation
+
+```bash
+npm i -g @howlil/ez-agents@latest
+ez-agents --claude --global
+```
+
+### Updating
+
+```bash
+npm update -g @howlil/ez-agents
+```
+
+**Development Install** (for contributing)
+
+```bash
+git clone https://github.com/howlil/ez-agents.git
+cd ez-agents
+npm install -g .
+ez-agents --claude --local
+```
+
+---
+
+## Configuration
+
+EZ Agents stores settings in `.planning/config.json`. You configure this during `/ez:new-project` or adjust later with `/ez:settings`.
+
+### Key Settings
+
+| Setting | Options | Default | What It Does |
+|---------|---------|---------|-------------|
+| `mode` | `interactive`, `yolo` | `interactive` | `yolo` skips confirmation prompts |
+| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Controls which model tier each agent uses |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | How many phases (3-5, 5-8, or 8-12) |
+| `smart_orchestration.enabled` | `true`, `false` | `true` | Enable/disable auto-invocation of helper commands |
+
+### Model Profiles
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| Planner | Opus | Opus | Sonnet |
+| Executor | Opus | Sonnet | Sonnet |
+| Researcher | Opus | Sonnet | Haiku |
+| Verifier | Sonnet | Sonnet | Haiku |
+
+**When to use each:**
+- **quality** — Critical work, complex decisions, you have quota
+- **balanced** — Day-to-day development (the default for a reason)
+- **budget** — High-volume work, familiar domains, prototyping
+
+### Multi-Provider Setup
+
+Different providers for different tasks:
+
+```json
+{
+  "provider": {
+    "default": "alibaba",
+    "anthropic": {
+      "api_key": "env:ANTHROPIC_API_KEY"
+    },
+    "alibaba": {
+      "api_key": "env:DASHSCOPE_API_KEY"
+    }
+  },
+  "agent_overrides": {
+    "ez-planner": { "provider": "alibaba", "model": "qwen-max" },
+    "ez-executor": { "provider": "anthropic", "model": "sonnet" }
+  }
+}
+```
+
+---
+
+## Project Structure
+
+After running `/ez:new-project`, you'll have:
+
+```
+.planning/
+  PROJECT.md           # What you're building and why
+  REQUIREMENTS.md      # Scoped requirements with IDs
+  ROADMAP.md           # Phase breakdown with status
+  STATE.md             # Current decisions, blockers, next steps
+  config.json          # Your configuration
+  phases/
+    01-phase-name/
+      01-01-PLAN.md    # Tasks to execute
+      01-01-SUMMARY.md # What was built and why
+      CONTEXT.md       # Your implementation preferences
+      RESEARCH.md      # Domain research
+      VERIFICATION.md  # Test results
+```
+
+**Note:** You can add `.planning/` to `.gitignore` if you don't want planning docs in your repo. Set `commit_docs: false` in `/ez:settings`.
+
+---
+
+## Example: Building a Task App
+
+Let's say you want to build "a task management app with team collaboration."
+
+### 1. Initialize
+
+```bash
+/ez:new-project
+```
+
+You answer questions:
+- Tech stack? → "Next.js + PostgreSQL"
+- Auth method? → "Email + OAuth (Google, GitHub)"
+- First milestone? → "MVP: user accounts, create/edit tasks, share with team"
+
+EZ Agents generates research, requirements, and a roadmap with ~6 phases.
+
+### 2. Phase 1: Foundation
+
+```bash
+/ez:discuss-phase 1
+```
+
+You clarify: "Use Next.js App Router, Prisma for DB, next-auth for OAuth."
+
+```bash
+/ez:plan-phase 1
+```
+
+Research runs (auth patterns, Prisma schema design). Plan is created:
+- Task 1: Database schema (users, tasks, teams)
+- Task 2: Next.js setup with next-auth
+- Task 3: User model and auth endpoints
+
+```bash
+/ez:execute-phase 1
+```
+
+Three tasks, three commits. Each task gets fresh context.
+
+```bash
+/ez:verify-work 1
+```
+
+You test: Can register? Can login? Can connect to DB? All pass.
+
+### 3. Repeat for Each Phase
+
+```bash
+/ez:discuss-phase 2
+/ez:plan-phase 2
+/ez:execute-phase 2
+/ez:verify-work 2
+```
+
+### 4. Complete Milestone
+
+```bash
+/ez:audit-milestone     # Checks all requirements are met
+/ez:complete-milestone  # Archives, tags v1.0
+```
+
+---
+
+## Documentation
+
+| Doc | What's Inside |
+|-----|---------------|
+| [User Guide](docs/USER-GUIDE.md) | Full command reference, workflows, troubleshooting |
+| [Workflows](docs/WORKFLOWS.md) | Complete workflow diagrams for all use cases |
+| [Provider Behaviors](docs/PROVIDER-BEHAVIORS.md) | Differences between Claude, OpenCode, Gemini, etc. |
+| [Qwen Code Install](docs/QWEN-CODE-INSTALL.md) | Fix for Qwen Code CLI installation issues |
+
+---
+
+## Contributing
+
+Contributions welcome! A few guidelines:
+
+1. **Test your changes** — Run `npm test` before submitting
+2. **Keep it cross-platform** — No Unix-specific commands (use `fs-utils.cjs`)
+3. **Document behavior** — Update USER-GUIDE.md for new commands
+4. **Respect the workflow** — EZ Agents is about structure; don't break existing patterns
+
+### Development Setup
+
+```bash
+git clone https://github.com/howlil/ez-agents.git
+cd ez-agents
+npm install
+npm run build:hooks
+npm link
+```
+
+### Running Tests
+
+```bash
+npm test              # Run all tests
+npm run test:coverage # With coverage report
+```
+
+---
+
+## Acknowledgments
+
+EZ Agents is a fork of the original project by [TÂCHES](https://github.com/glittercowboy). This fork adds multi-model support (Qwen, Kimi, OpenAI), enterprise-grade security, and cross-platform reliability. Not affiliated with the upstream repository.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+## Getting Help
+
+- **Issues:** [GitHub Issues](https://github.com/howlil/ez-agents/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/howlil/ez-agents/discussions)
+- **npm:** [@howlil/ez-agents](https://www.npmjs.com/package/@howlil/ez-agents)