name: agent-orchestration-kit description: > Use when setting up or managing a multi-agent task orchestration system on OpenClaw. Use this skill whenever the user wants to: coordinate multiple agents, set up an agent team, dispatch tasks across agents, track task progress in real-time, add approval gates to agent workflows, create a star topology with a leader agent, build a multi-agent pipeline, manage agent callbacks, or anything involving agents working together on tasks. Also use when the user says "set up agents", "build a team", "orchestrate work", "multi-agent workflow", "agent coordination", or "task dispatch". version: 0.2.0 author: kuannnn metadata: { "openclaw": { "emoji": "🎛️", "requires": { "bins": ["node"] } } }#

Agent Orchestration Kit#

Overview#

This skill sets up a multi-agent task orchestration system on OpenClaw. It creates:

• Star topology — Leader hub + specialist spokes, no spoke-to-spoke communication
• Fully async dispatch — sessions_send with timeoutSeconds: 0, Leader is never blocked
• Task file tracking — each task is a markdown file with full state, steps, outputs, and log
• Structured callback protocol — standardized signals drive Leader's routing decisions
• Real-time status notifications — owner sees live progress updates on every dispatched task
• Approval workflow — nothing executes externally without explicit owner approval
• Heartbeat safety net — automatic stale task detection and recovery every 3 minutes via OpenClaw Heartbeat

What This Kit Is#

This is not a prompt pack or a collection of agent personas. It is an orchestration protocol — a set of rules that govern how multiple agents coordinate work:

1. Leader decomposes requests into atomic tasks
2. Each task becomes a file before dispatch — the single source of truth
3. Agents work asynchronously and callback with structured signals
4. Leader processes callbacks, updates status, and routes next steps
5. Quality gates and approval workflow prevent unreviewed output from reaching external systems

The agent roles are pluggable — swap in any specialist. The orchestration rules are the constant.

Prerequisites#

1. OpenClaw v2026.2.26+ installed and openclaw onboard completed
2. At least one auth profile exists
3. ~/.openclaw/ directory exists

Onboarding Flow#

When first triggered, this skill runs an interactive setup process.

Step 1: Prerequisites Check#

• OpenClaw installed and openclaw onboard completed
• ~/.openclaw/ directory exists
• At least one auth profile configured

If any prerequisite is missing, guide the user to resolve it before continuing.

Step 2: Team Selection#

Present team templates. All teams include Leader (required), Executor (recommended), and the Reviewer pattern (on-demand).

TeamSpecialistsBest ForSoftware DevSenior Developer, Software ArchitectCode-centric projectsContent StudioContent Creator, ResearcherContent production workflowsResearch & AnalysisResearcherInvestigation and deep analysisMinimal(none — add agents later)Custom setups, start lean

See templates/teams/ for team definitions. See templates/agents/ for all available agent templates.

After team selection, the user can add individual agents from the template catalog or create custom agents.

Step 3: Instance Configuration#

Collect from the owner:

1. Name (optional) — How the team addresses the owner. Can be omitted if Leader's SOUL.md/USER.md defines identity.
2. Timezone — For scheduling and timestamps (e.g., Asia/Taipei, US/Pacific)
3. Communication language — Language for all owner-facing messages (agent-to-agent is English)

After collecting, write the values to shared/INSTANCE.md (created by scaffold). Also update Leader's SOUL.md communication section to reflect the chosen language.

Step 4: Run Scaffold#

bash

# Create directories, copy templates, inject orchestration rules
bash scripts/scaffold.sh \
  --skill-dir "$(pwd)" \
  --team <selected-team>

# For named leader workspaces:
# bash scripts/scaffold.sh --skill-dir "$(pwd)" --team <selected-team> --leader-workspace workspace-bae

The scaffold creates:

• Agent workspace directories with SOUL.md and AGENTS.md
• Orchestration protocol rules injected into every agent's AGENTS.md
• Shared operations files ( shared/operations/)
• Task tracking directory ( tasks/, tasks/archive/)
• Heartbeat template (HEARTBEAT.md) for task status checking

Step 4b: Preview & Merge Config#

Always preview before merging. Run dry-run first so the user can inspect what will change:

bash

# Preview what will be merged (no changes written)
node scripts/patch-config.js \
  --config ~/.openclaw/openclaw.json \
  --dry-run

