@howlil/ez-agents

v5.0.6

Published

3 months ago

EZ Agents — Meta-prompting with multi-model support (Qwen, Kimi, OpenAI)

0High
0Medium
0Low

claude claude-code ai meta-prompting context-engineering spec-driven-development gemini gemini-cli codex codex-cli ez-agents agent-orchestration

  _____ _____     _    ____ _____ _   _ _____ ____ 
 | ____|__  /    / \  / ___| ____| \ | |_   _/ ___|
 |  _|   / /    / _ \| |  _|  _| |  \| | | | \___ \
 | |___ / /_   / ___ \ |_| | |___| |\  | | |  ___) |
 |_____/____| /_/   \_\____|_____|_| \_| |_| |____/

        AI Agent Orchestration System
   Build software with coordinated AI agents

Documentation: API Reference · Architecture · Contributing · Changelog

npm install -g @howlil/[email protected]

Supported Runtimes: Claude Code · OpenCode · Gemini CLI · Codex · Copilot · Qwen Code · Kimi Code

Quick Start · Commands · Architecture · Phase System · Configuration

What is EZ Agents?

EZ Agents is a multi-agent orchestration system for building software with AI agents. It coordinates a team of 8 core agents through a structured 10-phase SDLC workflow — from project brief to production-ready code.

Core Value: Workflow-based orchestration takes your project requirements, decomposes them into a dependency-aware task graph, delegates work to specialist agents in parallel, enforces quality gates, and delivers implementation-ready output: code, tests, documentation, and release artifacts.

Works for: Greenfield projects · Existing codebases · Rapid MVPs · Enterprise-scale products

Key Features

8 Specialist AI Agents — Planner, Executor, Verifier, Debugger, Roadmapper, and research agents
40+ Pre-built Workflows — From project initialization to production release
Wave-Based Parallel Execution — Independent tasks run simultaneously with fresh context
Type-Safe Architecture — Full TypeScript with strict mode and 100% type coverage
6 Design Patterns — Factory, Strategy, Observer, Adapter, Decorator, and Facade patterns
229+ Skills — Domain-specific knowledge for frameworks, testing, DevOps, and security
Smart Orchestration — Automatic helper command invocation based on context
6 Runtime Guards — Safety checks for autonomy, context budget, hallucinations, and more

Quick Start

1. Install

npm install -g @howlil/[email protected]

2. Configure Your AI Runtime

# For Claude Code
ez-agents --claude --global

# For OpenCode
ez-agents --opencode --global

# For Gemini CLI
ez-agents --gemini --global

# For Qwen Code
ez-agents --qwen --global

# See all options
ez-agents --help

3. Initialize a Project

# In your project directory
/ez:new-project

Answer questions about what you're building. EZ Agents generates requirements and a roadmap.

4. Product Discovery (NEW - Product Thinking)

# Validate problem, define metrics, prioritize features
/ez:product-discovery

# Output:
# - User Personas & Journey Maps
# - Validated Problem Statement
# - North Star Metric + HEART Metrics
# - RICE-scored feature prioritization
# - MVP Plan with Build-Measure-Learn

5. Execute Phases

Fast Path (Recommended):

/ez:run-phase 1              # 35-55 min per phase
/ez:run-phase 1 --yolo       # Fully autonomous, no pauses

Manual Control:

/ez:discuss-phase 1          # Clarify approach (15 min)
/ez:plan-phase 1             # Create task breakdown (20 min)
/ez:execute-phase 1          # Build (one commit per task) (30 min)
/ez:verify-work 1            # Test it works (10 min)

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

Architecture

TypeScript & OOP Architecture (v5.0.0)

This codebase has been fully migrated to TypeScript with object-oriented patterns:

98 TypeScript modules in bin/lib/
6 design patterns implemented throughout the codebase
100% type coverage with strict mode enabled
Zero TypeScript errors — build passes tsc --noEmit

System Overview

The EZ Agents system operates through three main layers:

1. Workflow Layer (40 workflows)

plan-phase.md — Creates executable task breakdowns
execute-phase.md — Implements features with atomic commits
verify-work.md — Runs quality gates and tests
new-project.md — Initializes projects with requirements

2. Core Agents (8 specialist agents)

ez-planner — Creates executable phase plans
ez-executor — Implements features with git commits
ez-verifier — Validates work against requirements
ez-debugger — Diagnoses and fixes issues
ez-roadmapper — Creates strategic roadmaps
ez-phase-researcher — Technical research for phases
ez-project-researcher — Project-level discovery
ez-codebase-mapper — Maps existing codebases

3. Research & Release Agents

Research agents handle technical discovery and best practices
Release agents manage versioning, changelogs, and deployment

Complete Workflow

