workflow-runner

Workflow executor: run multi-role orchestration inside AI tools

Execute agency-orchestrator YAML workflows directly in the current session without configuring an API key. The current LLM is the execution engine—take on each role in turn to complete the task.

Applicable scenarios

• The user provided a .yaml workflow file (e.g., 运行 workflows/story-creation.yaml）
• The user requests multiple roles to collaborate on a task (e.g., "have the product manager and architect review this PRD together")
• The user installed agency-agents-zh and wants to orchestrate multiple roles directly within the AI tool

Execution flow (5 steps)

Execute in the following order; do not skip steps:

Step 1: Parse the workflow

Use the Read tool to read the YAML file specified by the user, and extract the following fields:

name: "工作流名称"
agents_dir: "agency-agents-zh"    # 角色定义目录
inputs:                            # 输入变量
  - name: xxx
    required: true/false
    default: "默认值"
steps:                             # 执行步骤
  - id: step_id
    role: "category/agent-name"    # 角色路径
    task: "任务描述 {{变量}}"       # 支持模板变量
    output: variable_name          # 输出变量名
    depends_on: [other_step_id]    # 依赖关系

Ignore the llm、concurrency、timeout、retry configuration—Skill mode uses the current session's LLM; these fields are only used in CLI mode.

Locate the roles directory: Use Bash test -d Check in the following order, and use the first one that exists:

1. Under the current working directory, {agents_dir}/(e.g., ./agency-agents-zh/）
2. ../{agents_dir}/(parent directory)
3. Relative to the directory containing the YAML file, {agents_dir}/
4. node_modules/agency-agents-zh/

If none are found,stop executionand prompt the user:

找不到角色目录。请先安装：
  git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
  或：npm install agency-agents-zh

Step 2: Collect inputs

• For each required: true input, check whether a value has already been provided in the user message
• Required inputs not provided:ask the user immediately, do not guess or use empty values
• Optional inputs with default : use the default value
• Optional inputs without a default value: set to an empty string

Step 3: Build the execution order

Based on depends_on perform a topological sort and divide the steps into multiple levels:

• Steps without depends_on → Level 1
• Steps whose depends_on are all at level N or earlier → Level N+1
• Steps within the same leveldo not depend on each other and can run in parallel

Show the execution plan in the reply:

执行计划（共 N 步）：
  第 1 层: [step_id] — 角色名
  第 2 层: [step_a, step_b] — 并行
  第 3 层: [step_id] — 角色名

Step 4: Execute level by level

For each level:

4a. Pre-read role files

Use the Read tool to read the role .md files for all steps in that level:{角色目录}/{role}.md

Extract from the file:

• Role name: the name field in the frontmatter
• Role system prompt: everything after the second --- markdown content

4b. Render the task template

Replace the {{变量名}} in the task with:

• User input values from inputs
• Result text from previous steps' output

4c. Execute

Single-step level: directly take on that role in the main session to execute. Format:

### Step N/Total: step_id（角色名）

[以该角色身份完成 task，使用角色的专业知识和沟通风格]

Multi-step level (parallel): Use the Agent tool to launch a sub-agent for each step. The prompt for each sub-agent must include:

• The role file'sfull text content(not the path — the sub-agent may not be able to read files)
• The rendered task text
• Instruction: "The above is your role definition. Please complete the following task in that role and output the result directly"

4d. Save output to context

If the step has a output field, store the output text of that step in the variable context for use by subsequent steps' {{变量}} .

Step 5: Save results and display

Use the Write tool to save the results to a file:

.ao-output/{工作流名称}-{YYYY-MM-DD}/
├── steps/
│   ├── 1-{step_id}.md       # 每步的输出
│   ├── 2-{step_id}.md
│   └── ...
├── summary.md                # 最后一步的完整输出（最终成果）
└── metadata.json             # 基本元数据

metadata.json format:

{
  "name": "工作流名称",
  "date": "2026-03-22",
  "success": true,
  "steps": [
    {"id": "step_id", "role": "category/agent", "status": "completed"},
    ...
  ]
}

After execution is complete, show the user:

1. Final deliverable (the contents of summary.md)
2. File save location
3. How many steps were executed

Important rules

Quick mode when there is no YAML file

If the user does not specify a YAML file but describes a task that requires multi-role collaboration:

1. Based on the user's description,automatically generate a YAML workflow definition
2. Show it to the user for confirmation
3. After confirmation, execute according to the above process

Example:

• The user says "help me write a story using a narratologist and a psychologist" → generate a workflow similar to story-creation
• The user says "have the product manager and architect review this PRD" → generate a workflow similar to product-review

Troubleshooting

• Role file does not exist: prompt the user to run ao init or npm install agency-agents-zh
• Template variable is undefined: check the context; if it is a required input, ask the user
• Step execution failed: mark the step as failed, skip all downstream steps that depend on it, and continue executing other independent steps