EZ Agents

Build any app — from MVP to enterprise — with coordinated AI agents.

npm i -g @howlil/ez-agents@latest

Works with: Claude Code · OpenCode · Gemini CLI · Codex · Copilot · Qwen · Kimi

Quick Start · Lean Workflow · Commands · Setup · Docs · Lean Guide

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

npm i -g @howlil/ez-agents@latest

2. Setup for Your AI Tool

# 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

# 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:

# ⚡ 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

/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
• Tests
• CodeQL
• Security Scan

For Existing Codebases

# 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:

/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:

# 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):

# 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:

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:

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:

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

npm i -g @howlil/ez-agents@latest
ez-agents --claude --global

Updating

npm update -g @howlil/ez-agents

Development Install (for contributing)

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:

{
  "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

/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

/ez:discuss-phase 1

You clarify: "Use Next.js App Router, Prisma for DB, next-auth for OAuth."

/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

/ez:execute-phase 1

Three tasks, three commits. Each task gets fresh context.

/ez:verify-work 1

You test: Can register? Can login? Can connect to DB? All pass.

3. Repeat for Each Phase

/ez:discuss-phase 2
/ez:plan-phase 2
/ez:execute-phase 2
/ez:verify-work 2

4. Complete Milestone

/ez:audit-milestone     # Checks all requirements are met
/ez:complete-milestone  # Archives, tags v1.0

Documentation

| Doc | What's Inside | |-----|---------------| | User Guide | Full command reference, workflows, troubleshooting | | Workflows | Complete workflow diagrams for all use cases | | Provider Behaviors | Differences between Claude, OpenCode, Gemini, etc. | | Qwen Code Install | 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

git clone https://github.com/howlil/ez-agents.git
cd ez-agents
npm install
npm run build:hooks
npm link

Running Tests

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. 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

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• npm: @howlil/ez-agents