@defai.digital/automatosx 5.3.4 → 5.3.7

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.
Files changed (8) hide show
  1. package/CHANGELOG.md +237 -0
  2. package/README.md +45 -7
  3. package/dist/index.js +98 -6
  4. package/dist/index.js.map +1 -1
  5. package/dist/version.json +2 -2
  6. package/examples/AGENTS_INFO.md +364 -377
  7. package/package.json +2 -5
  8. package/version.json +2 -2
package/examples/AGENTS_INFO.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # AutomatosX Agent Directory
2
2
 
3
- **v5.3.4 Update**: Team-based configuration complete. Best practices guide added.
3
+ **v5.3.6 Update**: Bob & Frank upgraded to depth 1 for specialist consultation. Daisy configuration clarified.
4
4
 
5
5
  AutomatosX agents have **human-friendly names** to make them easier to remember and use. Each agent has both a technical role name and a memorable display name.
6
6
 
@@ -38,340 +38,382 @@ Instead of directly commanding agents with slash commands, **let Claude Code coo
38
38
 
39
39
  ---
40
40
 
41
- ## 🎯 v5.0.12: Agent Governance & Delegation Controls
41
+ ## 🎯 Agent Classification by Delegation Strategy (v5.3.5)
42
42
 
43
- **Key Changes**:
44
- - ✅ **Role Ownership**: Quality owns code-review/debugging, Security owns security-audit
45
- - ✅ **Delegation Depth**: Most agents (1), Research only (0)
46
- - ✅ **Smart Ability Loading**: `abilitySelection` reduces prompt tokens by 30-50%
47
- - ✅ **Role-Specific Stages**: 8 unique workflow sequences
48
- - ✅ **No Cycles**: maxDelegationDepth: 1 prevents re-delegation
43
+ AutomatosX uses a **tiered delegation architecture** to orchestrate complex workflows while preventing delegation cycles.
49
44
 
50
- **Agent Categories by Delegation Depth**:
51
- - **Implementers** (depth 1): backend, frontend, fullstack, mobile, devops, security, design, writer
52
- - **Data Specialists** (depth 1): data (engineer), data-scientist
53
- - **Quality** (depth 1): quality (can delegate fixes to implementers)
54
- - **Coordinators** (depth 1): product, ceo, cto (delegate to implementers)
55
- - **Research** (depth 0): researcher (executes directly, no delegation)
45
+ ### Tier 1: Strategic Coordinators (Depth 3) 🎖️
56
46
 
57
- ## 🚀 Quick Overview: 15 Agents, 5 Teams, 3 Providers
47
+ **Purpose**: Orchestrate complex multi-layer workflows across teams and domains.
58
48
 
59
- AutomatosX agents are organized into **5 professional teams**, each optimized with the best AI provider for their domain:
49
+ | Agent | Display Name | Why Depth 3? | Typical Workflow |
50
+ |-------|--------------|--------------|------------------|
51
+ | **cto** | Tony | Cross-team technical initiatives | Strategy → Team Coordination → Implementation |
52
+ | **devops** | Oliver | Multi-stage deployment pipelines | Planning → Build → Test → Deploy → Monitor |
53
+ | **data-scientist** | Dana | End-to-end ML pipelines | Data → Feature → Model → Deploy → Monitor |
60
54
 
61
- | Team | Primary Provider | Agent Count | Expertise |
62
- |------|------------------|-------------|-----------|
63
- | **💻 Engineering Team** | 🟣 **Claude** (claude-code) | 6 | Backend, frontend, fullstack, mobile, DevOps, security |
64
- | **💾 Data Team** | 🔵 **Gemini** (gemini-cli) | 2 | Data engineering, data science & ML |
65
- | **🎯 Quality Team** | 🟣 **Claude** (claude-code) | 1 | Code review, debugging, testing (sole ownership) |
66
- | **🎨 Content Team** | Various | 2 | UX/UI design, technical documentation |
67
- | **📊 Leadership Team** | Various | 4 | CEO, CTO, Product Management, research & feasibility analysis |
55
+ **Delegation Pattern**:
56
+ - **Layer 1**: Strategic planning and coordination
57
+ - **Layer 2**: Team/domain delegation
58
+ - **Layer 3**: Specialist execution
68
59
 
69
- ### 🛡️ Intelligent 3-Layer Fallback System
60
+ **Example Workflow**:
61
+ ```
62
+ Tony (CTO): "Implement microservices architecture"
63
+ └─> Oliver (DevOps): "Set up K8s infrastructure"
64
+ └─> Bob (Backend): "Create service templates"
65
+ └─> Steve (Security): "Review security configs"
66
+ ```
70
67
 
71
- Each agent uses a **smart fallback strategy** to ensure maximum reliability:
68
+ ---
72
69
 
73
- 1. **Primary Provider**: Team-optimized AI (🟢 OpenAI / 🟣 Claude / 🔵 Gemini)
74
- 2. **Fallback Provider**: Agent-specific backup (configured per agent)
75
- 3. **Router Fallback**: Auto-routing through all available providers (priority-based)
70
+ ### Tier 2: Tactical Coordinators (Depth 1-2) 🎯
76
71
 
77
- **Example**: If an Engineering agent (primary: claude-code) encounters an issue:
78
- - ✅ Try Claude first (primary: `claude-code`)
79
- - ✅ Fall back to OpenAI (configured fallback: `openai`)
80
- - ✅ Try Gemini (router fallback: `gemini-cli`)
72
+ **Purpose**: Coordinate work within their domain, with limited cross-domain delegation.
81
73
 
82
- This ensures **99.9% uptime** even if one provider has issues!
74
+ | Agent | Display Name | Depth | Role | Why This Depth? |
75
+ |-------|--------------|-------|------|-----------------|
76
+ | **quality** | Queenie | **2** | QA Engineer | Needs to coordinate complex multi-layer testing workflows |
77
+ | **product** | Paris | 1 | Product Manager | Delegates to implementers, no sub-delegation needed |
78
+ | **fullstack** | Felix | 1 | Full-stack Dev | Handles end-to-end features, occasional specialist help |
79
+ | **mobile** | Maya | 1 | Mobile Dev | Mobile-specific work, backend/design delegation |
80
+ | **ceo** | Eric | 1 | Business Strategy | Strategic direction, delegates execution |
81
+ | **creative-marketer** | Cynthia | 1 | Creative Marketing | Marketing campaigns, content delegation |
83
82
 
