agency-orchestrator: Instructions file for Claude Code

Agency Orchestrator — Project Context

This is a multi-agent workflow orchestrator. Users define AI collaboration workflows in YAML, and the engine executes them with automatic DAG parallelism, variable passing, and retry logic.

Key Commands

ao run <workflow.yaml> [options]      # Execute workflow
ao run <workflow.yaml> --resume last --from <step-id>  # Re-run from a specific step
ao validate <workflow.yaml>           # Validate without running
ao plan <workflow.yaml>               # Show DAG execution plan + media spend preview (N clips × seconds × tier × vendor; estimated from input defaults)
ao doctor [--fix] [--no-probe] [--media-probe]  # Self-check provider/creds/endpoint reachability/CLI/system Claude Code; --fix repairs a hijacked ~/.claude (fake token / relay base_url); --no-probe skips the live endpoint probe (a 1-token request); --media-probe (old alias: --video-probe) checks every keyed OpenAI-compatible relay for **video / image / speech** endpoints at zero cost (invalid probe body + a control path; see src/media/probe-video.ts) — speech matters because `type: tts` otherwise fails only after the paid image/video steps already ran
ao roles                              # List all 276 available roles
ao install --tool claude-code         # Install bundled roles into a coding tool (claude-code/cursor/copilot/gemini-cli/qwen/opencode/workbuddy/codebuddy); --lang zh|en, --category, --dry-run
ao run <workflow.yaml> --compare      # Run workflow + single-shot baseline + blind judge → side-by-side verdict (productized eval).
                                      # Verdict + the baseline's own prompt + both full outputs are archived to <run>/compare.md and rendered in `ao report` — the baseline and the two judge calls cost real money, they don't live in the terminal only. The judge's anchor is the **deliverable** step's acceptance (not "last completed step")
ao team save <workflow.yaml>          # Save a role line-up as a reusable team (Loadout)
ao team list / show / rm              # Manage saved teams (stored in ~/.ao/teams)
ao run --team <name> "task"           # Run a new task with a saved team (locked line-up)
ao prompt optimize "<prompt>"         # AI-optimize a prompt (--mode system|user, --save)
ao prompt test / list / show / rm / garden  # Prompt Lab: test / manage / starter templates
ao skills [name]                      # List / view methodology skills (superpowers-zh) for step `skill:`
ao report [dir|last]                  # Render a run into a shareable single-file HTML (default: latest run → <run>/report.html)
ao ledger add "<what>" --reason <r>   # Human-intervention ledger (src/cli/ledger.ts): log manual work outside workflows; reasons unsupported|quality|judgment|external; JSONL at <ao-output>/ledger.jsonl (AO_LEDGER_FILE)
# claude-code MUST use `--output-format stream-json --verbose` (src/connectors/claude-code.ts `streamJson`): when one answer exceeds the CLI's output cap it auto-continues, and plain `json` keeps only the LAST segment in `result` (silently, subtype success). parseResultJson joins all assistant segments. Don't revert to json. test/claude-code-stream.ts pins it
AO_CLI_INHERIT_CWD=1 ao run <wf>      # claude-code/codebuddy spawn in an empty temp dir by default (src/connectors/claude-code.ts) so the user's Claude Code project memory / CLAUDE.md never leak into role outputs; set this to spawn in cwd (old behavior). Don't switch to --bare: it disables OAuth/keychain
ao ledger report [--since D] [--until D] [--out f.md]  # Daily table: runs, AI steps, approval/human_input nodes (auto-counted), manual entries → AI autonomy rate (counts, not effort; never prices)
ao run <wf> --notify <webhook>        # Push result to DingTalk/Feishu/WeCom/generic webhook when done (AO_NOTIFY_URL also works; cron-friendly)
ao run <wf> --export pptx             # Export outputs as PPTX (also docx/pdf/xlsx/skill/plan); pandoc preferred, pptxgenjs fallback.
                                      # The file lands in the CURRENT directory, named after the workflow — same name overwrites the previous export
ao run <wf> -i [email protected]         # Image inputs auto-become vision input (data-URI protocol, src/utils/vision.ts); needs a vision-capable API model; CLI providers strip+warn
ao run <wf> -i docs=@./materials     # Directory input = knowledge source: text files (md/txt/csv/json/yaml/html/code) concatenated as `## 文件: <path>` sections (src/utils/docs-dir.ts); skips binaries/hidden/node_modules; pdf/docx are skipped WITH a warning (convert via pandoc first); 400KB total / 200KB per-file cap, truncation is announced. Studio never expands @ (AO_NO_AT_FILE=1)