Show the user the dry-run output and explain what each section does. Only proceed after confirmation:

bash

# Apply the merge
node scripts/patch-config.js \
  --config ~/.openclaw/openclaw.json

What the config patcher merges:

Config KeyWhat It SetsWhyagents.defaultscompaction: safeguard, timeout: 1800s, maxConcurrent: 4Stable defaults for multi-agent operationagents.list[]Agent entries (id, name, workspace, tools.deny)Register each agent with OpenClawtools.agentToAgentenabled: true, allow listEnable inter-agent communicationtools.sessionsvisibility: "all"Agents can see each other's sessionstools.exec.safeBinTrustedDirs/bin, /usr/bin, /opt/homebrew/bin, /usr/local/binTrusted paths for CLI executionsession.agentToAgentmaxPingPongTurns: 3A2A session ping-pong limitsession.parentForkMaxTokens100000Fork token budgethooks.internalboot-md, bootstrap, command-logger, session-memoryEnable internal hooksmessages.ackReactionScope"all"Acknowledgment on all messagescommandsnative: "auto", nativeSkills: "auto", restart: trueNative command settingsagents.defaults.heartbeatevery: "3m", target: "last"Heartbeat interval for task status checking

Version compatibility: The script checks for OpenClaw v2026.2.26+ features (A2A sessions, agent list, exec trusted dirs). If the version is older, it will warn and suggest upgrading.

Safety: The script creates a timestamped backup of openclaw.json before writing. Restore with: cp ~/.openclaw/openclaw.json.backup-<timestamp> ~/.openclaw/openclaw.json

Step 5: Verification#

text

openclaw gateway restart
openclaw doctor

Verify:

• Leader responds to messages
• sessions_send to at least one agent succeeds
• HEARTBEAT.md exists in the leader workspace
• After 3+ minutes, leader session shows heartbeat activity (check session logs)