The EZ Agents workflow follows a structured 10-phase SDLC:

Phase 0: Initialization

User provides project idea
/ez:new-project initializes the project
Requirements are generated
Roadmap with 6-10 phases is created

Phase Loop (For Each Phase N)

Step 1: Discuss (Optional)

Command: /ez:discuss-phase
Purpose: Clarify approach and constraints
Duration: 15 minutes

Step 2: Plan

Command: /ez:plan-phase
Activities: Research, task breakdown, verification criteria
Duration: 20 minutes
Output: PLAN.md with dependency-aware tasks

Step 3: Execute

Command: /ez:execute-phase
Method: Wave-based parallel execution
Each task gets fresh 200K context window
One git commit per task
Duration: 30 minutes

Step 4: Verify

Command: /ez:verify-work
Activities: Run tests, manual validation
If tests fail: Auto-diagnose with /ez:debugger and retry
Duration: 10 minutes

Milestone Completion

/ez:audit-milestone — Verify all requirements met
/ez:complete-milestone — Create git tag and archive

Wave-Based Parallel Execution

Tasks are grouped into waves based on dependencies. This ensures:

Fresh context per task — AI doesn't lose context due to window limits
Atomic commits — Each task equals one commit, easy to revert
Parallel execution — Independent tasks run together
Clean git history — Descriptive messages, clear changes

Example: Phase 1 Foundation

Wave 1 (Parallel — No Dependencies)

Task 1.1: Database Schema (fresh 200K context) → git commit
Task 1.2: Next.js Setup (fresh 200K context) → git commit
Task 1.3: Project Config (fresh 200K context) → git commit

Wave 2 (Depends on Wave 1)

Task 1.4: Auth Endpoints
- Dependencies: Task 1.1 (Database Schema) + Task 1.2 (Next.js Setup)
- Fresh 200K context → git commit

Wave 3 (Final Tasks)

Task 1.5: Integration Tests
- Dependencies: Task 1.4 (Auth Endpoints)
- Fresh 200K context → git commit

8 Core Agents

| Agent | Purpose | Tools | |-------|---------|-------| | ez-planner | Creates executable phase plans with task breakdown, dependency analysis | Read, Write, Bash, Glob, Grep, WebFetch | | ez-executor | Executes plans with atomic commits, deviation handling, checkpoint management | Read, Write, Edit, Bash, Grep, Glob | | ez-verifier | Goal-backward verification, checks codebase delivers phase promises | Read, Write, Bash, Glob, Grep | | ez-phase-researcher | Phase-level technical research, stack discovery, best practices | Read, Write, WebSearch, WebFetch, Context7 | | ez-project-researcher | Project-level research, requirements analysis, user discovery | Read, Write, WebSearch, WebFetch | | ez-codebase-mapper | Explores codebase structure, writes analysis documents | Read, Glob, Grep, Bash | | ez-debugger | Scientific bug investigation, hypothesis-driven debugging | Read, Write, Bash, Grep | | ez-roadmapper | Roadmap creation, requirement-to-phase mapping, success criteria | Read, Write |