84
- ## Why Names?
83
+ **Delegation Pattern**:
84
+ - **Depth 2**: Coordinator → Implementer → Specialist
85
+ - **Depth 1**: Coordinator → Implementer (no sub-delegation)
85
86
 
86
- Research shows humans remember names better than roles. Instead of remembering "backend engineer", you can just think "ask Bob".
87
+ **Example Workflow (Depth 2 - Queenie)**:
88
+ ```
89
+ Queenie (Quality): "Comprehensive E2E testing with security audit"
90
+ └─> Bob (Backend): "Implement API tests"
91
+ └─> Steve (Security): "Audit security test coverage"
92
+ └─> Frank (Frontend): "Implement UI tests"
93
+ └─> Debbee (Design): "Validate visual regression"
94
+ ```
87
95
 
88
- ## Agent Directory
96
+ **Example Workflow (Depth 1 - Paris)**:
97
+ ```
98
+ Paris (Product): "Build user authentication feature"
99
+ └─> Bob (Backend): "Implement auth API" [Stops here]
100
+ └─> Frank (Frontend): "Implement login UI" [Stops here]
101
+ ```
89
102
 
90
- ### 💻 Engineering Team (Implementers)
103
+ ---
91
104
 
92
- **maxDelegationDepth: 1** - Can delegate once for cross-domain needs, no re-delegation
105
+ ### Tier 3: Pure Implementers (Depth 0) ⚙️
93
106
 
94
- | Name | Agent | Expertise | Best For | Primary | Fallback | Can Delegate To |
95
- |------|-------|-----------|----------|---------|----------|-----------------|
96
- | **Bob** | backend | API design, database modeling, caching | Backend development, microservices | 🟣 claude-code | 🟢 openai | frontend, data, security, quality, devops |
97
- | **Frank** | frontend | Component architecture, state management | Frontend development, React, accessibility | 🟣 claude-code | 🟢 openai | backend, design, security, quality, devops |
98
- | **Felix** | fullstack | End-to-end features, API integration, E2E testing | Full-stack development, cross-layer features | 🟣 claude-code | 🟢 openai | backend, frontend, design, devops, quality |
99
- | **Maya** | mobile | Native iOS/Android, React Native, Flutter | Mobile app development (native & cross-platform) | 🟣 claude-code | 🟢 openai | backend, design, devops, quality |
100
- | **Oliver** | devops | Infrastructure as code, CI/CD pipelines | DevOps, deployment, observability | 🟣 claude-code | 🟢 openai | backend, frontend, security, quality |
101
- | **Steve** | security | **SOLE OWNER** of security-audit | Security review, threat modeling | 🟢 openai | 🔵 gemini-cli | backend, frontend, devops, quality |
107
+ **Purpose**: Execute work directly with deep domain expertise, no delegation capability.
102
108
 
103
- ### 🎯 Quality Team (Coordinator Role)
109
+ | Agent | Display Name | Role | Why Depth 0? |
110
+ |-------|--------------|------|--------------|
111
+ | **backend** | Bob | Backend Engineer | Focus on backend execution, cross-domain via coordinators |
112
+ | **frontend** | Frank | Frontend Engineer | Focus on frontend execution |
113
+ | **data** | Daisy | Data Engineer | Focus on data pipeline execution |
114
+ | **design** | Debbee | UX/UI Designer | Focus on design execution |
115
+ | **security** | Steve | Security Engineer | Focus on security assessment |
116
+ | **writer** | Wendy | Technical Writer | Focus on documentation |
117
+ | **researcher** | Rodman | Researcher | Focus on research, recommend handoff |
104
118
 
105
- **maxDelegationDepth: 1** - Can delegate fixes back to implementers, no re-delegation
119
+ **Why No Delegation?**:
120
+ - ✅ Prevents delegation cycles
121
+ - ✅ Clearer responsibility boundaries
122
+ - ✅ Cross-domain needs handled by coordinators
123
+ - ✅ Focus on execution excellence
106
124
 
107
- | Name | Agent | Expertise | Best For | Primary | Fallback | Can Delegate To |
108
- |------|-------|-----------|----------|---------|----------|-----------------|
109
- | **Queenie** | quality | **SOLE OWNER** of code-review & debugging | Test planning, automation, quality gates | 🟢 openai | 🔵 gemini-cli | backend, frontend, security, devops, data |
125
+ **Example Workflow**:
126
+ ```
127
+ Bob (Backend): "Optimize database queries"
128
+ [Executes directly - no delegation]
129
+ ```
110
130
 
111
- ### 🎨 Content Team (Implementers)
131
+ ---
112
132
 
113
- **maxDelegationDepth: 1** - Can delegate once for cross-domain needs, no re-delegation
133
+ ## 📊 Quick Reference: Agent Distribution
114
134
 
115
- | Name | Agent | Expertise | Best For | Primary | Fallback | Can Delegate To |
116
- |------|-------|-----------|----------|---------|----------|-----------------|
117
- | **Debbee** | design | UX research, wireframes, design systems | UX design, prototyping, accessibility | 🔵 gemini-cli | 🟢 openai | frontend, writer, quality |
118
- | **Wendy** | writer | API docs, ADRs, release notes | Technical writing, documentation | 🟢 openai | 🟣 claude-code | backend, frontend, design, quality |
135
+ ### By Team and Depth
119
136
 
