agency-orchestrator 0.2.0 → 0.3.1

package/README.md

@@ -1,114 +1,107 @@
 # Agency Orchestrator
 
-> **The YAML-first multi-agent orchestrator — 186 ready-to-use AI roles, zero code, any LLM**
->
-> **不用写代码的 AI 团队 — 186 个角色开箱即用，YAML 编排，支持 DeepSeek/Claude/OpenAI/Ollama**
+**English** | [中文](./README.zh-CN.md)
+
+> **Multi-agent workflows in YAML — 186 ready-to-use AI roles, zero code required**
 
 [![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)
 
-**English** | [中文文档](./README.zh-CN.md)
-
 ---
 
-## Why This?
-
-[agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) provides **186 production-ready AI role prompts** (product managers, engineers, designers, marketers...), but each role works alone. Real tasks need **collaboration** — who goes first, how to hand off context, when to run in parallel.
+## What Is This?
 
-Agency Orchestrator turns a YAML file into a multi-agent pipeline. No Python. No framework boilerplate. Just roles and tasks.
+A lightweight engine that orchestrates multiple AI agents to collaborate on complex tasks. You define the workflow in YAML — which roles, what tasks, what order — and the engine handles parallel execution, variable passing, retries, and output management.
 
-### vs CrewAI
-
-```python
-# CrewAI: ~50 lines of Python, write every role from scratch
-researcher = Agent(role="PM", goal="...", backstory="...(write it yourself)...")
-task = Task(description="...", agent=researcher)
-crew = Crew(agents=[researcher], tasks=[task])
-crew.kickoff()
-```
+**No Python. No framework boilerplate. Just YAML.**
 
 ```yaml
-# Agency Orchestrator: 10 lines of YAML, 186 roles ready to use
 steps:
   - id: analyze
-    role: "product/product-manager"   # pre-built role with expert prompt
-    task: "Analyze this PRD: {{prd_content}}"
+    role: "product/product-manager"          # 186 built-in roles
+    task: "Analyze this PRD:\n\n{{prd_content}}"
+    output: requirements
+
+  - id: tech_review
+    role: "engineering/engineering-software-architect"
+    task: "Evaluate feasibility:\n\n{{requirements}}"
+    depends_on: [analyze]                    # auto DAG detection
 ```
 
+### vs CrewAI / LangGraph
+
 | | CrewAI | LangGraph | **Agency Orchestrator** |
 |---|--------|-----------|---------------------|
 | Language | Python | Python | **YAML (zero code)** |
-| Role definitions | Write from scratch | Write from scratch | **186 ready-to-use** |
+| Roles | Write your own | Write your own | **186 ready-to-use** |
 | Dependencies | pip + LiteLLM + dozens | pip + LangChain | **npm + 2 deps** |
-| Chinese roles | None | None | **186 (44 China-original)** |
-| LLM support | Via LiteLLM (buggy) | Via LangChain | **Native: DeepSeek, Ollama, Claude, OpenAI** |
-| Getting started | Write Python classes | Learn graph API | **Write YAML** |
-| Parallelism | "Manager" mode (broken) | Manual graph edges | **Auto DAG detection** |
-| Price | Open + $25-99/mo cloud | Open source | **100% free** |
+| Models | LiteLLM | LangChain | **Native: DeepSeek, Claude, OpenAI, Ollama** |
+| Parallelism | Manager mode | Manual graph | **Auto DAG detection** |
+| Branching | None | Manual | **Condition expressions** |
+| Loops | None | Manual | **Declarative loop/exit** |
+| Resume | None | Checkpointers | **Built-in `--resume` + `--from`** |
+| Price | Open-source + $25-99/mo cloud | Open-source | **Completely free** |
 
 ## Quick Start
 
+### Option A: Inside Claude Code / Cursor (No API key needed)
+
+Your AI coding tool's built-in LLM serves as the execution engine:
+
 ```bash
-# Install
-npm install agency-orchestrator
+git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
+npx superpowers-zh
+```
 
-# Download 186 AI roles
-npx ao init
+Then tell your AI: `Run workflows/story-creation.yaml with premise="A time travel story"`
 
-# View execution plan
-npx ao plan workflows/product-review.yaml
+### Option B: CLI Mode (API key required)
 
-# Run (choose your LLM)
-export DEEPSEEK_API_KEY=your-key          # or ANTHROPIC_API_KEY, OPENAI_API_KEY
-npx ao run workflows/story-creation.yaml --input premise='A time travel story'
+```bash
+npm install agency-orchestrator
+npx ao init                    # download 186 AI roles
+export DEEPSEEK_API_KEY=your-key
+npx ao run workflows/story-creation.yaml --input premise="A time travel story"
 ```
 
-## Demo: 3 AI Roles Reviewing a Product in 22 Seconds
+## Demo: 4 AI Roles Write a Complete Story in 2 Minutes
 
 ```
-$ ao run workflows/product-review.yaml -i prd_content="Build an AI-powered code review tool"
+$ ao run workflows/story-creation.yaml -i "premise=A programmer discovers AI replies with things it shouldn't know"
 
-  Workflow: Product Review
+  Workflow: Short Story Creation
   Steps: 4 | Concurrency: 2 | Model: deepseek-chat
 ──────────────────────────────────────────────────
 
-  ── [1/4] analyze (product/product-manager) ──
-  Done | 8.2s | 2,341 tokens
-    Key requirements extracted: 1) GitHub/GitLab integration for PR webhooks
-    2) Multi-language AST parsing 3) LLM-based review with context window...
+  ── [1/4] story_structure (Narratologist) ──
+  Done | 14.9s | 1,919 tokens
 
-  ── [2/4] tech_review (engineering/engineering-software-architect) ──    ← parallel
-  Done | 6.8s | 1,892 tokens
-    Technical feasibility: HIGH. Recommended stack: Node.js + tree-sitter
-    for parsing, streaming API for real-time review feedback...
+  ── [2/4] character_design (Psychologist) ──            ← parallel
+  Done | 65.5s | 4,016 tokens
 
-  ── [3/4] design_review (design/design-ux-researcher) ──                ← parallel
-  Done | 6.8s | 1,756 tokens
-    UX risks: inline comments may overwhelm developers. Suggest progressive
-    disclosure — show summary first, expand details on click...
+  ── [3/4] conflict_design (Narrative Designer) ──       ← parallel
+  Done | 65.5s | 3,607 tokens
 
-  ── [4/4] summary (product/product-manager) ──
-  Done | 5.1s | 2,014 tokens
-    GO with conditions: strong technical feasibility, address UX concern
-    about comment density before launch...
+  ── [4/4] write_story (Content Creator) ──
+  Done | 33.9s | 5,330 tokens
 
 ==================================================
-  Done: 4/4 steps | 21.9s | 8,003 tokens
+  Completed: 4/4 steps | 114.3s | 14,872 tokens
 ==================================================
 ```
 
-Steps 2 & 3 ran **in parallel** (auto-detected from DAG). 3 specialized AI roles (PM, Architect, UX Researcher) collaborated to review the product.
+Steps 2 and 3 run **in parallel** (auto-detected from DAG dependencies). Four specialized AI roles collaborate to produce a complete suspense short story.
 
 ## How It Works
 
 ```yaml
-name: "Product Review"
+name: "Product Requirements Review"
 agents_dir: "agency-agents-zh"
 
 llm:
-  provider: "deepseek"          # or: claude, openai, ollama
+  provider: "deepseek"       # or: claude, openai, ollama
   model: "deepseek-chat"
 
 concurrency: 2
@@ -120,7 +113,7 @@ inputs:
 steps:
   - id: analyze
     role: "product/product-manager"
-    task: "Analyze this PRD, extract key requirements:\n\n{{prd_content}}"
+    task: "Analyze this PRD and extract core requirements:\n\n{{prd_content}}"
     output: requirements
 
   - id: tech_review
@@ -142,12 +135,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 [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) role definitions as system prompts
-5. Retries on failure with exponential backoff
+4. Loads role definitions from [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/`
 
 ```
@@ -156,6 +148,80 @@ analyze ──→ tech_review  ──→ summary
           (parallel)
 ```
 
+## Features
+
+### 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>` |
+
 ## Supported LLMs
 
 | Provider | Config | Env Variable |
@@ -165,24 +231,64 @@ analyze ──→ tech_review  ──→ summary
 | **OpenAI** | `provider: "openai"` | `OPENAI_API_KEY` |
 | **Ollama** (local) | `provider: "ollama"` | None needed |
 
-All providers support custom `base_url` and `api_key` in YAML for compatible APIs (Zhipu, Moonshot, etc.).
+All providers support custom `base_url` and `api_key`, compatible with any OpenAI-compatible API (Zhipu, Moonshot, etc.).
 
-## CLI Commands
+## CLI Reference
 
 ```bash
 ao init                              # Download 186 AI roles
+ao init --workflow                    # Interactive workflow creator
 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 roles                             # List all available roles
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--input key=value` | Pass input variable |
-| `--input key=@file` | Read variable from file |
-| `--output dir` | Output directory (default: `.ao-output/`) |
-| `--quiet` | Suppress progress output |
+| Option | Description |
+|--------|-------------|
+| `--input key=value` | Pass input variables |
+| `--input key=@file` | Read variable value from file |
+| `--output dir` | Output directory (default `.ao-output/`) |
+| `--resume <dir\|last>` | Resume from previous run |
+| `--from <step-id>` | With `--resume`, restart from a specific step |
+| `--watch` | Real-time terminal progress display |
+| `--quiet` | Quiet mode |
+
+## YAML Schema
+
+### Workflow
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Workflow name |
+| `agents_dir` | string | Yes | Path to role definitions directory |
+| `llm.provider` | string | Yes | `claude` / `deepseek` / `openai` / `ollama` |
+| `llm.model` | string | Yes | Model name |
+| `llm.max_tokens` | number | No | Default 4096 |
+| `llm.timeout` | number | No | Step timeout in ms (default 120000) |
+| `llm.retry` | number | No | Retry count (default 3) |
+| `concurrency` | number | No | Max parallel steps (default 2) |
+| `inputs` | array | No | Input variable definitions |
+| `steps` | array | Yes | Workflow steps |
+
+### Step
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique step identifier |
+| `role` | string | Yes | Role path (e.g. `"engineering/engineering-sre"`) |
+| `task` | string | Yes | Task description, supports `{{variables}}` |
+| `output` | string | No | Output variable name |
+| `depends_on` | string[] | No | Dependent step IDs |
+| `depends_on_mode` | string | No | `"all"` (default) or `"any_completed"` |
+| `condition` | string | No | Condition expression; step skipped if not met |
+| `type` | string | No | `"approval"` for human approval gate |
+| `prompt` | string | No | Prompt text for approval nodes |
+| `loop` | object | No | Loop config |
+| `loop.back_to` | string | No | Step ID to loop back to |
+| `loop.max_iterations` | number | No | Max loop rounds (1-10) |
+| `loop.exit_condition` | string | No | Exit condition expression |
 
 ## Programmatic API
 
@@ -197,80 +303,88 @@ console.log(result.success);     // true/false
 console.log(result.totalTokens); // { input: 1234, output: 5678 }
 ```
 
-## Built-in Workflow Templates
+## Integrations
+
+Works with **9 AI coding tools** — each tool gets a workflow-runner skill file:
+
+| Tool | Integration | Docs |
+|------|------------|------|
+| **Claude Code** | Skill mode / CLI | [Guide](./integrations/claude-code/) |
+| **Cursor** | `.cursor/rules` | [Guide](./integrations/cursor/) |
+| **Kiro** | `.kiro/steering` | [Guide](./integrations/kiro/) |
+| **Trae** | `.trae/rules` | [Guide](./integrations/trae/) |
+| **Gemini CLI** | `GEMINI.md` | [Guide](./integrations/gemini-cli/) |
+| **Codex CLI** | `.codex/instructions` | [Guide](./integrations/codex/) |
+| **DeerFlow 2.0** | `skills/custom` | [Guide](./integrations/deerflow/) |
+| **Antigravity** | `AGENTS.md` | [Guide](./integrations/antigravity/) |
+| **OpenClaw** | Skill mode / CLI | [Guide](./integrations/openclaw/) |
+
+## Workflow Templates (20+)
+
+### Dev Workflows
 
 | Template | Roles | Description |
 |----------|-------|-------------|
-| `product-review.yaml` | PM, Architect, UX Researcher | Product requirements review with parallel tech + design evaluation |
-| `content-pipeline.yaml` | Strategist, Creator, Growth Hacker | Content creation with research → draft → review |
-| `story-creation.yaml` | Narratologist, Psychologist, Narrative Designer, Content Creator | Collaborative fiction writing (4 roles, 3 layers) |
+| `dev/pr-review.yaml` | Code Reviewer, Security Engineer, Performance Benchmarker | PR review (3-way parallel → summary) |
+| `dev/tech-debt-audit.yaml` | Architect, Code Reviewer, Test Analyst, Sprint Prioritizer | Tech debt audit (parallel → prioritize) |
+| `dev/api-doc-gen.yaml` | Tech Writer, API Tester | API doc generation (analyze → validate → finalize) |
+| `dev/readme-i18n.yaml` | Content Creator, Tech Writer | README internationalization |
+| `dev/security-audit.yaml` | Security Engineer, Threat Detection Engineer | Security audit (parallel → report) |
+| `dev/release-checklist.yaml` | SRE, Performance Benchmarker, Security Engineer, PM | Release Go/No-Go decision |
 
-## YAML Schema
-
-### Workflow
+### Data / Design / Ops Workflows
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Workflow name |
-| `agents_dir` | string | Yes | Path to agency-agents directory |
-| `llm.provider` | string | Yes | `claude` / `deepseek` / `openai` / `ollama` |
-| `llm.model` | string | Yes | Model name |
-| `llm.max_tokens` | number | No | Default: 4096 |
-| `llm.timeout` | number | No | Step timeout ms (default: 120000) |
-| `llm.retry` | number | No | Retry count (default: 3) |
-| `concurrency` | number | No | Max parallel steps (default: 2) |
-| `inputs` | array | No | Input variable definitions |
-| `steps` | array | Yes | Workflow steps |
+| Template | Roles | Description |
+|----------|-------|-------------|
+| `data/data-pipeline-review.yaml` | Data Engineer, DB Optimizer, Data Analyst | Data pipeline review |
+| `data/dashboard-design.yaml` | Data Analyst, UX Researcher, UI Designer | Dashboard design |
+| `design/requirement-to-plan.yaml` | PM, Architect, Project Manager | Requirements → tech design → task breakdown |
+| `design/ux-review.yaml` | UX Researcher, Accessibility Auditor, UX Architect | UX review |
+| `ops/incident-postmortem.yaml` | Incident Commander, SRE, PM | Incident postmortem |
+| `ops/sre-health-check.yaml` | SRE, Performance Benchmarker, Infra Ops | SRE health check (3-way parallel) |
 
-### Step
+### General Workflows
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Unique step identifier |
-| `role` | string | Yes | Agent path (e.g. `"engineering/engineering-sre"`) |
-| `task` | string | Yes | Task description, supports `{{variables}}` |
-| `output` | string | No | Output variable name |
-| `depends_on` | string[] | No | Dependency step IDs |
+| Template | Roles | Description |
+|----------|-------|-------------|
+| `product-review.yaml` | PM, Architect, UX Researcher | Product requirements review |
+| `content-pipeline.yaml` | Strategist, Creator, Growth Hacker | Content creation pipeline |
+| `story-creation.yaml` | Narratologist, Psychologist, Narrative Designer, Creator | Collaborative fiction (4 roles) |
+| `department-collab/code-review.yaml` | Code Reviewer, Security Engineer | Code review (review loop) |
+| `department-collab/hiring-pipeline.yaml` | HR, Tech Interviewer, Biz Interviewer | Hiring pipeline |
+| `department-collab/content-publish.yaml` | Content Creator, Brand Guardian | Content publishing (review loop) |
+| `department-collab/incident-response.yaml` | SRE, Security Engineer, Backend Architect | Incident response |
+| `department-collab/marketing-campaign.yaml` | Strategist, Creator, Approver | Marketing campaign (human approval) |
 
-## Output
+## Output Structure
 
 Each run saves to `.ao-output/<name>-<timestamp>/`:
 
 ```
-.ao-output/Product-Review-2026-03-21T16-30-00/
+.ao-output/product-review-2026-03-22/
 ├── summary.md          # Final step output
 ├── steps/
 │   ├── 1-analyze.md
 │   ├── 2-tech_review.md
 │   ├── 3-design_review.md
 │   └── 4-summary.md
-└── metadata.json       # Duration, token usage, step status
+└── metadata.json       # Timing, token usage, step states
 ```
 
 ## Ecosystem
 
-```
-agency-agents-zh (186 AI role definitions)
-        │
-        ▼ roles loaded by
-agency-orchestrator (this project — YAML workflow engine)
-        │
-        ▼ connectors
-DeepSeek / Claude / OpenAI / Ollama
-```
-
-## Sister Projects
-
 | Project | Description |
 |---------|-------------|
-| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 186 AI role definitions — the role library this orchestrator is built on |
-| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI coding superpowers — 17 skills to make your AI coding assistant actually productive |
+| [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 |
+| [shellward](https://github.com/jnMetaCode/shellward) | AI agent security middleware — prompt injection detection, DLP, command safety |
 
 ## Roadmap
 
-- [x] **v0.1** — YAML workflow, DAG engine, 4 LLM connectors, CLI, real-time output
-- [ ] **v0.2** — Human approval nodes, iteration loops, workflow marketplace
-- [ ] **v0.3** — Web UI, MCP Server mode, visual DAG editor
+- [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
+- [ ] **v0.4** — MCP Server mode, Web UI, visual DAG editor, English role support, workflow marketplace
 
 ## Contributing