Note: EZ Agents uses workflow-centric orchestration — intelligence is in ez-agents/workflows/*.md (40 workflow files), not in agent routing logic. Workflows directly spawn agents based on execution context.

Commands

Product Discovery (NEW)

| Command | Description | Time | |---------|-------------|------| | /ez:product-discovery | NEW — Validate problem, define metrics, prioritize features (RICE), create MVP plan | 30-60 min |

Core Workflow

| Command | Description | Time | |---------|-------------|------| | /ez:new-project | Initialize project: answer questions, product discovery, generate requirements and roadmap | 10 min | | /ez:run-phase [N] | Recommended: Run all phases iteratively with pause points. Use --yolo for fully autonomous | 35-55 min/phase | | /ez:quick | Small task without full phase workflow (bug fixes, config changes) | 5-10 min |

Phase Workflow (Manual Control)

| Command | Description | Time | |---------|-------------|------| | /ez:discuss-phase [N] | Optional — Clarify implementation approach before planning | 15 min | | /ez:plan-phase [N] | Create task breakdown with verification criteria | 20 min | | /ez:execute-phase [N] | Build the plan (parallel waves, one commit per task) | 30 min | | /ez:verify-work [N] | Manual testing with auto-diagnosis of failures | 10 min |

Milestone Management

| Command | Description | Time | |---------|-------------|------| | /ez:audit-milestone | Verify all requirements are met | 10 min | | /ez:complete-milestone <version> | Archive milestone, create git tag | 5 min | | /ez:new-milestone | Start next version cycle | 5 min |

Utilities

| Command | Description | |---------|-------------| | /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 |

Phase System

Phase Numbering

Integer phases: 01, 02, 03 — Planned milestone work
Decimal phases: 02.1, 02.2 — Urgent insertions (marked INSERTED)
Letter suffixes: 12A, 12B — Variant phases

Phase Directory Structure

.planning/
├── config.json              # Project configuration
├── STATE.md                 # Current state, decisions, blockers
├── ROADMAP.md               # Phase breakdown with status
├── REQUIREMENTS.md          # Scoped requirements with IDs
├── PROJECT.md               # What you're building and why
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md
    │   ├── 01-01-SUMMARY.md
    │   ├── 01-02-PLAN.md
    │   ├── 01-02-SUMMARY.md
    │   ├── 01-CONTEXT.md
    │   └── 01-RESEARCH.md
    ├── 02-api/
    │   └── ...
    └── 02.1-hotfix/
        └── ...

Context Files

| File | Purpose | Max Lines | |------|---------|-----------| | STATE.md | Single source of truth: current phase, decisions, blockers, metrics | 200 | | ROADMAP.md | Phase structure, requirements mapping, progress tracking | 300 | | REQUIREMENTS.md | What to build (MoSCoW prioritized) | 500 | | SUMMARY.md | What was built (per plan) | 50 | | PROJECT.md | Project overview and context | 300 |

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

Summary Frontmatter (Machine-Readable)

Each SUMMARY.md includes structured frontmatter for dependency tracking:

---
phase: 01-foundation
plan: 01
subsystem: auth
tags: [jwt, jose, bcrypt]
requires:
  - phase: previous
    provides: what-they-built
provides:
  - what-this-built
affects: [future-phase]
tech-stack:
  added: [jose, bcrypt]
  patterns: [httpOnly cookies]
key-files:
  created: [src/lib/auth.ts]
  modified: [prisma/schema.prisma]
key-decisions:
  - "Used jose instead of jsonwebtoken for Edge compatibility"
requirements-completed: [AUTH-01, AUTH-02]
duration: 28min
completed: 2025-01-15
---

Configuration

Project Config: `.planning/config.json`

{
  "model_profile": "balanced",
  "commit_docs": true,
  "search_gitignored": false,
  "branching_strategy": "none",
  "phase_branch_template": "ez/phase-{phase}-{slug}",
  "milestone_branch_template": "ez/{milestone}-{slug}",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "nyquist_validation": true
  },
  "parallelization": true,
  "brave_search": false,
  "recovery": {
    "enabled": true,
    "auto_backup": true
  },
  "infrastructure": {
    "enabled": false
  }
}

Model Profiles

Model profiles control which AI model tier each agent uses:

| Agent | quality | balanced | budget | |-------|-----------|------------|----------| | ez-planner | Opus | Opus | Sonnet | | ez-executor | Opus | Sonnet | Sonnet | | ez-phase-researcher | Opus | Sonnet | Haiku | | ez-codebase-mapper | Sonnet | Haiku | Haiku | | ez-verifier | Sonnet | Sonnet | Haiku | | ez-debugger | Opus | Sonnet | Sonnet |

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

Skills System

EZ Agents includes 229+ skills organized by domain:

Stack Skills

Frontend: React, Vue, Svelte, Angular, Next.js, Nuxt, Remix, Astro, Qwik, SolidJS
Backend: Node.js, Express, NestJS, FastAPI, Django, Laravel, Spring Boot, Go, .NET
Mobile: React Native, Flutter, Ionic
Database: PostgreSQL, MongoDB, Redis
Other: GraphQL, Tauri, Bun/Hono, AI/LLM Integration

Domain Skills

Testing: Unit, Integration, E2E, Security, Performance, Contract
DevOps: CI/CD, Containerization, Cloud Deployment, Monitoring
Architecture: System Design, Microservices, Event-Driven, Serverless
Security: OWASP, Authentication, Authorization, Encryption
Observability: Logging, Metrics, Tracing, Alerting
Operational: Bug Triage, Code Review, Migration, Incident Response, Tech Debt

Skill Structure

skills/stack/nextjs/
├── VERSIONS.md
└── nextjs_app_router_skill_v1/
    └── SKILL.md  (~130 lines - lightweight index)

Skills are resolved automatically based on stack detection during project initialization.

Smart Orchestration

Core commands automatically invoke helper commands based on context. 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.

Guards & Safety

EZ Agents includes 6 runtime guards for safety and quality:

| Guard | Purpose | |-------|---------| | Autonomy Guard | Prevents unauthorized autonomous actions | | Context Budget Guard | Monitors token usage (50%/70%/80% thresholds) | | Hallucination Guard | Detects AI hallucinations and fabrications | | Hidden State Guard | Prevents hidden state and context loss | | Team Overhead Guard | Prevents team coordination overhead | | Tool Sprawl Guard | Prevents tool proliferation |

Context Budget Thresholds

const THRESHOLDS = {
  INFO: 50,      // Quality degradation begins
  WARNING: 70,   // Efficiency mode engaged
  ERROR: 80      // Hard stop
};

Project Structure

Codebase Layout

ez-agents/
├── bin/                          # CLI entry points
│   ├── install.ts                # Main installer (multi-runtime)
│   ├── update.ts                 # Update command
│   ├── lib/                      # 98 core library modules (.ts)
│   │   ├── core.ts               # Shared utilities, model profiles
│   │   ├── config.ts             # Config CRUD
│   │   ├── phase.ts              # Phase operations
│   │   ├── state.ts              # STATE.md operations
│   │   ├── roadmap.ts            # ROADMAP.md parsing
│   │   ├── model-provider.ts     # Multi-model API
│   │   ├── safe-exec.ts          # Command injection prevention
│   │   ├── context-manager.ts    # Context assembly
│   │   └── ...
│   └── guards/                   # 6 runtime guards
├── commands/                     # Command handlers
│   └── ez/                       # 17 agent command templates (.md)
├── ez-agents/                    # Packaged runtime
│   ├── bin/
│   │   ├── ez-tools.ts           # CLI router (160+ atomic commands)
│   │   ├── lib/                  # 81 library modules
│   │   └── guards/               # 6 guards
│   ├── templates/                # 34 templates
│   ├── workflows/                # 40 workflow definitions
│   └── references/               # Reference documentation
├── agents/                       # 10 agent definitions (.md)
├── skills/                       # 229 skill definitions
│   ├── stack/                    # Tech stack skills
│   ├── testing/                  # Testing skills
│   ├── operational/              # Operational skills
│   └── observability/            # Observability skills
├── hooks/                        # Git hooks (Husky)
├── tests/                        # Test suite (307 tests)
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   ├── e2e/                      # End-to-end tests
│   └── critical-paths/           # Critical path tests
├── docs/                         # Documentation
├── .github/                      # GitHub Actions workflows
└── .planning/                    # Project planning artifacts

Key Directories

bin/ — TypeScript source code for CLI and core library
ez-agents/ — Packaged runtime installed to AI config directories
agents/ — Agent definitions with tool permissions and color coding
skills/ — Domain-specific knowledge and best practices
tests/ — Comprehensive test suite (67% passing, target 100%)
docs/ — Architecture, deployment, and troubleshooting guides

Testing

Test Structure

307 total tests across the codebase
206 passing (67%) — Target: 100%
101 failing — Being addressed in ongoing development

Test Categories

| Category | Count | Purpose | |----------|-------|---------| | Unit Tests | 150+ | Individual module testing | | Integration Tests | 50+ | Multi-module coordination | | E2E Tests | 30+ | Full workflow validation | | Critical Paths | 40+ | Core functionality guarantees | | Property-Based | 20+ | Invariant validation | | Performance | 10+ | Benchmark and regression | | Specialized | 7+ | State, context, analytics, finops, security |

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific category
npm test -- tests/unit/
npm test -- tests/integration/
npm test -- tests/e2e/

Contributing

Development Setup

# Clone repository
git clone https://github.com/howlil/ez-agents.git
cd ez-agents

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Link for local development
npm link

Code Quality

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Format code
npm run format

Pull Request Process

Create feature branch from main
Make changes with tests
Ensure all checks pass (CI, tests, linting)
Submit PR with clear description
Address review feedback
Merge after approval

Documentation

API Reference: Auto-generated with TypeDoc
Architecture: Detailed system design in docs/
Contributing: Guidelines in CONTRIBUTING.md
Changelog: Follows Keep a Changelog

Changelog

[5.0.0] - 2026-03-28

Major Release: Complete TypeScript & OOP Transformation

Highlights:

✅ TypeScript migration complete (98 modules)
✅ OOP architecture with 6 design patterns
✅ Zero TypeScript errors (586 → 0)
✅ 100% type coverage achieved
✅ Product discovery workflow added
✅ 10x engineer metrics tracking
✅ 229+ skills system

New Features:

Product Discovery workflow with user personas, metrics, and RICE scoring
Template validation module for output consistency
Skill system reference documentation
Workflow metrics tracking system
Workflow versioning with migrations
Standardized argument parsing (TypeScript)
5 new workflows (refactor, security, rollback, dependency-audit, accessibility-audit)
Reference indices for templates, workflows, and agents

System Health: 7.1/10 → 8.0/10 (+13%)

See CHANGELOG.md for complete history.

License

MIT License — see LICENSE for details.

Support

Documentation: API Reference
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: Support available via GitHub

Built with ❤️ by the EZ Agents Team

Top