120
- ### 📊 Leadership Team (Coordinators)
137
+ | Team | Depth 3 | Depth 2 | Depth 1 | Depth 0 |
138
+ |------|---------|---------|---------|---------|
139
+ | **Engineering** | Oliver, Dana | - | Felix, Maya, **Bob**, **Frank** | - |
140
+ | **Core/Quality** | - | **Queenie** | - | - |
141
+ | **Business** | - | - | Paris, Eric | - |
142
+ | **Content** | - | - | - | Debbee, Wendy |
143
+ | **Data** | Dana | - | - | Daisy |
144
+ | **Security** | - | - | - | Steve |
145
+ | **Research** | - | - | - | Rodman |
146
+ | **Marketing** | - | - | Cynthia | - |
121
147
 
122
- **maxDelegationDepth: 1** - Delegate to implementers, focus on strategy, no re-delegation
148
+ ### Total: 16 Agents
123
149
 
124
- | Name | Agent | Expertise | Best For | Primary | Fallback | Can Delegate To |
125
- |------|-------|-----------|----------|---------|----------|-----------------|
126
- | **Paris** | product | User research, feature planning, prioritization | Product strategy, roadmap planning | 🔵 gemini-cli | 🟣 claude-code | backend, frontend, design, writer, quality |
127
- | **Eric** | ceo | Business strategy, market analysis, vision | Strategic decisions, organizational leadership | 🔵 gemini-cli | 🟣 claude-code | paris, tony, all agents |
128
- | **Tony** | cto | Architecture governance, tech strategy, innovation | Technology roadmap, platform decisions | 🟢 openai | 🟣 claude-code | backend, frontend, devops, security, quality |
150
+ - **3 Strategic Coordinators** (Depth 3): Tony, Oliver, Dana
151
+ - **6 Tactical Coordinators** (Depth 1-2): Queenie (2), Paris, Felix, Maya, Eric, Cynthia
152
+ - **2 Tactical Implementers** (Depth 1): Bob, Frank ⭐ NEW in v5.3.6
153
+ - **5 Pure Implementers** (Depth 0): Daisy, Debbee, Steve, Wendy, Rodman
129
154
 
130
- ### 🔬 Research Team (Specialist)
155
+ ---
131
156
 
132
- **maxDelegationDepth: 0** - Execute research work directly, no delegation
157
+ ## 🚀 How Delegation Works
133
158
 
134
- | Name | Agent | Expertise | Best For | Primary | Fallback | Can Delegate To |
135
- |------|-------|-----------|----------|---------|----------|-----------------|
136
- | **Rodman** | researcher | Idea validation, feasibility analysis | Research reports, literature review | 🟢 openai | 🔵 gemini-cli | None (depth: 0) |
159
+ ### Understanding Delegation Depth
137
160
 
138
- ### 💾 Data Team (Specialists)
161
+ **Delegation Depth** controls how many layers of work coordination an agent can orchestrate:
139
162
 
140
- **maxDelegationDepth: 1** - Can delegate once for cross-domain needs, no re-delegation
163
+ - **Depth 0**: Do it yourself, no delegation
164
+ - **Depth 1**: Can delegate to others, but they can't delegate further
165
+ - **Depth 2**: Can delegate to others, who can then delegate to specialists
166
+ - **Depth 3**: Can orchestrate complex multi-layer workflows across multiple teams
141
167
 
142
- | Name | Agent | Expertise | Best For | Primary | Fallback | Can Delegate To |
143
- |------|-------|-----------|----------|---------|----------|-----------------|
144
- | **Daisy** | data | ETL pipelines, data infrastructure, SQL optimization | Data engineering, data pipelines | 🔵 gemini-cli | 🟣 claude-code | backend, security, quality |
145
- | **Dana** | data-scientist | Statistical analysis, ML modeling, data visualization | Data science, analytics, predictive modeling | 🔵 gemini-cli | 🟣 claude-code | data, backend, quality |
168
+ ### Delegation Flow Examples
169
+
170
+ #### Example 1: Strategic Initiative (Depth 3)
171
+ ```
172
+ Tony (CTO): "Implement microservices architecture"
173
+ └─> Oliver (DevOps): "Set up K8s infrastructure" [Layer 1]
174
+ └─> Bob (Backend): "Create service templates" [Layer 2]
175
+ └─> Steve (Security): "Review configs" [Layer 3]
176
+ ```
177
+
178
+ #### Example 2: Quality Workflow (Depth 2)
179
+ ```
180
+ Queenie (Quality): "Comprehensive E2E testing with security audit"
181
+ └─> Bob (Backend): "Implement API tests" [Layer 1]
182
+ └─> Steve (Security): "Audit security coverage" [Layer 2]
183
+ └─> Frank (Frontend): "Implement UI tests" [Layer 1]
184
+ └─> Debbee (Design): "Validate visual" [Layer 2]
185
+ ```
186
+
187
+ #### Example 3: Tactical Coordination (Depth 1)
188
+ ```
189
+ Paris (Product): "Build user authentication feature"
190
+ └─> Bob (Backend): "Implement auth API" [Layer 1]
191
+ [Stops here - Bob cannot delegate further]
192
+ └─> Frank (Frontend): "Implement login UI" [Layer 1]
193
+ [Stops here - Frank cannot delegate further]
194
+ ```
195
+
196
+ #### Example 4: Pure Implementation (Depth 0)
197
+ ```
198
+ Bob (Backend): "Optimize database queries"
199
+ [Executes directly - no delegation allowed]
200
+ ```
146
201
 
147
202
  ---
148
203
 
