Workflow Executor: Run Multi-Role Orchestration within AI Tools

Execute agency-orchestrator YAML workflows directly in the current session without configuring an API key. The current LLM serves as the execution engine — acting as each role in sequence to complete the task.

Applicable Scenarios

The user provides a
```
.yaml
```
workflow file (e.g., "Run workflows/story-creation.yaml")
The user requests multi-role collaboration to complete a task (e.g., "Have a product manager and architect review this PRD together")
The user has installed
```
agency-agents-zh
```
and wants to orchestrate multi-role tasks directly within the AI tool

Execution Process (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:

yaml

name: "Workflow Name"
agents_dir: "agency-agents-zh"    # Role definition directory
inputs:                            # Input variables
  - name: xxx
    required: true/false
    default: "Default Value"
steps:                             # Execution steps
  - id: step_id
    role: "category/agent-name"    # Role path
    task: "Task description {{variable}}"       # Supports template variables
    output: variable_name          # Output variable name
    depends_on: [other_step_id]    # Dependencies

Ignore
llm
,
concurrency
,
timeout
,
retry
configurations — Skill mode uses the current session's LLM, these fields are only for CLI mode.

Locate Role Directory: Use Bash

test -d

to check in the following order, use the first existing one:

```
{agents_dir}/
```
in the current working directory (e.g.,
```
./agency-agents-zh/
```
)
```
../{agents_dir}/
```
(parent directory)
```
{agents_dir}/
```
relative to the directory where the YAML file is located
```
node_modules/agency-agents-zh/
```

If none are found, stop execution and prompt the user:

Role directory not found. Please install first:
  git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
  Or: npm install agency-agents-zh

Step 2: Collect Inputs

For each
```
required: true
```
input, check if the user has provided a value in their message
For required inputs not provided: Ask the user immediately, do not guess or use empty values
For optional inputs with
```
default
```
: Use the default value
For optional inputs without default: Set to empty string

Step 3: Build Execution Order

Perform topological sorting based on

depends_on

to divide steps into multiple layers:

Steps without depends_on → Layer 1
Steps whose depends_on are all in Layer N or earlier → Layer N+1
Steps in the same layer are independent of each other and can be executed in parallel

Display the execution plan in the response:

Execution Plan (Total N steps):
  Layer 1: [step_id] — Role Name
  Layer 2: [step_a, step_b] — Parallel Execution
  Layer 3: [step_id] — Role Name

Step 4: Execute Layer by Layer

For each layer:

4a. Pre-read Role Files

Use the Read tool to read the role

.md

files for all steps in the layer:

{Role Directory}/{role}.md

Extract from the file:

Role Name:
```
name
```
field in the frontmatter
Role System Prompt: All markdown content after the second
```
---
```

4b. Render Task Template

Replace

{{variable_name}}

in the task with:

User input values from inputs
Result text from output of previous steps

4c. Execute

Single-step layer: Directly act as the role to execute in the main session. Format:

### Step N/Total: step_id (Role Name)

[Complete the task as this role, using the role's professional knowledge and communication style]

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

Full text content of the role file (not the path — sub-agents may not be able to read files)
Rendered task text
Instruction: "The above is your role definition. Please complete the following task as this role and output the result directly"

4d. Save Output to Context

If the step has an

output

field, save the step's output text to the variable context for use in

{{variable}}

of subsequent steps.

Step 5: Save and Display Results

Use the Write tool to save results to files:

.ao-output/{Workflow Name}-{YYYY-MM-DD}/
├── steps/
│   ├── 1-{step_id}.md       # Output of each step
│   ├── 2-{step_id}.md
│   └── ...
├── summary.md                # Complete output of the last step (final deliverable)
└── metadata.json             # Basic metadata

metadata.json format:

json

{
  "name": "Workflow Name",
  "date": "2026-03-22",
  "success": true,
  "steps": [
    {"id": "step_id", "role": "category/agent", "status": "completed"},
    ...
  ]
}

After execution, show the user:

Final deliverable (content of summary.md)
File save location
Number of steps executed

Important Rules

<HARD-GATE> - Each step must truly act as the corresponding role, using the role's professional knowledge and communication style, do not give generic answers - Role switching must be clear — mark the role name at the start of each step - Do not skip or merge steps, strictly follow the DAG layer order - If the role file cannot be found, inform the user and suggest installing agency-agents-zh - Do not execute steps without reading the role .md file first — must Read before executing </HARD-GATE>

Quick Mode Without YAML File

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

Automatically generate a YAML workflow definition based on the user's description
Show it to the user for confirmation
Execute according to the above process after confirmation

Examples:

User says "Help me write a story with a narratologist and psychologist" → Generate a workflow similar to story-creation
User says "Have a 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 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, continue executing other independent steps

workflow-runner

NPX Install

Tags

SKILL.md Content (Chinese)