@howlil/ez-agents 5.0.0 → 5.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +734 -1057
- package/dist/bin/install.js +12 -3
- package/dist/bin/update.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,1057 +1,734 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
```
|
|
4
|
-
_____ _____ _ ____ _____ _ _ _____ ____
|
|
5
|
-
| ____|__ / / \ / ___| ____| \ | |_ _/ ___|
|
|
6
|
-
| _| / / / _ \| | _| _| | \| | | | \___ \
|
|
7
|
-
| |___ / /_ / ___ \ |_| | |___| |\ | | | ___) |
|
|
8
|
-
|_____/____| /_/ \_\____|_____|_| \_| |_| |____/
|
|
9
|
-
|
|
10
|
-
AI Agent Orchestration System
|
|
11
|
-
Build software with coordinated AI agents
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
[ for complete migration guide.
|
|
926
|
-
|
|
927
|
-
### TypeScript Usage Example
|
|
928
|
-
|
|
929
|
-
```typescript
|
|
930
|
-
import { createAgent, createPhase, withRetry } from '@howlil/ez-agents';
|
|
931
|
-
|
|
932
|
-
// Full type inference and validation
|
|
933
|
-
const agent = createAgent({
|
|
934
|
-
name: 'code-reviewer',
|
|
935
|
-
model: 'qwen',
|
|
936
|
-
skills: ['code-review', 'testing']
|
|
937
|
-
});
|
|
938
|
-
|
|
939
|
-
const phase = createPhase({
|
|
940
|
-
number: 1,
|
|
941
|
-
title: 'Foundation',
|
|
942
|
-
status: 'pending'
|
|
943
|
-
});
|
|
944
|
-
|
|
945
|
-
// Error handling with retry (replaces circuit breaker)
|
|
946
|
-
const result = await withRetry(() => apiCall(), {
|
|
947
|
-
maxRetries: 3,
|
|
948
|
-
baseDelay: 100,
|
|
949
|
-
onRetry: (error, attempt) => console.warn(`Retry ${attempt}: ${error.message}`)
|
|
950
|
-
});
|
|
951
|
-
```
|
|
952
|
-
|
|
953
|
-
### Type Safety Benefits
|
|
954
|
-
|
|
955
|
-
v5.0.0 provides:
|
|
956
|
-
|
|
957
|
-
- **Compile-time error detection** — Catch bugs before runtime
|
|
958
|
-
- **IDE autocomplete** — Full IntelliSense for all APIs
|
|
959
|
-
- **Refactoring safety** — Rename symbols with confidence
|
|
960
|
-
- **Self-documenting code** — Types serve as documentation
|
|
961
|
-
- **Generic reusability** — Type-safe generic utilities
|
|
962
|
-
|
|
963
|
-
### Architecture: OOP + FP Hybrid
|
|
964
|
-
|
|
965
|
-
EZ Agents uses a hybrid architecture combining Object-Oriented Programming (OOP) for stateful entities and Functional Programming (FP) for pure transformations.
|
|
966
|
-
|
|
967
|
-
#### When to Use Classes (OOP)
|
|
968
|
-
|
|
969
|
-
Use classes for stateful entities with lifecycle:
|
|
970
|
-
- `SessionManager` — Manages session state persistence
|
|
971
|
-
- `ContextManager` — Tracks context usage and limits
|
|
972
|
-
- `withRetry()` — Simple retry logic (replaces CircuitBreaker)
|
|
973
|
-
|
|
974
|
-
```typescript
|
|
975
|
-
export class SessionManager {
|
|
976
|
-
private state: SessionState | null;
|
|
977
|
-
|
|
978
|
-
loadState(): SessionState | null { /* ... */ }
|
|
979
|
-
saveState(state: SessionState): void { /* ... */ }
|
|
980
|
-
}
|
|
981
|
-
```
|
|
982
|
-
|
|
983
|
-
#### When to Use Functions (FP)
|
|
984
|
-
|
|
985
|
-
Use functions for pure transformations and utilities:
|
|
986
|
-
- `safeExec()` — Command execution
|
|
987
|
-
- `loadConfig()` — Configuration loading
|
|
988
|
-
- `withRetry()` — Retry logic with exponential backoff
|
|
989
|
-
- `map()`, `filter()`, `reduce()` — Data transformations
|
|
990
|
-
|
|
991
|
-
```typescript
|
|
992
|
-
export function withRetry<T>(
|
|
993
|
-
operation: () => Promise<T>,
|
|
994
|
-
options: RetryOptions = {}
|
|
995
|
-
): Promise<T> {
|
|
996
|
-
// Exponential backoff with jitter
|
|
997
|
-
}
|
|
998
|
-
```
|
|
999
|
-
|
|
1000
|
-
### Migration Notes
|
|
1001
|
-
|
|
1002
|
-
**For existing users:** v5.0.0 has BREAKING CHANGES in Phase 28.
|
|
1003
|
-
|
|
1004
|
-
- If you used `CircuitBreaker`, migrate to `withRetry()` (see [MIGRATION.md](MIGRATION.md))
|
|
1005
|
-
- If you used analytics module, use external service or implement custom solution
|
|
1006
|
-
- Update `.env`: Remove `EZ_LOG_CIRCUIT_BREAKER` and `EZ_LOG_ANALYTICS`
|
|
1007
|
-
|
|
1008
|
-
**For contributors:** See [TypeScript Contributor Guide](docs/CONTRIBUTING-TYPESCRIPT.md) for architecture patterns and type standards.
|
|
1009
|
-
|
|
1010
|
-
---
|
|
1011
|
-
|
|
1012
|
-
## Contributing
|
|
1013
|
-
|
|
1014
|
-
Contributions welcome! A few guidelines:
|
|
1015
|
-
|
|
1016
|
-
1. **Test your changes** — Run `npm test` before submitting
|
|
1017
|
-
2. **Keep it cross-platform** — No Unix-specific commands (use `fs-utils.cjs`)
|
|
1018
|
-
3. **Document behavior** — Update documentation for new commands
|
|
1019
|
-
4. **Respect the workflow** — EZ Agents is about structure; don't break existing patterns
|
|
1020
|
-
|
|
1021
|
-
### Development Setup
|
|
1022
|
-
|
|
1023
|
-
```bash
|
|
1024
|
-
git clone https://github.com/howlil/ez-agents.git
|
|
1025
|
-
cd ez-agents
|
|
1026
|
-
npm install
|
|
1027
|
-
npm run build:hooks
|
|
1028
|
-
npm link
|
|
1029
|
-
```
|
|
1030
|
-
|
|
1031
|
-
### Running Tests
|
|
1032
|
-
|
|
1033
|
-
```bash
|
|
1034
|
-
npm test # Run all tests
|
|
1035
|
-
npm run test:coverage # With coverage report
|
|
1036
|
-
```
|
|
1037
|
-
|
|
1038
|
-
---
|
|
1039
|
-
|
|
1040
|
-
## Acknowledgments
|
|
1041
|
-
|
|
1042
|
-
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.
|
|
1043
|
-
|
|
1044
|
-
---
|
|
1045
|
-
|
|
1046
|
-
## License
|
|
1047
|
-
|
|
1048
|
-
MIT — see [LICENSE](LICENSE)
|
|
1049
|
-
|
|
1050
|
-
---
|
|
1051
|
-
|
|
1052
|
-
## Getting Help
|
|
1053
|
-
|
|
1054
|
-
- **Issues:** [GitHub Issues](https://github.com/howlil/ez-agents/issues)
|
|
1055
|
-
- **Discussions:** [GitHub Discussions](https://github.com/howlil/ez-agents/discussions)
|
|
1056
|
-
- **npm:** [@howlil/ez-agents](https://www.npmjs.com/package/@howlil/ez-agents)
|
|
1057
|
-
- **Source:** [GitHub](https://github.com/howlil/ez-agents)
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
_____ _____ _ ____ _____ _ _ _____ ____
|
|
5
|
+
| ____|__ / / \ / ___| ____| \ | |_ _/ ___|
|
|
6
|
+
| _| / / / _ \| | _| _| | \| | | | \___ \
|
|
7
|
+
| |___ / /_ / ___ \ |_| | |___| |\ | | | ___) |
|
|
8
|
+
|_____/____| /_/ \_\____|_____|_| \_| |_| |____/
|
|
9
|
+
|
|
10
|
+
AI Agent Orchestration System
|
|
11
|
+
Build software with coordinated AI agents
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
[](https://www.npmjs.com/package/@howlil/ez-agents)
|
|
15
|
+
[](https://npmjs.com/package/@howlil/ez-agents)
|
|
16
|
+
[](https://github.com/howlil/ez-agents/actions/workflows/ci.yml)
|
|
17
|
+
[](https://github.com/howlil/ez-agents/actions/workflows/codeql.yml)
|
|
18
|
+
[](LICENSE)
|
|
19
|
+
|
|
20
|
+
**Documentation:** [API Reference](https://howlil.github.io/ez-agents/api/) · [Architecture](docs/ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install -g @howlil/ez-agents@5.0.0
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**Supported Runtimes:** Claude Code · OpenCode · Gemini CLI · Codex · Copilot · Qwen Code · Kimi Code
|
|
27
|
+
|
|
28
|
+
[Quick Start](#quick-start) · [Commands](#commands) · [Architecture](#architecture) · [Phase System](#phase-system) · [Configuration](#configuration)
|
|
29
|
+
|
|
30
|
+
</div>
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## What is EZ Agents?
|
|
35
|
+
|
|
36
|
+
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.
|
|
37
|
+
|
|
38
|
+
**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.
|
|
39
|
+
|
|
40
|
+
**Works for:** Greenfield projects · Existing codebases · Rapid MVPs · Enterprise-scale products
|
|
41
|
+
|
|
42
|
+
### Key Features
|
|
43
|
+
|
|
44
|
+
- **8 Specialist AI Agents** — Planner, Executor, Verifier, Debugger, Roadmapper, and research agents
|
|
45
|
+
- **40+ Pre-built Workflows** — From project initialization to production release
|
|
46
|
+
- **Wave-Based Parallel Execution** — Independent tasks run simultaneously with fresh context
|
|
47
|
+
- **Type-Safe Architecture** — Full TypeScript with strict mode and 100% type coverage
|
|
48
|
+
- **6 Design Patterns** — Factory, Strategy, Observer, Adapter, Decorator, and Facade patterns
|
|
49
|
+
- **229+ Skills** — Domain-specific knowledge for frameworks, testing, DevOps, and security
|
|
50
|
+
- **Smart Orchestration** — Automatic helper command invocation based on context
|
|
51
|
+
- **6 Runtime Guards** — Safety checks for autonomy, context budget, hallucinations, and more
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Quick Start
|
|
56
|
+
|
|
57
|
+
### 1. Install
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm install -g @howlil/ez-agents@5.0.0
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### 2. Configure Your AI Runtime
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
# For Claude Code
|
|
67
|
+
ez-agents --claude --global
|
|
68
|
+
|
|
69
|
+
# For OpenCode
|
|
70
|
+
ez-agents --opencode --global
|
|
71
|
+
|
|
72
|
+
# For Gemini CLI
|
|
73
|
+
ez-agents --gemini --global
|
|
74
|
+
|
|
75
|
+
# For Qwen Code
|
|
76
|
+
ez-agents --qwen --global
|
|
77
|
+
|
|
78
|
+
# See all options
|
|
79
|
+
ez-agents --help
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### 3. Initialize a Project
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# In your project directory
|
|
86
|
+
/ez:new-project
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Answer questions about what you're building. EZ Agents generates requirements and a roadmap.
|
|
90
|
+
|
|
91
|
+
### 4. Product Discovery (NEW - Product Thinking)
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# Validate problem, define metrics, prioritize features
|
|
95
|
+
/ez:product-discovery
|
|
96
|
+
|
|
97
|
+
# Output:
|
|
98
|
+
# - User Personas & Journey Maps
|
|
99
|
+
# - Validated Problem Statement
|
|
100
|
+
# - North Star Metric + HEART Metrics
|
|
101
|
+
# - RICE-scored feature prioritization
|
|
102
|
+
# - MVP Plan with Build-Measure-Learn
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 5. Execute Phases
|
|
106
|
+
|
|
107
|
+
**Fast Path (Recommended):**
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
/ez:run-phase 1 # 35-55 min per phase
|
|
111
|
+
/ez:run-phase 1 --yolo # Fully autonomous, no pauses
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
**Manual Control:**
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
/ez:discuss-phase 1 # Clarify approach (15 min)
|
|
118
|
+
/ez:plan-phase 1 # Create task breakdown (20 min)
|
|
119
|
+
/ez:execute-phase 1 # Build (one commit per task) (30 min)
|
|
120
|
+
/ez:verify-work 1 # Test it works (10 min)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### 6. Complete Milestone
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
/ez:audit-milestone # Verify all requirements met (10 min)
|
|
127
|
+
/ez:complete-milestone 1.0.0 # Archive and tag release (5 min)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
**Total time from idea to MVP: 2-3 days**
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Architecture
|
|
135
|
+
|
|
136
|
+
### TypeScript & OOP Architecture (v5.0.0)
|
|
137
|
+
|
|
138
|
+
This codebase has been fully migrated to TypeScript with object-oriented patterns:
|
|
139
|
+
|
|
140
|
+
- **98 TypeScript modules** in `bin/lib/`
|
|
141
|
+
- **6 design patterns** implemented throughout the codebase
|
|
142
|
+
- **100% type coverage** with strict mode enabled
|
|
143
|
+
- **Zero TypeScript errors** — build passes `tsc --noEmit`
|
|
144
|
+
|
|
145
|
+
### System Overview
|
|
146
|
+
|
|
147
|
+
The EZ Agents system operates through three main layers:
|
|
148
|
+
|
|
149
|
+
**1. Workflow Layer (40 workflows)**
|
|
150
|
+
- `plan-phase.md` — Creates executable task breakdowns
|
|
151
|
+
- `execute-phase.md` — Implements features with atomic commits
|
|
152
|
+
- `verify-work.md` — Runs quality gates and tests
|
|
153
|
+
- `new-project.md` — Initializes projects with requirements
|
|
154
|
+
|
|
155
|
+
**2. Core Agents (8 specialist agents)**
|
|
156
|
+
- `ez-planner` — Creates executable phase plans
|
|
157
|
+
- `ez-executor` — Implements features with git commits
|
|
158
|
+
- `ez-verifier` — Validates work against requirements
|
|
159
|
+
- `ez-debugger` — Diagnoses and fixes issues
|
|
160
|
+
- `ez-roadmapper` — Creates strategic roadmaps
|
|
161
|
+
- `ez-phase-researcher` — Technical research for phases
|
|
162
|
+
- `ez-project-researcher` — Project-level discovery
|
|
163
|
+
- `ez-codebase-mapper` — Maps existing codebases
|
|
164
|
+
|
|
165
|
+
**3. Research & Release Agents**
|
|
166
|
+
- Research agents handle technical discovery and best practices
|
|
167
|
+
- Release agents manage versioning, changelogs, and deployment
|
|
168
|
+
|
|
169
|
+
### Complete Workflow
|
|
170
|
+
|
|
171
|
+
The EZ Agents workflow follows a structured 10-phase SDLC:
|
|
172
|
+
|
|
173
|
+
**Phase 0: Initialization**
|
|
174
|
+
1. User provides project idea
|
|
175
|
+
2. `/ez:new-project` initializes the project
|
|
176
|
+
3. Requirements are generated
|
|
177
|
+
4. Roadmap with 6-10 phases is created
|
|
178
|
+
|
|
179
|
+
**Phase Loop (For Each Phase N)**
|
|
180
|
+
|
|
181
|
+
**Step 1: Discuss (Optional)**
|
|
182
|
+
- Command: `/ez:discuss-phase`
|
|
183
|
+
- Purpose: Clarify approach and constraints
|
|
184
|
+
- Duration: 15 minutes
|
|
185
|
+
|
|
186
|
+
**Step 2: Plan**
|
|
187
|
+
- Command: `/ez:plan-phase`
|
|
188
|
+
- Activities: Research, task breakdown, verification criteria
|
|
189
|
+
- Duration: 20 minutes
|
|
190
|
+
- Output: `PLAN.md` with dependency-aware tasks
|
|
191
|
+
|
|
192
|
+
**Step 3: Execute**
|
|
193
|
+
- Command: `/ez:execute-phase`
|
|
194
|
+
- Method: Wave-based parallel execution
|
|
195
|
+
- Each task gets fresh 200K context window
|
|
196
|
+
- One git commit per task
|
|
197
|
+
- Duration: 30 minutes
|
|
198
|
+
|
|
199
|
+
**Step 4: Verify**
|
|
200
|
+
- Command: `/ez:verify-work`
|
|
201
|
+
- Activities: Run tests, manual validation
|
|
202
|
+
- If tests fail: Auto-diagnose with `/ez:debugger` and retry
|
|
203
|
+
- Duration: 10 minutes
|
|
204
|
+
|
|
205
|
+
**Milestone Completion**
|
|
206
|
+
- `/ez:audit-milestone` — Verify all requirements met
|
|
207
|
+
- `/ez:complete-milestone` — Create git tag and archive
|
|
208
|
+
|
|
209
|
+
### Wave-Based Parallel Execution
|
|
210
|
+
|
|
211
|
+
Tasks are grouped into waves based on dependencies. This ensures:
|
|
212
|
+
|
|
213
|
+
- **Fresh context per task** — AI doesn't lose context due to window limits
|
|
214
|
+
- **Atomic commits** — Each task equals one commit, easy to revert
|
|
215
|
+
- **Parallel execution** — Independent tasks run together
|
|
216
|
+
- **Clean git history** — Descriptive messages, clear changes
|
|
217
|
+
|
|
218
|
+
**Example: Phase 1 Foundation**
|
|
219
|
+
|
|
220
|
+
**Wave 1 (Parallel — No Dependencies)**
|
|
221
|
+
- Task 1.1: Database Schema (fresh 200K context) → git commit
|
|
222
|
+
- Task 1.2: Next.js Setup (fresh 200K context) → git commit
|
|
223
|
+
- Task 1.3: Project Config (fresh 200K context) → git commit
|
|
224
|
+
|
|
225
|
+
**Wave 2 (Depends on Wave 1)**
|
|
226
|
+
- Task 1.4: Auth Endpoints
|
|
227
|
+
- Dependencies: Task 1.1 (Database Schema) + Task 1.2 (Next.js Setup)
|
|
228
|
+
- Fresh 200K context → git commit
|
|
229
|
+
|
|
230
|
+
**Wave 3 (Final Tasks)**
|
|
231
|
+
- Task 1.5: Integration Tests
|
|
232
|
+
- Dependencies: Task 1.4 (Auth Endpoints)
|
|
233
|
+
- Fresh 200K context → git commit
|
|
234
|
+
|
|
235
|
+
### 8 Core Agents
|
|
236
|
+
|
|
237
|
+
| Agent | Purpose | Tools |
|
|
238
|
+
|-------|---------|-------|
|
|
239
|
+
| **ez-planner** | Creates executable phase plans with task breakdown, dependency analysis | Read, Write, Bash, Glob, Grep, WebFetch |
|
|
240
|
+
| **ez-executor** | Executes plans with atomic commits, deviation handling, checkpoint management | Read, Write, Edit, Bash, Grep, Glob |
|
|
241
|
+
| **ez-verifier** | Goal-backward verification, checks codebase delivers phase promises | Read, Write, Bash, Glob, Grep |
|
|
242
|
+
| **ez-phase-researcher** | Phase-level technical research, stack discovery, best practices | Read, Write, WebSearch, WebFetch, Context7 |
|
|
243
|
+
| **ez-project-researcher** | Project-level research, requirements analysis, user discovery | Read, Write, WebSearch, WebFetch |
|
|
244
|
+
| **ez-codebase-mapper** | Explores codebase structure, writes analysis documents | Read, Glob, Grep, Bash |
|
|
245
|
+
| **ez-debugger** | Scientific bug investigation, hypothesis-driven debugging | Read, Write, Bash, Grep |
|
|
246
|
+
| **ez-roadmapper** | Roadmap creation, requirement-to-phase mapping, success criteria | Read, Write |
|
|
247
|
+
|
|
248
|
+
**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.
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Commands
|
|
253
|
+
|
|
254
|
+
### Product Discovery (NEW)
|
|
255
|
+
|
|
256
|
+
| Command | Description | Time |
|
|
257
|
+
|---------|-------------|------|
|
|
258
|
+
| `/ez:product-discovery` | **NEW** — Validate problem, define metrics, prioritize features (RICE), create MVP plan | 30-60 min |
|
|
259
|
+
|
|
260
|
+
### Core Workflow
|
|
261
|
+
|
|
262
|
+
| Command | Description | Time |
|
|
263
|
+
|---------|-------------|------|
|
|
264
|
+
| `/ez:new-project` | Initialize project: answer questions, **product discovery**, generate requirements and roadmap | 10 min |
|
|
265
|
+
| `/ez:run-phase [N]` | **Recommended:** Run all phases iteratively with pause points. Use `--yolo` for fully autonomous | 35-55 min/phase |
|
|
266
|
+
| `/ez:quick` | Small task without full phase workflow (bug fixes, config changes) | 5-10 min |
|
|
267
|
+
|
|
268
|
+
### Phase Workflow (Manual Control)
|
|
269
|
+
|
|
270
|
+
| Command | Description | Time |
|
|
271
|
+
|---------|-------------|------|
|
|
272
|
+
| `/ez:discuss-phase [N]` | Optional — Clarify implementation approach before planning | 15 min |
|
|
273
|
+
| `/ez:plan-phase [N]` | Create task breakdown with verification criteria | 20 min |
|
|
274
|
+
| `/ez:execute-phase [N]` | Build the plan (parallel waves, one commit per task) | 30 min |
|
|
275
|
+
| `/ez:verify-work [N]` | Manual testing with auto-diagnosis of failures | 10 min |
|
|
276
|
+
|
|
277
|
+
### Milestone Management
|
|
278
|
+
|
|
279
|
+
| Command | Description | Time |
|
|
280
|
+
|---------|-------------|------|
|
|
281
|
+
| `/ez:audit-milestone` | Verify all requirements are met | 10 min |
|
|
282
|
+
| `/ez:complete-milestone <version>` | Archive milestone, create git tag | 5 min |
|
|
283
|
+
| `/ez:new-milestone` | Start next version cycle | 5 min |
|
|
284
|
+
|
|
285
|
+
### Utilities
|
|
286
|
+
|
|
287
|
+
| Command | Description |
|
|
288
|
+
|---------|-------------|
|
|
289
|
+
| `/ez:map-codebase` | Analyze existing codebase (before `/ez:new-project`) |
|
|
290
|
+
| `/ez:progress` | See where you are and what's next |
|
|
291
|
+
| `/ez:resume-work` | Restore context from last session |
|
|
292
|
+
| `/ez:settings` | Configure workflow, model profile, git strategy |
|
|
293
|
+
| `/ez:update` | Update EZ Agents (with changelog preview) |
|
|
294
|
+
| `/ez:help` | Show all commands |
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## Phase System
|
|
299
|
+
|
|
300
|
+
### Phase Numbering
|
|
301
|
+
|
|
302
|
+
- **Integer phases:** `01`, `02`, `03` — Planned milestone work
|
|
303
|
+
- **Decimal phases:** `02.1`, `02.2` — Urgent insertions (marked `INSERTED`)
|
|
304
|
+
- **Letter suffixes:** `12A`, `12B` — Variant phases
|
|
305
|
+
|
|
306
|
+
### Phase Directory Structure
|
|
307
|
+
|
|
308
|
+
```
|
|
309
|
+
.planning/
|
|
310
|
+
├── config.json # Project configuration
|
|
311
|
+
├── STATE.md # Current state, decisions, blockers
|
|
312
|
+
├── ROADMAP.md # Phase breakdown with status
|
|
313
|
+
├── REQUIREMENTS.md # Scoped requirements with IDs
|
|
314
|
+
├── PROJECT.md # What you're building and why
|
|
315
|
+
└── phases/
|
|
316
|
+
├── 01-foundation/
|
|
317
|
+
│ ├── 01-01-PLAN.md
|
|
318
|
+
│ ├── 01-01-SUMMARY.md
|
|
319
|
+
│ ├── 01-02-PLAN.md
|
|
320
|
+
│ ├── 01-02-SUMMARY.md
|
|
321
|
+
│ ├── 01-CONTEXT.md
|
|
322
|
+
│ └── 01-RESEARCH.md
|
|
323
|
+
├── 02-api/
|
|
324
|
+
│ └── ...
|
|
325
|
+
└── 02.1-hotfix/
|
|
326
|
+
└── ...
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
### Context Files
|
|
330
|
+
|
|
331
|
+
| File | Purpose | Max Lines |
|
|
332
|
+
|------|---------|-----------|
|
|
333
|
+
| `STATE.md` | Single source of truth: current phase, decisions, blockers, metrics | 200 |
|
|
334
|
+
| `ROADMAP.md` | Phase structure, requirements mapping, progress tracking | 300 |
|
|
335
|
+
| `REQUIREMENTS.md` | What to build (MoSCoW prioritized) | 500 |
|
|
336
|
+
| `SUMMARY.md` | What was built (per plan) | 50 |
|
|
337
|
+
| `PROJECT.md` | Project overview and context | 300 |
|
|
338
|
+
|
|
339
|
+
**Deprecated (no longer required):**
|
|
340
|
+
- `CONTEXT.md` → Merge decisions into `STATE.md`
|
|
341
|
+
- `RESEARCH.md` → Inline research in `PLAN.md`
|
|
342
|
+
- `VERIFICATION.md` → Inline in `SUMMARY.md`
|
|
343
|
+
- `UAT.md` → Merge into `SUMMARY.md`
|
|
344
|
+
- `DISCUSSION.md` → Removed entirely
|
|
345
|
+
|
|
346
|
+
### Summary Frontmatter (Machine-Readable)
|
|
347
|
+
|
|
348
|
+
Each `SUMMARY.md` includes structured frontmatter for dependency tracking:
|
|
349
|
+
|
|
350
|
+
```yaml
|
|
351
|
+
---
|
|
352
|
+
phase: 01-foundation
|
|
353
|
+
plan: 01
|
|
354
|
+
subsystem: auth
|
|
355
|
+
tags: [jwt, jose, bcrypt]
|
|
356
|
+
requires:
|
|
357
|
+
- phase: previous
|
|
358
|
+
provides: what-they-built
|
|
359
|
+
provides:
|
|
360
|
+
- what-this-built
|
|
361
|
+
affects: [future-phase]
|
|
362
|
+
tech-stack:
|
|
363
|
+
added: [jose, bcrypt]
|
|
364
|
+
patterns: [httpOnly cookies]
|
|
365
|
+
key-files:
|
|
366
|
+
created: [src/lib/auth.ts]
|
|
367
|
+
modified: [prisma/schema.prisma]
|
|
368
|
+
key-decisions:
|
|
369
|
+
- "Used jose instead of jsonwebtoken for Edge compatibility"
|
|
370
|
+
requirements-completed: [AUTH-01, AUTH-02]
|
|
371
|
+
duration: 28min
|
|
372
|
+
completed: 2025-01-15
|
|
373
|
+
---
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## Configuration
|
|
379
|
+
|
|
380
|
+
### Project Config: `.planning/config.json`
|
|
381
|
+
|
|
382
|
+
```json
|
|
383
|
+
{
|
|
384
|
+
"model_profile": "balanced",
|
|
385
|
+
"commit_docs": true,
|
|
386
|
+
"search_gitignored": false,
|
|
387
|
+
"branching_strategy": "none",
|
|
388
|
+
"phase_branch_template": "ez/phase-{phase}-{slug}",
|
|
389
|
+
"milestone_branch_template": "ez/{milestone}-{slug}",
|
|
390
|
+
"workflow": {
|
|
391
|
+
"research": true,
|
|
392
|
+
"plan_check": true,
|
|
393
|
+
"verifier": true,
|
|
394
|
+
"nyquist_validation": true
|
|
395
|
+
},
|
|
396
|
+
"parallelization": true,
|
|
397
|
+
"brave_search": false,
|
|
398
|
+
"recovery": {
|
|
399
|
+
"enabled": true,
|
|
400
|
+
"auto_backup": true
|
|
401
|
+
},
|
|
402
|
+
"infrastructure": {
|
|
403
|
+
"enabled": false
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### Model Profiles
|
|
409
|
+
|
|
410
|
+
Model profiles control which AI model tier each agent uses:
|
|
411
|
+
|
|
412
|
+
| Agent | `quality` | `balanced` | `budget` |
|
|
413
|
+
|-------|-----------|------------|----------|
|
|
414
|
+
| ez-planner | Opus | Opus | Sonnet |
|
|
415
|
+
| ez-executor | Opus | Sonnet | Sonnet |
|
|
416
|
+
| ez-phase-researcher | Opus | Sonnet | Haiku |
|
|
417
|
+
| ez-codebase-mapper | Sonnet | Haiku | Haiku |
|
|
418
|
+
| ez-verifier | Sonnet | Sonnet | Haiku |
|
|
419
|
+
| ez-debugger | Opus | Sonnet | Sonnet |
|
|
420
|
+
|
|
421
|
+
**When to use each:**
|
|
422
|
+
- **quality** — Critical work, complex decisions, you have quota
|
|
423
|
+
- **balanced** — Day-to-day development (the default for a reason)
|
|
424
|
+
- **budget** — High-volume work, familiar domains, prototyping
|
|
425
|
+
|
|
426
|
+
### Multi-Provider Setup
|
|
427
|
+
|
|
428
|
+
Different providers for different tasks:
|
|
429
|
+
|
|
430
|
+
```json
|
|
431
|
+
{
|
|
432
|
+
"provider": {
|
|
433
|
+
"default": "alibaba",
|
|
434
|
+
"anthropic": {
|
|
435
|
+
"api_key": "env:ANTHROPIC_API_KEY"
|
|
436
|
+
},
|
|
437
|
+
"alibaba": {
|
|
438
|
+
"api_key": "env:DASHSCOPE_API_KEY"
|
|
439
|
+
}
|
|
440
|
+
},
|
|
441
|
+
"agent_overrides": {
|
|
442
|
+
"ez-planner": { "provider": "alibaba", "model": "qwen-max" },
|
|
443
|
+
"ez-executor": { "provider": "anthropic", "model": "sonnet" }
|
|
444
|
+
}
|
|
445
|
+
}
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
---
|
|
449
|
+
|
|
450
|
+
## Skills System
|
|
451
|
+
|
|
452
|
+
EZ Agents includes **229+ skills** organized by domain:
|
|
453
|
+
|
|
454
|
+
### Stack Skills
|
|
455
|
+
|
|
456
|
+
- **Frontend:** React, Vue, Svelte, Angular, Next.js, Nuxt, Remix, Astro, Qwik, SolidJS
|
|
457
|
+
- **Backend:** Node.js, Express, NestJS, FastAPI, Django, Laravel, Spring Boot, Go, .NET
|
|
458
|
+
- **Mobile:** React Native, Flutter, Ionic
|
|
459
|
+
- **Database:** PostgreSQL, MongoDB, Redis
|
|
460
|
+
- **Other:** GraphQL, Tauri, Bun/Hono, AI/LLM Integration
|
|
461
|
+
|
|
462
|
+
### Domain Skills
|
|
463
|
+
|
|
464
|
+
- **Testing:** Unit, Integration, E2E, Security, Performance, Contract
|
|
465
|
+
- **DevOps:** CI/CD, Containerization, Cloud Deployment, Monitoring
|
|
466
|
+
- **Architecture:** System Design, Microservices, Event-Driven, Serverless
|
|
467
|
+
- **Security:** OWASP, Authentication, Authorization, Encryption
|
|
468
|
+
- **Observability:** Logging, Metrics, Tracing, Alerting
|
|
469
|
+
- **Operational:** Bug Triage, Code Review, Migration, Incident Response, Tech Debt
|
|
470
|
+
|
|
471
|
+
### Skill Structure
|
|
472
|
+
|
|
473
|
+
```
|
|
474
|
+
skills/stack/nextjs/
|
|
475
|
+
├── VERSIONS.md
|
|
476
|
+
└── nextjs_app_router_skill_v1/
|
|
477
|
+
└── SKILL.md (~130 lines - lightweight index)
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
Skills are resolved automatically based on stack detection during project initialization.
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## Smart Orchestration
|
|
485
|
+
|
|
486
|
+
Core commands automatically invoke helper commands based on context. All auto-invocations are visible with an `[auto]` prefix.
|
|
487
|
+
|
|
488
|
+
| Command | Auto Pre | Auto Post | Conditional |
|
|
489
|
+
|---------|----------|-----------|-------------|
|
|
490
|
+
| `/ez:execute-phase` | health check | verify-work | discuss-phase (medium/enterprise, no CONTEXT.md) · add-todo (scope creep) |
|
|
491
|
+
| `/ez:plan-phase` | — | — | discuss-phase (phase touches auth/DB/payment/security area) |
|
|
492
|
+
| `/ez:release medium` | — | — | verify-work |
|
|
493
|
+
| `/ez:release enterprise` | — | — | verify-work → audit-milestone → arch-review |
|
|
494
|
+
| `/ez:progress` | health check (silent) | — | — |
|
|
495
|
+
|
|
496
|
+
**Override flags:**
|
|
497
|
+
|
|
498
|
+
| Flag | Effect |
|
|
499
|
+
|------|--------|
|
|
500
|
+
| `--no-auto` | Disable all auto-invocations for that run |
|
|
501
|
+
| `--verbose` | Show detail for every auto-invocation step |
|
|
502
|
+
| `--skip-discussion` | Skip only the auto discuss-phase trigger |
|
|
503
|
+
|
|
504
|
+
Disable globally: set `"smart_orchestration": { "enabled": false }` in `.planning/config.json`.
|
|
505
|
+
|
|
506
|
+
---
|
|
507
|
+
|
|
508
|
+
## Guards & Safety
|
|
509
|
+
|
|
510
|
+
EZ Agents includes 6 runtime guards for safety and quality:
|
|
511
|
+
|
|
512
|
+
| Guard | Purpose |
|
|
513
|
+
|-------|---------|
|
|
514
|
+
| **Autonomy Guard** | Prevents unauthorized autonomous actions |
|
|
515
|
+
| **Context Budget Guard** | Monitors token usage (50%/70%/80% thresholds) |
|
|
516
|
+
| **Hallucination Guard** | Detects AI hallucinations and fabrications |
|
|
517
|
+
| **Hidden State Guard** | Prevents hidden state and context loss |
|
|
518
|
+
| **Team Overhead Guard** | Prevents team coordination overhead |
|
|
519
|
+
| **Tool Sprawl Guard** | Prevents tool proliferation |
|
|
520
|
+
|
|
521
|
+
### Context Budget Thresholds
|
|
522
|
+
|
|
523
|
+
```javascript
|
|
524
|
+
const THRESHOLDS = {
|
|
525
|
+
INFO: 50, // Quality degradation begins
|
|
526
|
+
WARNING: 70, // Efficiency mode engaged
|
|
527
|
+
ERROR: 80 // Hard stop
|
|
528
|
+
};
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
---
|
|
532
|
+
|
|
533
|
+
## Project Structure
|
|
534
|
+
|
|
535
|
+
### Codebase Layout
|
|
536
|
+
|
|
537
|
+
```
|
|
538
|
+
ez-agents/
|
|
539
|
+
├── bin/ # CLI entry points
|
|
540
|
+
│ ├── install.ts # Main installer (multi-runtime)
|
|
541
|
+
│ ├── update.ts # Update command
|
|
542
|
+
│ ├── lib/ # 98 core library modules (.ts)
|
|
543
|
+
│ │ ├── core.ts # Shared utilities, model profiles
|
|
544
|
+
│ │ ├── config.ts # Config CRUD
|
|
545
|
+
│ │ ├── phase.ts # Phase operations
|
|
546
|
+
│ │ ├── state.ts # STATE.md operations
|
|
547
|
+
│ │ ├── roadmap.ts # ROADMAP.md parsing
|
|
548
|
+
│ │ ├── model-provider.ts # Multi-model API
|
|
549
|
+
│ │ ├── safe-exec.ts # Command injection prevention
|
|
550
|
+
│ │ ├── context-manager.ts # Context assembly
|
|
551
|
+
│ │ └── ...
|
|
552
|
+
│ └── guards/ # 6 runtime guards
|
|
553
|
+
├── commands/ # Command handlers
|
|
554
|
+
│ └── ez/ # 17 agent command templates (.md)
|
|
555
|
+
├── ez-agents/ # Packaged runtime
|
|
556
|
+
│ ├── bin/
|
|
557
|
+
│ │ ├── ez-tools.ts # CLI router (160+ atomic commands)
|
|
558
|
+
│ │ ├── lib/ # 81 library modules
|
|
559
|
+
│ │ └── guards/ # 6 guards
|
|
560
|
+
│ ├── templates/ # 34 templates
|
|
561
|
+
│ ├── workflows/ # 40 workflow definitions
|
|
562
|
+
│ └── references/ # Reference documentation
|
|
563
|
+
├── agents/ # 10 agent definitions (.md)
|
|
564
|
+
├── skills/ # 229 skill definitions
|
|
565
|
+
│ ├── stack/ # Tech stack skills
|
|
566
|
+
│ ├── testing/ # Testing skills
|
|
567
|
+
│ ├── operational/ # Operational skills
|
|
568
|
+
│ └── observability/ # Observability skills
|
|
569
|
+
├── hooks/ # Git hooks (Husky)
|
|
570
|
+
├── tests/ # Test suite (307 tests)
|
|
571
|
+
│ ├── unit/ # Unit tests
|
|
572
|
+
│ ├── integration/ # Integration tests
|
|
573
|
+
│ ├── e2e/ # End-to-end tests
|
|
574
|
+
│ └── critical-paths/ # Critical path tests
|
|
575
|
+
├── docs/ # Documentation
|
|
576
|
+
├── .github/ # GitHub Actions workflows
|
|
577
|
+
└── .planning/ # Project planning artifacts
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
### Key Directories
|
|
581
|
+
|
|
582
|
+
- **`bin/`** — TypeScript source code for CLI and core library
|
|
583
|
+
- **`ez-agents/`** — Packaged runtime installed to AI config directories
|
|
584
|
+
- **`agents/`** — Agent definitions with tool permissions and color coding
|
|
585
|
+
- **`skills/`** — Domain-specific knowledge and best practices
|
|
586
|
+
- **`tests/`** — Comprehensive test suite (67% passing, target 100%)
|
|
587
|
+
- **`docs/`** — Architecture, deployment, and troubleshooting guides
|
|
588
|
+
|
|
589
|
+
---
|
|
590
|
+
|
|
591
|
+
## Testing
|
|
592
|
+
|
|
593
|
+
### Test Structure
|
|
594
|
+
|
|
595
|
+
- **307 total tests** across the codebase
|
|
596
|
+
- **206 passing (67%)** — Target: 100%
|
|
597
|
+
- **101 failing** — Being addressed in ongoing development
|
|
598
|
+
|
|
599
|
+
### Test Categories
|
|
600
|
+
|
|
601
|
+
| Category | Count | Purpose |
|
|
602
|
+
|----------|-------|---------|
|
|
603
|
+
| **Unit Tests** | 150+ | Individual module testing |
|
|
604
|
+
| **Integration Tests** | 50+ | Multi-module coordination |
|
|
605
|
+
| **E2E Tests** | 30+ | Full workflow validation |
|
|
606
|
+
| **Critical Paths** | 40+ | Core functionality guarantees |
|
|
607
|
+
| **Property-Based** | 20+ | Invariant validation |
|
|
608
|
+
| **Performance** | 10+ | Benchmark and regression |
|
|
609
|
+
| **Specialized** | 7+ | State, context, analytics, finops, security |
|
|
610
|
+
|
|
611
|
+
### Running Tests
|
|
612
|
+
|
|
613
|
+
```bash
|
|
614
|
+
# Run all tests
|
|
615
|
+
npm test
|
|
616
|
+
|
|
617
|
+
# Run with coverage
|
|
618
|
+
npm run test:coverage
|
|
619
|
+
|
|
620
|
+
# Run specific category
|
|
621
|
+
npm test -- tests/unit/
|
|
622
|
+
npm test -- tests/integration/
|
|
623
|
+
npm test -- tests/e2e/
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
---
|
|
627
|
+
|
|
628
|
+
## Contributing
|
|
629
|
+
|
|
630
|
+
### Development Setup
|
|
631
|
+
|
|
632
|
+
```bash
|
|
633
|
+
# Clone repository
|
|
634
|
+
git clone https://github.com/howlil/ez-agents.git
|
|
635
|
+
cd ez-agents
|
|
636
|
+
|
|
637
|
+
# Install dependencies
|
|
638
|
+
npm install
|
|
639
|
+
|
|
640
|
+
# Build project
|
|
641
|
+
npm run build
|
|
642
|
+
|
|
643
|
+
# Run tests
|
|
644
|
+
npm test
|
|
645
|
+
|
|
646
|
+
# Link for local development
|
|
647
|
+
npm link
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
### Code Quality
|
|
651
|
+
|
|
652
|
+
```bash
|
|
653
|
+
# Type checking
|
|
654
|
+
npm run typecheck
|
|
655
|
+
|
|
656
|
+
# Linting
|
|
657
|
+
npm run lint
|
|
658
|
+
npm run lint:fix
|
|
659
|
+
|
|
660
|
+
# Format code
|
|
661
|
+
npm run format
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
### Pull Request Process
|
|
665
|
+
|
|
666
|
+
1. Create feature branch from `main`
|
|
667
|
+
2. Make changes with tests
|
|
668
|
+
3. Ensure all checks pass (CI, tests, linting)
|
|
669
|
+
4. Submit PR with clear description
|
|
670
|
+
5. Address review feedback
|
|
671
|
+
6. Merge after approval
|
|
672
|
+
|
|
673
|
+
### Documentation
|
|
674
|
+
|
|
675
|
+
- **API Reference:** Auto-generated with TypeDoc
|
|
676
|
+
- **Architecture:** Detailed system design in `docs/`
|
|
677
|
+
- **Contributing:** Guidelines in `CONTRIBUTING.md`
|
|
678
|
+
- **Changelog:** Follows [Keep a Changelog](https://keepachangelog.com/)
|
|
679
|
+
|
|
680
|
+
---
|
|
681
|
+
|
|
682
|
+
## Changelog
|
|
683
|
+
|
|
684
|
+
### [5.0.0] - 2026-03-28
|
|
685
|
+
|
|
686
|
+
**Major Release: Complete TypeScript & OOP Transformation**
|
|
687
|
+
|
|
688
|
+
**Highlights:**
|
|
689
|
+
- ✅ TypeScript migration complete (98 modules)
|
|
690
|
+
- ✅ OOP architecture with 6 design patterns
|
|
691
|
+
- ✅ Zero TypeScript errors (586 → 0)
|
|
692
|
+
- ✅ 100% type coverage achieved
|
|
693
|
+
- ✅ Product discovery workflow added
|
|
694
|
+
- ✅ 10x engineer metrics tracking
|
|
695
|
+
- ✅ 229+ skills system
|
|
696
|
+
|
|
697
|
+
**New Features:**
|
|
698
|
+
- Product Discovery workflow with user personas, metrics, and RICE scoring
|
|
699
|
+
- Template validation module for output consistency
|
|
700
|
+
- Skill system reference documentation
|
|
701
|
+
- Workflow metrics tracking system
|
|
702
|
+
- Workflow versioning with migrations
|
|
703
|
+
- Standardized argument parsing (TypeScript)
|
|
704
|
+
- 5 new workflows (refactor, security, rollback, dependency-audit, accessibility-audit)
|
|
705
|
+
- Reference indices for templates, workflows, and agents
|
|
706
|
+
|
|
707
|
+
**System Health:** 7.1/10 → 8.0/10 (+13%)
|
|
708
|
+
|
|
709
|
+
See [CHANGELOG.md](CHANGELOG.md) for complete history.
|
|
710
|
+
|
|
711
|
+
---
|
|
712
|
+
|
|
713
|
+
## License
|
|
714
|
+
|
|
715
|
+
MIT License — see [LICENSE](LICENSE) for details.
|
|
716
|
+
|
|
717
|
+
---
|
|
718
|
+
|
|
719
|
+
## Support
|
|
720
|
+
|
|
721
|
+
- **Documentation:** [API Reference](https://howlil.github.io/ez-agents/api/)
|
|
722
|
+
- **Issues:** [GitHub Issues](https://github.com/howlil/ez-agents/issues)
|
|
723
|
+
- **Discussions:** [GitHub Discussions](https://github.com/howlil/ez-agents/discussions)
|
|
724
|
+
- **Email:** Support available via GitHub
|
|
725
|
+
|
|
726
|
+
---
|
|
727
|
+
|
|
728
|
+
<div align="center">
|
|
729
|
+
|
|
730
|
+
**Built with ❤️ by the EZ Agents Team**
|
|
731
|
+
|
|
732
|
+
[Top](#ez-agents)
|
|
733
|
+
|
|
734
|
+
</div>
|