149
- **Note**: General-purpose agents (assistant, coder, debugger, reviewer) have been moved to templates (`examples/templates/`) to prevent delegation cycles. Use `ax agent create` to add them when specifically needed for your project.
204
+ ## 🎯 Agent Selection Guide
205
+
206
+ ### Choose by Task Complexity
207
+
208
+ **Strategic/Multi-team Tasks** → Tony, Oliver, Dana (Depth 3)
209
+ - Cross-team initiatives
210
+ - Multi-phase deployments
211
+ - Complex ML pipelines
212
+
213
+ **Domain Coordination** → Queenie, Paris, Felix, Maya, Eric (Depth 1-2)
214
+ - Quality assurance workflows
215
+ - Feature planning
216
+ - Mobile app development
217
+ - Product strategy
218
+
219
+ **Direct Implementation** → Bob, Frank, Daisy, Debbee, Steve, Wendy, Rodman (Depth 0)
220
+ - Backend development
221
+ - Frontend development
222
+ - Data engineering
223
+ - Design work
224
+ - Security audits
225
+ - Documentation
226
+ - Research
227
+
228
+ ### Choose by Domain
229
+
230
+ | Domain | Implementation | Coordination | Strategy |
231
+ |--------|---------------|--------------|----------|
232
+ | **Backend** | Bob (0) | Felix (1) | Tony (3) |
233
+ | **Frontend** | Frank (0) | Felix (1) | Tony (3) |
234
+ | **Quality** | - | **Queenie (2)** | Tony (3) |
235
+ | **Infrastructure** | - | - | Oliver (3) |
236
+ | **Data Science** | Daisy (0) | - | Dana (3) |
237
+ | **Product** | - | Paris (1) | Eric (1) |
238
+ | **Design** | Debbee (0) | - | - |
239
+ | **Security** | Steve (0) | - | Tony (3) |
240
+ | **Mobile** | - | Maya (1) | Tony (3) |
150
241
 
151
- ## Provider Configuration
242
+ ---
152
243
 
153
- ### ✅ Best Practice: Model Parameters
244
+ ## 📋 Detailed Agent Directory
154
245
 
155
- **v5.0.11+ Recommendation**: Let provider CLIs use their optimized defaults
246
+ ### 💻 Engineering Team
156
247
 
157
- **What Changed**:
158
- - All `temperature` and `maxTokens` parameters have been **removed from default agents**
159
- - Provider CLIs (Claude, Gemini, OpenAI) use their own optimized settings
160
- - This gives agents **full access to provider capabilities** (Claude: 200K tokens, Gemini: 2M tokens)
248
+ **Provider**: 🟣 Claude (claude-code) primary, 🟢 OpenAI fallback
161
249
 
162
- **Why This Is Better**:
163
- 1. **No Artificial Limits**: Agents can generate complete, comprehensive answers
164
- 2. **Provider Optimization**: Each CLI is tuned for its model's strengths
165
- 3. **Simpler Configuration**: Less to maintain and understand
166
- 4. **Fewer Mistakes**: Can't accidentally limit powerful models to 4K tokens
250
+ #### Strategic Coordinators (Depth 3)
167
251
 
168
- **When to Add Parameters** (optional):
169
- - **Cost Control**: Set `maxTokens` to limit API usage for specific agents
170
- - **Determinism**: Set `temperature: 0` for QA/testing agents that need consistent output
171
- - **OpenAI Only**: Currently only OpenAI provider supports these parameters
252
+ | Name | Agent | Expertise | Best For | Delegation Capability |
253
+ |------|-------|-----------|----------|-----------------------|
254
+ | **Oliver** | devops | Infrastructure as code, CI/CD, K8s | Complex multi-stage deployments | 3 layers (Planning → Build → Deploy) |
255
+ | **Dana** | data-scientist | ML modeling, statistical analysis | End-to-end ML pipelines | 3 layers (Data → Train → Deploy) |
172
256
 
173
- **How to Add Parameters** (if needed):
174
- ```yaml
175
- # Example: Cost-controlled agent
176
- config:
177
- maxTokens: 2000 # Limit output length
257
+ #### Tactical Coordinators (Depth 1)
178
258
 
179
- # Example: Deterministic QA agent
180
- config:
181
- temperature: 0 # Consistent output
182
- ```
259
+ | Name | Agent | Expertise | Best For | Delegation Capability |
260
+ |------|-------|-----------|----------|-----------------------|
261
+ | **Felix** | fullstack | End-to-end features, API integration | Full-stack features | 1 layer (can delegate to specialists) |
262
+ | **Maya** | mobile | Native iOS/Android, React Native | Mobile app development | 1 layer (can delegate to backend/design) |
183
263
 