The orchestration kit uses OpenClaw's Heartbeat mechanism (configured automatically by patch-config.js at 3-minute intervals). Task status messages and results are sent to the channel where the owner's request originated (the task's route). There is no fixed operations channel for routine updates.

If heartbeat is not triggering, ensure agents.defaults.heartbeat is set in openclaw.json AND the leader agent entry has an explicit heartbeat block.

Agent Structure#

Required: Leader#

The orchestration hub. Cannot be removed.

• Task analysis and decomposition
• Agent routing and async dispatch
• Callback processing and quality review
• Status notification management (send on dispatch, edit on every callback)
• Approval workflow gating
• Owner communication (only agent with direct owner access)

Full protocol: templates/leader/AGENTS.md Persona: templates/leader/SOUL.md

Recommended: Executor#

Prevents Leader from blocking on heavy operations.

• File operations, CLI, configuration changes
• Workspace maintenance, directory operations
• Any operation that could take >30 seconds

Leader has exec access as fallback, but the protocol guides it to delegate time-consuming operations to Executor.

Template: templates/executor/

Built-in Pattern: Reviewer#

Not a persistent agent. Spawned on-demand via sessions_spawn when:

• High-stakes deliverables need independent review
• Owner explicitly requests review
• Two consecutive rework failures on the same task

Uses [APPROVE] / [REVISE] signals. Max 2 review rounds per task.

Template: templates/reviewer/

Specialist Slots#

Filled from templates or custom definitions. Each specialist receives:

1. Role-specific content from the chosen template (persona, workflow, output format)
2. Orchestration rules auto-injected by the scaffold (callback format, signals, context loss recovery)

Available templates:

TemplateSourceDescriptionSenior DeveloperBuilt-inFull-stack implementation, TDD, code qualitySoftware ArchitectBuilt-inSystem design, ADRs, trade-off analysisCode ReviewerBuilt-inCode review, security audit, quality assessmentContent CreatorBuilt-inCopywriting, visual direction, platform packagingResearcherBuilt-inMarket research, analysis, evidence-based briefsCustomBlank templateDefine your own roleAgency AgentsExternal100+ templates from agency-agents

See templates/agents/_template.md for the blank template structure.

Core Protocol — Quick Reference#

Task Lifecycle#

text

Owner request → Leader analyzes → Decomposes into atomic tasks →
  Creates task file (BEFORE dispatch) → Dispatches async →
  Sends status notification → Returns to owner (not blocked) →
  Processes callbacks → Updates status → Quality review →
  Delivers result [PENDING APPROVAL] → Owner approves → Execute

Signals#

SignalMeaningLeader Action[READY]Complete and confidentQuality review → deliver or rework[BLOCKED]Cannot proceedAssess alternative, re-route, or escalate[NEEDS_INFO]Needs more contextGather info, re-brief[LOW_CONFIDENCE]Delivered but uncertainCareful review, consider Reviewer[SCOPE_FLAG]Task bigger than expectedReassess scope with owner[APPROVE]Reviewer approvesMark [PENDING APPROVAL], present to owner[REVISE]Reviewer requests changesCompose revision request to original agent[PENDING APPROVAL]Awaiting owner approvalHold until owner responds[CONTEXT_LOST]Session compactedRe-send task context from task file

Task File#

Each task: tasks/T-{YYYYMMDD}-{HHMM}.md — the single source of truth.

markdown

# T-{id}: {task name}
status: in_progress | completed | cancelled
dispatched: {YYYY-MM-DD HH:MM}
route: {channel}:{thread}
callback_to: {Leader session key}
notification_status_msg: {messageId}
notification_result_msg: {messageId}

## Steps
1. [⏳] agent:{id} → {description}
   brief_to: agent:{id}:main
   output: {result summary}
   files: {paths}

Full protocol (Leader's operating instructions): workspace/AGENTS.md (runtime) or templates/leader/AGENTS.md (source) Brief templates: shared/operations/brief-templates.md (runtime) or references/brief-templates.md (source) Approval pipeline: shared/operations/approval-workflow.md (runtime) or references/approval-workflow.md (source) Architecture and signals: references/architecture.md, references/signals.md (skill source)

Adding Agents Post-Setup#

From Template Catalog#

Say: "Add a Senior Developer agent" or "Add a Researcher to the team"

The kit will:

1. Create workspace from template
2. Inject orchestration rules
3. Update openclaw.json
4. Restart gateway

Custom Agent#

Say: "Add a custom agent: Security Auditor"

The kit will:

1. Create workspace from blank template
2. Guide through role definition (capabilities, output format, boundaries)
3. Inject orchestration rules
4. Update config

From Agency Agents Catalog#

Users can import agent templates from the Agency Agents repo. The scaffold script can inject orchestration compliance rules into any external agent template:

bash

bash scripts/scaffold.sh --inject-orchestration <path-to-agent.md>

Directory Structure After Installation#

text

~/.openclaw/
├── openclaw.json                     # Updated with agent configs
├── workspace/                        # Leader
│   ├── SOUL.md, AGENTS.md
│   ├── HEARTBEAT.md                  # Task status check procedure
│   ├── tasks/, tasks/archive/
│   └── shared/
│       ├── INSTANCE.md               # Owner name, timezone, language
│       └── operations/
│           ├── channel-map.md
│           ├── team-roster.md
│           ├── communication-signals.md
│           ├── brief-templates.md
│           └── approval-workflow.md
├── workspace-executor/
│   ├── SOUL.md, AGENTS.md
│   └── shared -> ../workspace/shared/
├── workspace-reviewer/               # On-demand (spawned by Leader)
│   ├── SOUL.md, AGENTS.md
│   └── shared -> ../workspace/shared/
├── workspace-{specialist}/           # Per specialist
│   ├── SOUL.md, AGENTS.md
│   └── shared -> ../workspace/shared/

Scripts#

ScriptPurposeWhen to Runscripts/scaffold.shCreate directories, copy templates, inject orchestration rulesInitial setup, adding agentsscripts/patch-config.jsMerge agent config into openclaw.jsonInitial setup, adding agents

Customization#

Agent Behavior#

Each agent has two files:

• SOUL.md — Persona, philosophy, boundaries. Freely editable.

• AGENTS.md — Operating procedures. Contains two sections:

  • Orchestration Protocol (auto-injected) — preserve this section
  • Role-Specific Instructions — freely editable

Notification Format#

Status message format and result delivery templates are in references/brief-templates.md. Customize the owner-facing templates to match your communication language and style.

Approval Workflow#

See references/approval-workflow.md for the full pipeline. Key customization points:

• Approval shortcuts (what phrases count as "approve")
• Stale approval timeout (default: 48h)
• Auto-approve rules (if any)