agency-orchestrator 0.4.2 → 0.5.1

package/README.en.md

@@ -2,141 +2,146 @@
 
 **English** | [中文](./README.md)
 
-> **You're already paying for AI. Why do you need another API key just to run a workflow?**
+> **One sentence in, a full plan out — multiple AI roles collaborate automatically.**
 
 [![CI](https://github.com/jnMetaCode/agency-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/jnMetaCode/agency-orchestrator/actions)
 [![npm version](https://img.shields.io/npm/v/agency-orchestrator)](https://www.npmjs.com/package/agency-orchestrator)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
-**186 expert AI roles · Zero-code YAML orchestration · Use your existing subscription · No API key required**
+**One sentence → full plan · 211 expert AI roles · Zero-code YAML · 10 LLM providers · 7 need no API key**
 
-```
-Claude Max ✓  ChatGPT Plus ✓  GitHub Copilot ✓  Google Account (free) ✓  Ollama ✓
-```
+> **Note:** `ao compose --run` auto-detects your language. For English input, it uses [agency-agents](https://github.com/msitarzewski/agency-agents) (170+ English roles). Use `ao init --lang en` to download the English role library. **6 English workflow templates** are ready in `workflows/en/` — more coming in v0.6.
+
+> 📖 [Full Tutorial](https://dev.to/jnmetacode/agency-orchestrator-one-sentence-five-ai-agents-a-complete-plan-in-3-minutes-1ij6) — from install to real-world use in 10 minutes
 
 > If you find this useful, please **Star** it — helps others discover the project.
 
+<p align="center">
+  <img src="./demo.gif" alt="ao compose --run demo" width="700">
+</p>
+
 ---
 
-## Why Agency Orchestrator
+## One Sentence, Full Result
 
-**Sound familiar?**
+```bash
+ao compose "I'm a programmer looking to start a side hustle with AI content, target $3K/month, give me a complete plan" --run
+```
 
-- You want multiple AI agents to collaborate, but CrewAI/LangGraph require Python and defining every role from scratch
-- You set up the framework, then discover you **still need to get API keys, add credits, and manage quotas**
-- You're already paying $20/month for Claude Max / ChatGPT Plus / Copilot — but you can't use that subscription
+5 AI roles collaborate automatically:
 
-**Agency Orchestrator's answer:**
+```
+  Workflow: Programmer AI Side Hustle Plan
+  Steps: 5 | Model: claude-code
+  Roles: 🔭 Trend Researcher | 📱 Platform Analyst | 💰 Financial Planner | ✍️ Content Strategist | 📋 Execution Planner
+──────────────────────────────────────────────────
 
-Write one YAML file → 186 expert roles collaborate automatically → runs on your **existing subscription**.
+  ✅ 🔭 Trend Researcher   31.3s  → 6 niches compared by competition/ceiling/AI leverage
+  ✅ 📱 Platform Analyst    32.0s  → 6 platforms scored, recommends "YouTube + Newsletter" combo
+  ✅ 💰 Financial Planner   31.8s  → $3K/mo breakdown: course $1,800 + community $600 + consulting $600
+  ✅ ✍️ Content Strategist   44.6s  → 20 topics + 4 headline formulas + content SOP
+  ✅ 📋 Execution Planner   42.2s  → 90-day action plan, day-by-day
 
-> **Industry first: Every multi-agent framework out there (CrewAI, LangGraph, AutoGen, Dify, n8n, Agency Swarm, MetaGPT, Google ADK, OpenAI Agents SDK) requires API keys. Agency Orchestrator is the only one that lets you bring your subscription.**
+==================================================
+  Done: 5/5 steps | 182.1s | 6,493 tokens
+==================================================
+```
 
-### 30-Second Comparison
+**No code. No config. No role selection.** One sentence → AI auto-decomposes the task → matches roles from 211 experts → executes as DAG → outputs a complete plan.
 
-```python
-# CrewAI: ~50 lines of Python, define every role, API key required
-researcher = Agent(role="PM", goal="...", backstory="...(write it yourself)...")
-task = Task(description="...", agent=researcher)
-crew = Crew(agents=[researcher], tasks=[task])
-crew.kickoff()
-```
+### What Can You Build
 
-```yaml
-# Agency Orchestrator: 10 lines of YAML, 186 roles ready to go, no API key
-steps:
-  - id: analyze
-    role: "product/product-manager"   # expert prompt already written
-    task: "Analyze this PRD: {{prd_content}}"
+```bash
+ao compose "Analyze the feasibility of building an AI budgeting app" --run        # Startup feasibility
+ao compose "Compare Cursor, Windsurf, and Copilot — give me a recommendation" --run  # Tech comparison
+ao compose "Write a deep-dive article on AI Agent trends" --run                    # Long-form writing
+ao compose "Plan an AI education startup with $15K budget" --run                   # Business plan
+ao compose "PR code review covering security and performance" --run                # Code review
+ao compose "Design a pricing strategy for a SaaS product" --run                    # Pricing analysis
 ```
 
-| | CrewAI | LangGraph | AutoGen | **Agency Orchestrator** |
-|---|--------|-----------|---------|---------------------|
-| Language | Python | Python | Python | **YAML (zero code)** |
-| Roles | Write your own | Write your own | Write your own | **186 ready-to-use** |
-| API Key | Required | Required | Required | **6 providers need none** |
-| Dependencies | pip + LiteLLM + dozens | pip + LangChain | pip + AutoGen | **npm + 2 deps** |
-| Parallelism | Manager mode | Manual graph | Manual | **Auto DAG detection** |
-| Branching | None | Manual | Manual | **Condition expressions** |
-| Loops | None | Manual | Manual | **Declarative loop/exit** |
-| Resume | None | Checkpointers | None | **Built-in `--resume`** |
-| Price | Open-source + $25-99/mo | Open-source | Open-source | **Completely free** |
+Each scenario auto-matches a different combination of AI roles.
 
-## Get Started in 3 Steps
+---
 
-### Step 1: Try it in 5 seconds
+## Why Agency Orchestrator
 
-```bash
-npx agency-orchestrator demo
-```
+Chatting with one AI gives you one perspective. But any real decision needs product, engineering, finance, and marketing perspectives...
 
-4 AI roles collaborate on a story. No install, no config, no API key.
+**Agency Orchestrator = multiple AI experts working in parallel, then synthesized. One person vs. a whole team.**
 
-### Step 2: Run a real workflow with your subscription
+| | ChatGPT / Claude | CrewAI / LangGraph | **Agency Orchestrator** |
+|---|--------|-----------|---------------------|
+| Roles | 1 generalist | Write your own | **211 expert roles** |
+| Usage | Chat | Write Python | **One sentence / YAML** |
+| API key | — | Required | **7 providers need none** |
+| Dependencies | — | pip + dozens of packages | **npm + 2 deps** |
+| Parallelism | — | Manual graph | **Auto DAG detection** |
+| Price | Subscription | Open-source + API fees | **Completely free** |
 
-```bash
-npm install agency-orchestrator
-npx ao init                    # download 186 AI roles
+## Get Started in 3 Steps
 
-# Use your existing Claude Max subscription (no API key!)
-npx ao run workflows/story-creation.yaml --input premise="A time travel story"
-```
+### Step 1: Install
 
-Just set `provider: "claude-code"` in your YAML. No Claude? Use `gemini-cli` (free with Google account), `copilot-cli`, or `codex-cli`.
+```bash
+npm install -g agency-orchestrator
+```
 
-### Step 3: Use it inside your AI coding tool
+### Step 2: One sentence, go
 
 ```bash
-./scripts/install.sh           # one-command install for your AI tools
+# Use your existing Claude subscription (no API key needed)
+ao compose "Analyze the feasibility of building an AI budgeting app" --run --provider claude-code
+
+# Or use DeepSeek ($2 lasts forever)
+export DEEPSEEK_API_KEY="your-key"
+ao compose "Analyze the feasibility of building an AI budgeting app" --run
 ```
 
-Then tell Cursor / Claude Code / Copilot:
+### Step 3: Use built-in templates or integrate with AI coding tools
 
+```bash
+# 6 English workflow templates in workflows/en/
+ao run workflows/en/solo-founder-plan.yaml -i idea="AI-powered resume builder for job seekers"
+ao run workflows/en/pr-review.yaml -i pr_diff=@mypr.diff -i pr_description="Add auth middleware"
+ao run workflows/en/business-plan.yaml -i idea="B2B SaaS for remote-team project tracking"
 ```
-Run workflows/story-creation.yaml with premise="A time travel story"
-```
-
-It auto-parses YAML → loads roles → executes in DAG order → saves results.
 
-**Works with 14 AI coding tools** ([integration guides](./integrations/)): Claude Code · GitHub Copilot · Cursor · Windsurf · Kiro · Trae · Aider · Gemini CLI · Codex CLI · OpenCode · Qwen Code · DeerFlow 2.0 · Antigravity · OpenClaw
+Also works inside Cursor / Claude Code — just say "run a workflow." Supports **14 AI coding tools** ([integration guides](./integrations/)).
 
-## Demo: 4 AI Roles Write a Complete Story in 2 Minutes
+## More Real Demos
 
 ```
-$ ao run workflows/story-creation.yaml -i "premise=A programmer discovers AI replies with things it shouldn't know"
+$ ao compose "Analyze startup opportunities in short-form video" --run
 
-  Workflow: Short Story Creation
-  Steps: 4 | Concurrency: 2 | Model: deepseek-chat
+  Workflow: Short-Form Video Startup Opportunity Analysis
+  Steps: 6 | Concurrency: 2 | Model: deepseek-chat
+  Roles: 👔 CEO | 📊 Market Researcher | 🔍 User Researcher | 🧭 Product Manager | 📣 Marketing Lead | 💰 CFO
 ──────────────────────────────────────────────────
 
-  ── [1/4] story_structure (Narratologist) ──
-  Done | 14.9s | 1,919 tokens
-
-  ── [2/4] character_design (Psychologist) ──            ← parallel
-  Done | 65.5s | 4,016 tokens
-
-  ── [3/4] conflict_design (Narrative Designer) ──       ← parallel
-  Done | 65.5s | 3,607 tokens
-
-  ── [4/4] write_story (Content Creator) ──
-  Done | 33.9s | 5,330 tokens
+  ✅ 👔 CEO              12.7s   → Strategic direction & target user positioning
+  ✅ 📊 Market Researcher 45.2s   → 700M DAU data, competitive landscape analysis
+  ✅ 🔍 User Researcher   38.1s   → User personas, pain points, willingness to pay
+  ✅ 🧭 Product Manager   41.3s   → MVP feature list, content matrix, monetization paths
+  ✅ 📣 Marketing Lead    35.6s   → Cold start plan, ad strategy, user funnel
+  ✅ 💰 CFO              28.4s   → $200K startup, $550K first-year revenue, break-even analysis
 
 ==================================================
-  Completed: 4/4 steps | 114.3s | 14,872 tokens
+  Done: 6/6 steps | 233.0s | 65,191 tokens
 ==================================================
 ```
 
-Steps 2 and 3 run **in parallel** (auto-detected from DAG dependencies). Four specialized AI roles collaborate to produce a complete suspense short story.
+Of the 6 roles, Market Researcher and User Researcher **run in parallel** (auto-detected from DAG dependencies).
 
 ## How It Works
 
 ```yaml
 name: "Product Requirements Review"
-agents_dir: "agency-agents-zh"
+agents_dir: "agency-agents"      # or "agency-agents-zh" for Chinese roles
 
 llm:
-  provider: "deepseek"       # or: claude, openai, ollama
+  provider: "deepseek"          # No API key: claude-code / gemini-cli / copilot-cli / codex-cli / hermes-cli / ollama
   model: "deepseek-chat"
 
 concurrency: 2
@@ -170,10 +175,11 @@ steps:
 ```
 
 The engine automatically:
+
 1. Parses YAML → builds a **DAG** (directed acyclic graph)
 2. Detects parallelism — `tech_review` and `design_review` run concurrently
 3. Passes outputs between steps via `{{variables}}`
-4. Loads role definitions from [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) as system prompts
+4. Loads role definitions from [agency-agents](https://github.com/msitarzewski/agency-agents) (or [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh)) as system prompts
 5. Retries on failure (exponential backoff)
 6. Saves all outputs to `ao-output/`
 
@@ -183,97 +189,7 @@ analyze ──→ tech_review  ──→ summary
           (parallel)
 ```
 
-## Features
-
-### AI Workflow Composer
-
-Describe your workflow in one sentence — AI selects the right roles, designs the DAG, and generates a ready-to-run YAML:
-
-```bash
-ao compose "PR code review covering security and performance"
-```
-
-The AI will:
-1. Select matching roles from 186 available (e.g., Code Reviewer, Security Engineer, Performance Benchmarker)
-2. Design the DAG (3-way parallel → summary)
-3. Generate complete YAML with variable passing and task descriptions
-4. Save to `workflows/` — ready to `ao run`
-
-Supports `--provider` and `--model` flags (default: DeepSeek).
-
-### Condition Branching
-
-```yaml
-- id: tech_path
-  role: "engineering/engineering-sre"
-  task: "Technical evaluation: {{requirements}}"
-  depends_on: [classify]
-  condition: "{{job_type}} contains technical"
-
-- id: biz_path
-  role: "marketing/marketing-social-media-strategist"
-  task: "Business evaluation: {{requirements}}"
-  depends_on: [classify]
-  condition: "{{job_type}} contains business"
-
-- id: summary
-  depends_on: [tech_path, biz_path]
-  depends_on_mode: "any_completed"  # proceeds when ANY upstream completes
-```
-
-Supported operators: `contains`, `equals`, `not_contains`, `not_equals`.
-
-### Loop Iteration
-
-```yaml
-- id: write_draft
-  role: "marketing/marketing-content-creator"
-  task: "Write article: {{topic}}"
-  output: draft
-
-- id: brand_review
-  role: "design/design-brand-guardian"
-  task: "Review brand compliance: {{draft}}"
-  output: review_result
-  depends_on: [write_draft]
-  loop:
-    back_to: write_draft
-    max_iterations: 3
-    exit_condition: "{{review_result}} contains approved"
-```
-
-When the exit condition is not met, execution loops back to `back_to`. The `{{_loop_iteration}}` variable tracks the current round.
-
-### Resume & Iterate
-
-**Problem**: After `ao run` completes, all step outputs are lost. To tweak the final story, you'd have to re-run everything from scratch.
-
-**Solution**: `--resume` reloads previous outputs. `--from` specifies where to restart.
-
-```bash
-# Round 1: Normal run
-ao run workflows/story-creation.yaml -i premise="A time travel story"
-
-# Round 2: Characters feel flat — re-run from character_design
-ao run workflows/story-creation.yaml --resume last --from character_design
-
-# Round 3: Only rewrite the final prose
-ao run workflows/story-creation.yaml --resume last --from write_story
-
-# Round 4: Go back to a specific version
-ao run workflows/story-creation.yaml --resume ao-output/<dir>/ --from write_story
-```
-
-Each round creates a new timestamped output directory. All versions are preserved.
-
-| Scenario | Command |
-|----------|---------|
-| First run | `ao run workflow.yaml -i key=value` |
-| Re-run from a step | `ao run workflow.yaml --resume last --from <step-id>` |
-| Re-run only failed steps | `ao run workflow.yaml --resume last` |
-| Resume specific version | `ao run workflow.yaml --resume ao-output/<dir>/ --from <step-id>` |
-
-## 9 LLM Providers — 6 Need No API Key
+## 10 LLM Providers — 7 Need No API Key
 
 **Already paying for one of these? You're ready to go:**
 
@@ -282,8 +198,9 @@ Each round creates a new timestamped output directory. All versions are preserve
 | Claude Max/Pro ($20/mo) | `provider: "claude-code"` | `npm i -g @anthropic-ai/claude-code` | **$0 extra** |
 | Google Account | `provider: "gemini-cli"` | `npm i -g @google/gemini-cli` | **Free** (1000 req/day, Gemini 2.5 Pro) |
 | GitHub Copilot ($10/mo) | `provider: "copilot-cli"` | `npm i -g @github/copilot` | **$0 extra** |
-| ChatGPT Plus/Pro ($20/mo) | `provider: "codex-cli"` | `npm i -g @openai/codex` | **$0 extra** |
+| ChatGPT Plus ($20/mo) | `provider: "codex-cli"` | `npm i -g @openai/codex` | **$0 extra** |
 | OpenClaw account | `provider: "openclaw-cli"` | `npm i -g openclaw` | **$0 extra** |
+| Hermes Agent (NousResearch open-source 🔥) | `provider: "hermes-cli"` | [Install guide](https://github.com/NousResearch/hermes-agent) | **Free** |
 | A computer | `provider: "ollama"` | [ollama.ai](https://ollama.ai) | **Free** (local models) |
 
 **Or use traditional API keys:**
@@ -300,13 +217,15 @@ All API providers support custom `base_url` and `api_key`, compatible with any O
 
 ```bash
 ao demo                              # Zero-config multi-agent demo
-ao init                              # Download 186 AI roles
+ao init                              # Download 211 Chinese AI roles
+ao init --lang en                    # Download 170+ English AI roles
 ao init --workflow                    # Interactive workflow creator
 ao compose "description"             # AI-powered workflow generation
+ao compose "description" --run       # Generate AND execute in one command
 ao run <workflow.yaml> [options]      # Execute workflow
-ao validate <workflow.yaml>           # Validate without running
-ao plan <workflow.yaml>               # Show execution plan (DAG)
-ao explain <workflow.yaml>            # Explain execution plan in natural language
+ao validate <workflow.yaml>          # Validate without running
+ao plan <workflow.yaml>              # Show execution plan (DAG)
+ao explain <workflow.yaml>           # Explain execution plan in natural language
 ao roles                             # List all available roles
 ao serve                             # Start MCP Server (for Claude Code / Cursor)
 ```
@@ -321,6 +240,46 @@ ao serve                             # Start MCP Server (for Claude Code / Curso
 | `--watch` | Real-time terminal progress display |
 | `--quiet` | Quiet mode |
 
+### AI Workflow Composer
+
+Describe your workflow in one sentence — AI selects the right roles, designs the DAG, and generates a ready-to-run YAML:
+
+```bash
+ao compose "PR code review covering security and performance"
+```
+
+The AI will:
+1. Select matching roles from 211 available (e.g., Code Reviewer, Security Engineer, Performance Benchmarker)
+2. Design the DAG (3-way parallel → summary)
+3. Generate complete YAML with variable passing and task descriptions
+4. Save to `workflows/` — ready to `ao run`
+
+Add `--run` to generate and execute in one command. Supports `--provider` and `--model` flags (default: DeepSeek).
+
+### Resume & Iterate
+
+Not happy with a step? No need to start over. `--resume` reloads previous outputs, `--from` specifies where to restart:
+
+```bash
+# Round 1: Normal run
+ao run workflows/en/solo-founder-plan.yaml -i idea="AI-powered resume builder for job seekers"
+
+# Marketing plan needs work? Re-run from that step
+ao run workflows/en/solo-founder-plan.yaml --resume last --from marketing_plan
+
+# Only redo the final decision
+ao run workflows/en/solo-founder-plan.yaml --resume last --from ceo_decision
+```
+
+Each round saves to a new timestamped directory in `ao-output/`. All versions are preserved.
+
+| Scenario | Command |
+|----------|---------|
+| First run | `ao run workflow.yaml -i key=value` |
+| Re-run from a step | `ao run workflow.yaml --resume last --from <step-id>` |
+| Re-run only failed steps | `ao run workflow.yaml --resume last` |
+| Resume specific version | `ao run workflow.yaml --resume ao-output/<dir>/ --from <step-id>` |
+
 ## MCP Server Mode
 
 AI coding tools (Claude Code, Cursor, etc.) can invoke workflow operations directly via the MCP protocol:
@@ -366,7 +325,7 @@ Cursor (`.cursor/mcp.json`):
 |-------|------|----------|-------------|
 | `name` | string | Yes | Workflow name |
 | `agents_dir` | string | Yes | Path to role definitions directory |
-| `llm.provider` | string | Yes | `claude-code` / `gemini-cli` / `copilot-cli` / `codex-cli` / `openclaw-cli` / `ollama` / `claude` / `deepseek` / `openai` |
+| `llm.provider` | string | Yes | `claude-code` / `gemini-cli` / `copilot-cli` / `codex-cli` / `openclaw-cli` / `hermes-cli` / `ollama` / `claude` / `deepseek` / `openai` |
 | `llm.model` | string | Yes | Model name |
 | `llm.max_tokens` | number | No | Default 4096 |
 | `llm.timeout` | number | No | Step timeout in ms (default 120000) |
@@ -417,7 +376,7 @@ Works with **14 AI coding tools** — install with one command:
 
 | Tool | Config Location | Install Command | Docs |
 |------|----------------|----------------|------|
-| **Claude Code** | Skill mode | `npx superpowers-zh` | [Guide](./integrations/claude-code/) |
+| **Claude Code** | Skill mode | `--tool claude-code` | [Guide](./integrations/claude-code/) |
 | **GitHub Copilot** | `.github/copilot-instructions.md` | `--tool copilot` | [Guide](./integrations/copilot/) |
 | **Cursor** | `.cursor/rules/` | `--tool cursor` | [Guide](./integrations/cursor/) |
 | **Windsurf** | `.windsurfrules` | `--tool windsurf` | [Guide](./integrations/windsurf/) |
@@ -432,7 +391,28 @@ Works with **14 AI coding tools** — install with one command:
 | **Antigravity** | `AGENTS.md` | `--tool antigravity` | [Guide](./integrations/antigravity/) |
 | **OpenClaw** | Skill mode | `--tool openclaw` | [Guide](./integrations/openclaw/) |
 
-## Workflow Templates (30)
+## English Workflow Templates (6)
+
+Ready to run with `agency-agents` English roles:
+
+| Template | Roles | Description |
+|----------|-------|-------------|
+| `en/solo-founder-plan.yaml` | CEO, Market/User Researcher, Tech Lead, Brand, PM, Marketing, CFO | **Solo founder all-hands** — one sentence → 8 departments plan → CEO decision |
+| `en/pr-review.yaml` | Code Reviewer, Security Engineer, Performance Benchmarker | PR review (3-way parallel → merge verdict) |
+| `en/product-review.yaml` | PM, Architect, UX Researcher | PRD review (tech + design parallel → synthesis) |
+| `en/business-plan.yaml` | Trend Researcher, FP&A Analyst, PM, Executive Summary | Business plan (market → parallel forecast + roadmap → plan) |
+| `en/content-pipeline.yaml` | Social Strategist, Content Creator, Growth Hacker | Content pipeline (research → draft → brand review → finalize) |
+| `en/competitor-analysis.yaml` | Trend Researcher, Analytics Reporter, SEO Specialist, Executive Summary | Competitor report (research → data + SEO parallel → summary) |
+
+```bash
+ao run workflows/en/solo-founder-plan.yaml -i idea="Your idea here"
+```
+
+---
+
+## Chinese Workflow Templates (32)
+
+> Available via `ao init` (Chinese mode). Use `agency-agents-zh` roles.
 
 ### Dev Workflows (7)
 
@@ -474,7 +454,7 @@ Works with **14 AI coding tools** — install with one command:
 | `legal/contract-review.yaml` | Contract Reviewer, Legal Compliance | **Contract review** (clause analysis → compliance → opinion) |
 | `hr/interview-questions.yaml` | Recruiter, Psychologist, Backend Architect | **Interview questions** (dimensions → parallel design → scorecard) |
 
-### General Workflows (10)
+### General Workflows (12)
 
 | Template | Roles | Description |
 |----------|-------|-------------|
@@ -488,6 +468,8 @@ Works with **14 AI coding tools** — install with one command:
 | `department-collab/incident-response.yaml` | SRE, Security Engineer, Backend Architect | Incident response |
 | `department-collab/marketing-campaign.yaml` | Strategist, Creator, Approver | Marketing campaign (human approval) |
 | `department-collab/ceo-org-delegation.yaml` | CEO, Engineering/Marketing/Product/HR Leads | **CEO org delegation** (decide → parallel depts → summary) |
+| `一人公司全员大会.yaml` | CEO, Market Researcher, User Researcher, PM, Marketing Lead, CFO | **One-person company all-hands** (CEO → 6 depts parallel → decision) |
+| `ai-startup-launch.yaml` | CEO, PM, Architect, Marketing Lead, Finance Advisor | **SaaS product launch decision** (CEO → 4 depts parallel → launch plan) |
 
 ## Output Structure
 
@@ -507,8 +489,8 @@ ao-output/product-review-2026-03-22/
 ## Ecosystem
 
 ```
-Your AI subscription ──→ agency-orchestrator ──→ 186 expert roles collaborate ──→ quality output
-                              │
+Your AI subscription ──→ agency-orchestrator ──→ 380+ expert roles collaborate ──→ quality output
+                              │                  (211 Chinese + 170+ English)
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
       14 AI Coding Tools    CLI Mode        MCP Server
@@ -518,8 +500,10 @@ Your AI subscription ──→ agency-orchestrator ──→ 186 expert roles co
 
 | Project | Description |
 |---------|-------------|
-| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 186 AI role definitions — the role library for this engine |
-| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI coding superpowers — 20 skills for Claude Code / Cursor |
+| [agency-agents](https://github.com/msitarzewski/agency-agents) | 170+ English AI role definitions by [@msitarzewski](https://github.com/msitarzewski) — the English role library for this engine |
+| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 211 Chinese AI role definitions (Chinese) — the Chinese role library for this engine |
+| [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) | AI coding tools field guide (Chinese) — 66 Claude Code tips + 9 tools best practices |
+| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI coding superpowers (Chinese) — 20 skills for Claude Code / Cursor |
 | [shellward](https://github.com/jnMetaCode/shellward) | AI agent security middleware — prompt injection detection, DLP, command safety |
 
 ## Roadmap
@@ -527,8 +511,9 @@ Your AI subscription ──→ agency-orchestrator ──→ 186 expert roles co
 - [x] **v0.1** — YAML workflows, DAG engine, 4 LLM connectors, CLI, streaming output
 - [x] **v0.2** — Condition branching, loop iteration, human approval, Resume, 5 department-collab templates
 - [x] **v0.3** — 9 AI tool integrations, 20+ workflow templates, `ao explain`, `ao init --workflow`, `--watch` mode
-- [x] **v0.4** — MCP Server mode (`ao serve`), 14 AI tool integrations, one-command installer, 30 workflow templates, **9 LLM providers (6 need no API key: Claude Code / Gemini / Copilot / Codex / OpenClaw / Ollama)**
-- [ ] **v0.5** — Web UI, visual DAG editor, English role support, workflow marketplace
+- [x] **v0.4** — MCP Server mode (`ao serve`), 14 AI tool integrations, one-command installer, 32 workflow templates, **10 LLM providers (7 need no API key: Claude Code / Gemini / Copilot / Codex / OpenClaw / Hermes / Ollama)**
+- [x] **v0.5** — `ao compose --run` one-sentence-to-result, real-time streaming, smart retry (exponential backoff), per-step model override, agent identity
+- [ ] **v0.6** — Web UI, visual DAG editor, English workflow templates, workflow marketplace
 
 ## Contributing