184
- **References**:
185
- - See `CLAUDE.md` § Provider Model Parameters for technical details
186
- - Track Gemini CLI support: [Issue #5280](https://github.com/google-gemini/gemini-cli/issues/5280)
264
+ #### Tactical Implementers (Depth 1) ⭐ NEW in v5.3.6
265
+
266
+ | Name | Agent | Expertise | Best For | Delegation Capability |
267
+ |------|-------|-----------|----------|-----------------------|
268
+ | **Bob** | backend | API design, database modeling, caching | Backend development | 1 layer (can consult security, design, quality) |
269
+ | **Frank** | frontend | React, component architecture, state mgmt | Frontend development | 1 layer (can consult design, security, quality) |
270
+
271
+ #### Pure Implementers (Depth 0)
272
+
273
+ | Name | Agent | Expertise | Best For | Delegation Capability |
274
+ |------|-------|-----------|----------|-----------------------|
275
+ | **Steve** | security | **SOLE OWNER** of security-audit | Security reviews, threat modeling | None (executes directly) |
187
276
 
188
277
  ---
189
278
 
190
- AutomatosX uses a **3-layer fallback system** for maximum reliability:
279
+ ### 🎯 Quality Team
191
280
 
192
- 1. **Primary Provider**: Each agent's preferred AI provider (configured in agent YAML)
193
- 2. **Fallback Provider**: Optional per-agent fallback (can be configured via `fallbackProvider` field)
194
- 3. **Router Fallback**: Auto-routing through multiple providers (OpenAI → Gemini)
281
+ **Provider**: 🟢 OpenAI (codex) primary, 🔵 Gemini fallback
195
282
 
196
- ### Supported AI Providers
283
+ #### Tactical Coordinator (Depth 2) ⭐ NEW in v5.3.5
197
284
 
198
- | Brand | CLI Tool | Best For |
199
- |-------|----------|----------|
200
- | 🟣 **Claude** | `claude` or `claude-code` | General purpose, coding, analysis, debugging |
201
- | 🟢 **OpenAI** | `codex` | Code generation, planning |
202
- | 🔵 **Gemini** | `gemini` | Creative tasks, multimodal |
285
+ | Name | Agent | Expertise | Best For | Delegation Capability |
286
+ |------|-------|-----------|----------|-----------------------|
287
+ | **Queenie** | quality | **SOLE OWNER** of code-review & debugging | Multi-layer QA workflows, test coordination | 2 layers (QA → Implementation → Specialist) |
203
288
 
204
- ### Current Provider Distribution
289
+ **Why Depth 2?**: Quality assurance requires coordinating complex workflows where implementers need to delegate to specialists (e.g., Backend implements tests → Security audits security aspects).
205
290
 
206
- | AI Provider | Agent Count | Agents |
207
- |-------------|-------------|--------|
208
- | 🔵 **Gemini** (gemini-cli) | 5 | Eric, Paris, Daisy, Dana, Debbee |
209
- | 🟣 **Claude** (claude-code) | 6 | Bob, Frank, Felix, Maya, Oliver |
210
- | 🟢 **OpenAI** (openai) | 4 | Tony, Wendy, Queenie, Steve, Rodman |
211
-
212
- ### Provider Selection Logic
213
-
214
- ```text
215
- Agent Request → Try Primary Provider (varies by team)
216
- ↓ (if fails)
217
- Try Fallback Provider (configured per agent)
218
- ↓ (if fails)
219
- Use Auto-Routing Priority:
220
- 1. 🟢 OpenAI (priority 1)
221
- 2. 🔵 Gemini (priority 2)
222
- 3. 🟣 Claude (priority 3)
223
- ```
291
+ ---
224
292
 
225
- **Example 1**: If Sofia (Core Team: primary 🟢 **OpenAI**, fallback 🟣 **Claude**) encounters an error:
293
+ ### 💾 Data Team
226
294
 
227
- 1. Try 🟢 **OpenAI** first
228
- 2. If fails, try fallback 🟣 **Claude**
229
- 3. If still fails, router tries 🔵 **Gemini** (remaining provider)
295
+ **Provider**: 🔵 Gemini (gemini-cli) primary, 🟣 Claude fallback
230
296
 
231
- **Example 2**: If Bob (Engineering: primary 🟣 **Claude**, fallback 🟢 **OpenAI**) encounters an error:
297
+ #### Strategic Coordinator (Depth 3)
232
298
 
233
- 1. Try 🟣 **Claude** first
234
- 2. If fails, try fallback 🟢 **OpenAI**
235
- 3. If still fails, router tries 🔵 **Gemini** (remaining provider)
299
+ | Name | Agent | Expertise | Best For | Delegation Capability |
300
+ |------|-------|-----------|----------|-----------------------|
301
+ | **Dana** | data-scientist | Statistical analysis, ML modeling | Complete ML pipelines | 3 layers (Data → Feature → Model → Deploy) |
236
302
 
237
- **Example 3**: If Eric (Business: primary 🔵 **Gemini**, fallback 🟣 **Claude**) encounters an error:
303
+ #### Pure Implementer (Depth 0)
238
304
 
239
- 1. Try 🔵 **Gemini** first
240
- 2. If fails, try fallback 🟣 **Claude**
241
- 3. If still fails, router tries 🟢 **OpenAI** (remaining provider)
305
+ | Name | Agent | Expertise | Best For | Delegation Capability |
306
+ |------|-------|-----------|----------|-----------------------|
307
+ | **Daisy** | data | ETL pipelines, data infrastructure | Data engineering | None (executes directly) |
242
308
 
243
- ### Customizing Provider Configuration
309
+ ---
244
310
 
245
- You can customize provider preferences for any agent:
311
+ ### 🎨 Content Team
246
312
 
247
- ```yaml
248
- # Example 1: Core Team configuration (OpenAI → Claude → Gemini)
249
- name: assistant
250
- displayName: Alex
251
- provider: openai # Primary: 🟢 OpenAI
252
- fallbackProvider: claude-code # Fallback: 🟣 Claude
253
-
254
- # Example 2: Engineering Team configuration (Claude → OpenAI → Gemini)
255
- name: backend
256
- displayName: Bob
257
- provider: claude # Primary: 🟣 Claude
258
- fallbackProvider: openai # Fallback: 🟢 OpenAI (using 'codex' CLI)
259
-
260
- # Example 3: Business Team configuration (Gemini → Claude → OpenAI)
261
- name: ceo
262
- displayName: Eric
263
- provider: gemini-cli # Primary: 🔵 Gemini
264
- fallbackProvider: claude # Fallback: 🟣 Claude
265
-
266
- # Example 4: Design Team configuration (Gemini → OpenAI → Claude)
267
- name: design
268
- displayName: Debbee
269
- provider: gemini-cli # Primary: 🔵 Gemini
270
- fallbackProvider: openai # Fallback: 🟢 OpenAI
271
-
272
- # Available provider options:
273
- # - claude or claude-code (🟣 Claude - both are Anthropic Claude)
274
- # - openai or codex (🟢 OpenAI - both use 'codex' CLI)
275
- # - gemini-cli or gemini (🔵 Gemini - both use 'gemini' CLI)
276
- ```
313
+ **Provider**: Various
277
314
 
278
- **Why choose each provider?**
315
+ #### Pure Implementers (Depth 0)
279
316
 
280
- - 🟣 **Claude**: Best for general reasoning, long-context tasks, detailed analysis, and coding
281
- - 🟢 **OpenAI**: Excellent for code generation, technical planning, and structured outputs
282
- - 🔵 **Gemini**: Great for creative tasks, multimodal processing, and strategic thinking
317
+ | Name | Agent | Expertise | Best For | Delegation Capability |
318
+ |------|-------|-----------|----------|-----------------------|
319
+ | **Debbee** | design | UX research, wireframes, design systems | UX/UI design | None (executes directly) |
320
+ | **Wendy** | writer | API docs, ADRs, release notes | Technical writing | None (executes directly) |
283
321
 
284
- ## Usage Examples
322
+ ---
285
323
 
286
- ### Using Agent Names
324
+ ### 📊 Leadership Team
287
325
 
288
- ```bash
289
- # Use the agent name from the table above
290
- automatosx run backend "Design a RESTful API for user management"
291
- automatosx run frontend "Create a React login component"
292
- automatosx run security "Review this authentication code"
293
- ```
326
+ **Provider**: Various
294
327
 
295
- ### Using Display Names (Human-Friendly)
328
+ #### Strategic Coordinator (Depth 3)
296
329
 
297
- ```bash
298
- # More memorable! Use the human-friendly display name
299
- automatosx run Bob "Design a RESTful API for user management"
300
- automatosx run Frank "Create a React login component"
301
- automatosx run Felix "Build an end-to-end user registration feature"
302
- automatosx run Maya "Create a mobile app login screen for iOS and Android"
303
- automatosx run Steve "Review this authentication code"
330
+ | Name | Agent | Expertise | Best For | Delegation Capability |
331
+ |------|-------|-----------|----------|-----------------------|
332
+ | **Tony** | cto | Architecture governance, tech strategy | Technology roadmap, platform decisions | 3 layers (Strategy → Team → Implementation) |
304
333
 
305
- # Quick help from experts
306
- automatosx run Eric "Should we prioritize mobile or web?"
307
- automatosx run Tony "What's our cloud migration strategy?"
308
- automatosx run Paris "How should we price this feature?"
334
+ #### Tactical Coordinators (Depth 1)
309
335
 
310
- # Get insights
311
- automatosx run Daisy "Build an ETL pipeline for user data"
312
- automatosx run Dana "Analyze our user engagement trends with ML models"
313
- automatosx run Debbee "Review this dashboard design"
314
- ```
336
+ | Name | Agent | Expertise | Best For | Delegation Capability |
337
+ |------|-------|-----------|----------|-----------------------|
338
+ | **Eric** | ceo | Business strategy, market analysis | Strategic decisions, organizational leadership | 1 layer (can delegate execution) |
339
+ | **Paris** | product | User research, feature planning | Product strategy, roadmap planning | 1 layer (can delegate to implementers) |
315
340
 
316
- ## Complete Agent List
317
-
318
- ### Old Version (v3.x) Name Mapping
319
-
320
- For reference, here are the names from AutomatosX v3.x:
321
-
322
- | v4.0 Name | v3.x Name | Agent |
323
- |-----------|-----------|-------|
324
- | Alex | Alex | assistant |
325
- | Sofia | - | coder (new) |
326
- | Ryan | - | reviewer (new) |
327
- | Danny | - | debugger (new) |
328
- | Wendy | - | writer (new) |
329
- | Bob | Bob | backend |
330
- | Frank | Frank | frontend |
331
- | Oliver | Oliver | devops |
332
- | Steve | Steve | security |
333
- | Queenie | Queenie | quality |
334
- | Eric | Eric | ceo |
335
- | Tony | Tony | cto |
336
- | Paris | Paris | product |
337
- | Daisy | Daisy | data |
338
- | Debbee | Debbee | design |
339
-
340
- ### Additional Agents from v3.x
341
-
342
- These agents are available in v3.x but not yet ported to v4.0:
343
-
344
- - **Adrian** - Architect (Solution Architect)
345
- - **Anna** - Analyst (Business Analyst)
346
- - **Flora** - CFO (Chief Financial Officer)
347
- - **Doris** - Docs (Documentation Specialist)
348
- - **Emily** - Edge (Edge Computing Engineer)
349
- - **Louis** - Legal (Legal Counsel)
350
- - **Maggie** - Marketer (Marketing Manager)
351
- - **Nicolas** - Network (Network Engineer)
352
- - **Quian** - Quantum (Quantum Computing Specialist)
341
+ ---
353
342
 
354
- ## Customizing Agents
343
+ ### 🔬 Research & Specialist Teams
355
344
 
356
- You can customize any agent or create new ones:
345
+ #### Pure Implementer (Depth 0)
357
346
 
358
- ```bash
359
- # Copy an example agent
360
- cp examples/agents/backend.yaml .automatosx/agents/my-backend.yaml
347
+ | Name | Agent | Expertise | Best For | Delegation Capability |
348
+ |------|-------|-----------|----------|-----------------------|
349
+ | **Rodman** | researcher | Idea validation, feasibility analysis | Research reports, literature review | None (recommends handoff) |
361
350
 
362
- # Edit the profile
363
- vim .automatosx/agents/my-backend.yaml
364
- ```
351
+ #### Tactical Coordinator (Depth 1)
365
352
 
366
- Change the `displayName` field to give your agent a memorable name:
353
+ | Name | Agent | Expertise | Best For | Delegation Capability |
354
+ |------|-------|-----------|----------|-----------------------|
355
+ | **Cynthia** | creative-marketer | GenAI prompting, digital marketing | Marketing campaigns, content creation | 1 layer (can delegate content work) |
367
356
 
368
- ```yaml
369
- name: my-backend
370
- displayName: MyBob # Your custom name!
371
- role: Custom Backend Engineer
372
- ```
357
+ ---
358
+
359
+ ## 🛡️ Intelligent 3-Layer Fallback System
360
+
361
+ Each agent uses a **smart fallback strategy** to ensure maximum reliability:
362
+
363
+ 1. **Primary Provider**: Team-optimized AI (🟢 OpenAI / 🟣 Claude / 🔵 Gemini)
364
+ 2. **Fallback Provider**: Agent-specific backup (configured per agent)
365
+ 3. **Router Fallback**: Auto-routing through all available providers (priority-based)
366
+
367
+ **Example**: If an Engineering agent (primary: claude-code) encounters an issue:
368
+ - ✅ Try Claude first (primary: `claude-code`)
369
+ - ✅ Fall back to OpenAI (configured fallback: `openai`)
370
+ - ✅ Try Gemini (router fallback: `gemini-cli`)
371
+
372
+ This ensures **99.9% uptime** even if one provider has issues!
373
+
374
+ ---
375
+
376
+ ## 📝 Agent Governance Principles (v5.3.5)
377
+
378
+ ### When to Use Each Depth
373
379
 
374
- ## Tips for Remembering
380
+ **Depth 3** - Strategic Coordination
381
+ - ✅ Cross-team initiatives
382
+ - ✅ Multi-phase complex workflows
383
+ - ✅ Strategic technical decisions
384
+ - Example: CTO coordinating microservices migration
385
+
386
+ **Depth 2** - Tactical Multi-layer Coordination
387
+ - ✅ Domain-specific complex workflows
388
+ - ✅ Requires coordinating specialists
389
+ - ✅ Multi-stage quality/testing processes
390
+ - Example: QA coordinating comprehensive testing
391
+
392
+ **Depth 1** - Simple Coordination
393
+ - ✅ Single-layer delegation
394
+ - ✅ Coordinate within domain
395
+ - ✅ No sub-delegation needed
396
+ - Example: Product manager delegating to developers
397
+
398
+ **Depth 0** - Pure Implementation
399
+ - ✅ Deep domain expertise
400
+ - ✅ Execute directly
401
+ - ✅ No delegation complexity
402
+ - Example: Backend developer writing APIs
403
+
404
+ ### Adding New Agents
405
+
406
+ When creating agents, choose depth based on:
407
+
408
+ - **Scope**: Team-level (3), Domain-level (1-2), Task-level (0)
409
+ - **Coordination Need**: Multi-layer (2-3), Single-layer (1), None (0)
410
+ - **Decision Authority**: Strategic (3), Tactical (1-2), Implementation (0)
411
+
412
+ ---
413
+
414
+ ## Why Names?
415
+
416
+ Research shows humans remember names better than roles. Instead of remembering "backend engineer", you can just think "ask Bob".
375
417
 
376
418
  ### Mnemonic Devices
377
419
 
@@ -389,157 +431,102 @@ role: Custom Backend Engineer
389
431
  - **Dana** - "**D**ana does **D**ata science"
390
432
  - **Debbee** - "**D**ebbee **D**esigns beautifully"
391
433
 
392
- ### Team Analogy
393
-
394
- Think of AutomatosX like assembling your dream team:
395
-
396
- - Need backend work? **Call Bob**
397
- - UI problems? **Ask Frank**
398
- - Full-stack features? **Work with Felix**
399
- - Mobile apps? **Reach out to Maya**
400
- - Security concerns? **Talk to Steve**
401
- - Data pipelines? **Contact Daisy**
402
- - Data science & ML? **Collaborate with Dana**
403
- - Strategy questions? **Consult Eric**
404
- - Product decisions? **Meet with Paris**
405
- - Design feedback? **Chat with Debbee**
406
-
407
- ## Next Steps
408
-
409
- - Browse `examples/agents/` to see all agent profiles
410
- - Copy agents to `.automatosx/agents/` to use them
411
- - Customize agent personalities and abilities
412
- - Create your own agents with memorable names!
413
-
414
434
  ---
415
435
 
416
- ## 🎯 Agent Maintenance Principles (v5.0.11+)
417
-
418
- To prevent delegation cycles and maintain a clean agent ecosystem, AutomatosX follows these principles:
436
+ ## Usage Examples
419
437
 
420
- ### Core Principles
438
+ ### Using Agent Names
421
439
 
422
- 1. **Unique Responsibility**: Each default agent must have a clearly defined, non-overlapping responsibility area.
423
- 2. **Prevent Duplication**: No two agents should cover the same type of task.
424
- 3. **Prefer Specialization**: Default agents should be specialists, not generalists.
425
- 4. **Templates for Flexibility**: General-purpose agents should be templates, not defaults.
440
+ ```bash
441
+ # Use the agent name from the table above
442
+ ax run backend "Design a RESTful API for user management"
443
+ ax run frontend "Create a React login component"
444
+ ax run security "Review this authentication code"
445
+ ```
426
446
 
427
- ### Delegation Strategy
447
+ ### Using Display Names (Human-Friendly)
428
448
 
429
- **Broad-scope agents** (CEO, CTO, Product) are configured with:
430
- - `maxDelegationDepth: 1` - Limits multi-layer delegation
431
- - **Delegation evaluation guidance** in systemPrompt:
432
- ```
433
- Before delegating, evaluate:
434
- 1. Can I handle this with my expertise? If yes, do it yourself.
435
- 2. Does this require specialized skills? If yes, delegate to specialists.
436
- 3. Delegation should be intentional, not automatic.
437
- ```
449
+ ```bash
450
+ # More memorable! Use the human-friendly display name
451
+ ax run Bob "Design a RESTful API for user management"
452
+ ax run Frank "Create a React login component"
453
+ ax run Felix "Build an end-to-end user registration feature"
454
+ ax run Maya "Create a mobile app login screen for iOS and Android"
455
+ ax run Steve "Review this authentication code"
438
456
 
439
- ### Adding New Agents
457
+ # Quality coordination (NEW depth 2 capability)
458
+ ax run Queenie "Implement comprehensive E2E tests with security audit"
440
459
 
441
- When creating or modifying agents:
460
+ # Quick help from experts
461
+ ax run Eric "Should we prioritize mobile or web?"
462
+ ax run Tony "What's our cloud migration strategy?"
463
+ ax run Paris "How should we price this feature?"
442
464
 
443
- 1. **Check for overlaps**: Ensure the new agent doesn't duplicate existing agents
444
- 2. **Update team configuration**: Assign to appropriate team (core/engineering/business/design)
445
- 3. **Set delegation limits**: For coordinators, set `maxDelegationDepth: 1`
446
- 4. **Add delegation guidance**: Include evaluation criteria in systemPrompt
447
- 5. **Document responsibilities**: Update this file with the agent's clear scope
465
+ # Get insights
466
+ ax run Daisy "Build an ETL pipeline for user data"
467
+ ax run Dana "Analyze our user engagement trends with ML models"
468
+ ax run Debbee "Review this dashboard design"
469
+ ```
448
470
 
449
- ### Templates vs. Default Agents
471
+ ---
450
472
 
451
- **Default Agents** (`automatosx/agents/`):
452
- - Specialized roles with clear boundaries
453
- - Always available by default
454
- - Current: backend, frontend, devops, security, quality, data, product, design, writer, ceo, cto
473
+ ## Provider Configuration
455
474
 
456
- **Templates** (`examples/templates/`):
457
- - General-purpose or situational roles
458
- - Created on-demand with `ax agent create`
459
- - Current: assistant, fullstack-developer, code-reviewer, debugger, developer, analyst, designer, qa-specialist
475
+ ### Supported AI Providers
460
476
 
461
- ### How to Re-enable Template Agents
477
+ | Brand | CLI Tool | Best For |
478
+ |-------|----------|----------|
479
+ | 🟣 **Claude** | `claude` or `claude-code` | General purpose, coding, analysis, debugging |
480
+ | 🟢 **OpenAI** | `codex` | Code generation, planning |
481
+ | 🔵 **Gemini** | `gemini` | Creative tasks, multimodal |
462
482
 
463
- If your project genuinely needs a general-purpose agent (e.g., assistant, fullstack-developer), follow these steps:
483
+ ### Current Provider Distribution
464
484
 
465
- #### Evaluation Checklist
485
+ | AI Provider | Agent Count | Agents |
486
+ |-------------|-------------|--------|
487
+ | 🔵 **Gemini** (gemini-cli) | 5 | Eric, Paris, Daisy, Dana, Debbee |
488
+ | 🟣 **Claude** (claude-code) | 6 | Bob, Frank, Felix, Maya, Oliver, Tony |
489
+ | 🟢 **OpenAI** (openai) | 5 | Queenie, Steve, Wendy, Rodman, Cynthia |
466
490
 
467
- **Before creating a template agent, ask:**
468
- 1. ✅ Can specialized agents (backend, frontend, quality) handle this task?
469
- 2. ✅ Will this agent overlap with existing default agents?
470
- 3. ✅ Is this for a specific project phase or temporary need?
471
- 4. ✅ Have I read the template's "TEMPLATE ROLE NOTICE"?
491
+ ---
472
492
 
473
- **If all answers are satisfactory, proceed:**
493
+ ## Customizing Agents
474
494
 
475
- #### Step 1: Create from Template
495
+ You can customize any agent or create new ones:
476
496
 
477
497
  ```bash
478
- # Interactive creation (recommended)
498
+ # Create from template
479
499
  ax agent create my-assistant --template assistant --interactive
480
500
 
481
- # Or non-interactive
482
- ax agent create my-fullstack --template fullstack-developer \
483
- --display-name "Sofia" \
484
- --role "Full-stack Developer" \
485
- --team engineering
501
+ # Or copy an existing agent
502
+ cp examples/agents/backend.yaml .automatosx/agents/my-backend.yaml
503
+ vim .automatosx/agents/my-backend.yaml
486
504
  ```
487
505
 
488
- #### Step 2: Review Configuration
489
-
490
- After creation, review the agent YAML in `.automatosx/agents/`:
491
- - ✅ Check `maxDelegationDepth` (set to 1 for general-purpose agents)
492
- - ✅ Review delegation guidance in systemPrompt
493
- - ✅ Ensure abilities don't completely overlap with existing agents
494
-
495
- #### Step 3: Test for Delegation Cycles
496
-
497
- Run a test task and monitor delegation behavior:
498
- ```bash
499
- # Test the agent
500
- ax run my-assistant "Create a simple REST API"
506
+ Change the `displayName` field to give your agent a memorable name:
501
507
 
502
- # Watch for delegation patterns
503
- # ❌ Bad: Agent immediately delegates to backend/frontend
504
- # ✅ Good: Agent attempts task first, delegates only when necessary
508
+ ```yaml
509
+ name: my-backend
510
+ displayName: MyBob # Your custom name!
511
+ role: Custom Backend Engineer
512
+ maxDelegationDepth: 0 # Choose appropriate depth
505
513
  ```
506
514
 
507
- #### Step 4: Adjust if Needed
515
+ ---
508
516
 
509
- If delegation cycles occur:
510
- - Lower `maxDelegationDepth` to 1
511
- - Add stronger "do it yourself first" guidance in systemPrompt
512
- - Consider removing the agent and using specialized agents instead
517
+ ## Next Steps
513
518
 
514
- #### Step 5: Document Your Decision
519
+ - Browse `examples/agents/` to see all agent profiles
520
+ - Copy agents to `.automatosx/agents/` to use them
521
+ - Customize agent personalities and abilities
522
+ - Create your own agents with memorable names!
515
523
 
516
- Add a comment to your project's `CLAUDE.md`:
517
- ```markdown
518
- ## Custom Agents
524
+ **Pro tip**: You can list all available agents with:
519
525
 
520
- ### my-assistant (General Assistant)
521
- - **Why needed**: Handles cross-domain tasks during prototyping phase
522
- - **Overlap mitigation**: maxDelegationDepth=1, explicit self-evaluation
523
- - **Review date**: 2025-11-01
526
+ ```bash
527
+ ax list agents
524
528
  ```
525
529
 
526
- ### Preventing Delegation Cycles
527
-
528
- Common causes of infinite delegation:
529
- - ❌ Two generalists with overlapping skills
530
- - ❌ Agents with identical abilities but different names
531
- - ❌ No clear "stop condition" in delegation logic
532
-
533
- Solutions:
534
- - ✅ Move generalists to templates
535
- - ✅ Limit maxDelegationDepth for broad-scope agents
536
- - ✅ Add explicit delegation evaluation in systemPrompt
537
- - ✅ Prefer specialized agents with clear boundaries
538
-
539
530
  ---
540
531
 
541
- **Pro tip**: You can list all available agents with:
542
-
543
- ```bash
544
- automatosx list agents
545
- ```
532
+ **Note**: General-purpose agents (assistant, coder, debugger, reviewer) have been moved to templates (`examples/templates/`) to prevent delegation cycles. Use `ax agent create` to add them when specifically needed for your project.