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)
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 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
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)