multi_agent_coordinator - SKILL.md

Description

Orchestrate complex multi-agent workflows with explicit coordinator planning, execution governance, and automatic output management. Each skill run creates its own isolated output namespace to prevent file accumulation and confusion from repeated executions.

Core Innovation

Automatic namespaced output management - each skill run gets a unique timestamped directory, eliminating manual cleanup and preventing cross-run confusion while preserving audit trails.

When to Use

• Repeatable verification and migration workflows
• Regular system health checks
• Iterative refactoring projects
• Any scenario where the skill will be executed multiple times
• Situations requiring historical audit trails without manual file management

The Five-Phase Coordinator Process

PHASE 0: COORDINATOR PLANNING & OUTPUT SETUP (EXPLICIT & OUTPUTTED)

This happens before any agent spawning and creates isolated output space

1. Generate Unique Run Identifier

   • Create timestamp-based namespace: multi_agent_run_YYYYMMDD_HHMMSS
   • All outputs for this run go under this directory
   • Prevents collisions with previous runs

2. Create Isolated Output Directory

   • Path: /home/openclaw/.openclaw/workspace/coordinator_runs/multi_agent_run_YYYYMMDD_HHMMSS/
   • All skill outputs are contained here
   • Previous runs remain untouched in their own directories

3. High-Level Task Plan Creation

   • Analyze problem statement
   • Decompose into logical functional domains
   • Output: TASK_PLAN.md (inside run directory)

4. Dependency Analysis & Sequencing

   • Build dependency graph: Task B depends on Task A if B needs A's output
   • Identify independent tasks (can run in parallel)
   • Output: DEPENDENCY_GRAPH.md (inside run directory)

5. Parallel Group Formation

   • Group independent tasks into execution groups
   • Groups must be executed in dependency-respecting sequence
   • Output: EXECUTION_GROUPS.md (inside run directory)

6. Agent Specification & Prompt Generation

   • For each agent, define:
     • Specific task from requirements
     • Safety constraints (isolation, read-only needs, backups, etc.)
     • Required inputs/access
     • Expected output format
     • Which execution group it belongs to
   • Generate exact prompts
   • Output:
     • AGENT_REQUIREMENTS.md (inside run directory)
     • AGENT_1.prompt through AGENT_N.prompt (inside run directory/prompts/)
     • COORDINATOR.prompt (inside run directory/prompts/)

PHASE 1: EXECUTION (GOVERNED AUTONOMY WITH ISOLATED OUTPUTS)

• Group 0 (Coordinator):
  • Starts and maintains session throughout
  • Writes progress to run directory
• For each Execution Group in Sequence:
  1. Spawn all agents in the current group in parallel
  2. Agents write outputs to run directory (isolated per agent)
  3. Wait for all agents in the current group to complete (or timeout)
  4. Verify all agents in group finished successfully
  5. Proceed to next group ONLY when current group is fully done
• Coordinator maintains session, enforces group sequencing, and handles failures

PHASE 2: OUTPUT ORGANIZATION & CLEANUP PREPARATION

• All agent outputs automatically stored in run directory
• No manual cleanup needed during execution
• Outputs remain available for audit/historical reference

PHASE 3: REPORTING

• Collect all agent outputs from run directory
• Verify safety protocol adherence and group sequencing was maintained
• Generate final consolidated report in run directory

PHASE 4: AUTOMATIC CLEANUP POLICY (CONFIGURABLE)

• Skill includes configurable retention policy
• Default: Keep last 5 runs, auto-delete older ones
• User can adjust: Keep all, keep none (immediate cleanup), or custom count
• Cleanup happens automatically after successful completion
• Failed runs are preserved for investigation unless user opts for aggressive cleanup

Key Deliverables (All Namespaced to Run Directory)

1. TASK_PLAN.md - Coordinator's high-level decomposition
2. DEPENDENCY_GRAPH.md - Task relationships and sequencing logic
3. EXECUTION_GROUPS.md - Defined parallel groups and sequence order
4. AGENT_REQUIREMENTS.md - Multi-agent setup specifications
5. prompts/AGENT_1.prompt through prompts/AGENT_N.prompt - All agent prompts
6. prompts/COORDINATOR.prompt - Coordinator's ongoing governance prompt
7. outputs/AGENT_1.output through outputs/AGENT_N.output - Agent results
8. outputs/COORDINATOR.output - Coordinator session log
9. REPORT.final - Consolidated final report

Automatic Output Management Features

1. Isolation by Default: Each run gets its own directory
2. No Manual Cleanup Needed: Outputs don't accumulate in workspace
3. Audit Trail Preservation: Historical runs remain accessible
4. Configurable Retention: User-defined cleanup policies
5. Failed Run Preservation: By default, failed runs are kept for debugging
6. Workspace Cleanliness: Main directory stays uncluttered

Usage Pattern with Output Management

1. You provide: Problem statement + explicit approval to start coordinator planning
2. Skill outputs: All planning documents and prompts in a new timestamped directory
3. You review: The coordinator's explicit reasoning in the isolated run directory
4. You provide: Explicit approval to execute the generated workflow
5. Skill executes: The governed multi-agent coordination, outputs namespaced
6. Skill provides: Final report in the run directory + applies cleanup policy
7. You find: Results in coordinator_runs/multi_agent_run_YYYYMMDD_HHMMSS/REPORT.final

Applied to Our Database Migration Example

The first run would create:

/home/openclaw/.openclaw/workspace/coordinator_runs/ └── multi_agent_run_20260401_093000/ ├── TASK_PLAN.md ├── DEPENDENCY_GRAPH.md
├── EXECUTION_GROUPS.md ├── AGENT_REQUIREMENTS.md ├── prompts/ │ ├── AGENT_1.prompt │ ├── AGENT_2.prompt │ ├── ... (through AGENT_8.prompt) │ └── COORDINATOR.prompt ├── outputs/ │ ├── AGENT_1.output │ ├── AGENT_2.output
│ ├── ... (through AGENT_8.output) │ └── COORDINATOR.output └── REPORT.final

A second run 10 minutes later would create:

/home/openclaw/.openclaw/workspace/coordinator_runs/ ├── multi_agent_run_20260401_093000/ ← First run (preserved per policy) └── multi_agent_run_20260401_094000/ ← Second run (new isolated space) ├── TASK_PLAN.md ├── DEPENDENCY_GRAPH.md ├── EXECUTION_GROUPS.md ├── AGENT_REQUIREMENTS.md ├── prompts/ (all agent prompts) ├── outputs/ (all agent outputs) └── REPORT.final

Cleanup Policy Examples (User Configurable)

• Conservative (default): keep_last=5 - Keep 5 most recent runs, delete older
• Archival: keep_all=true - Never auto-delete, manual cleanup only
• Minimal: keep_last=0 - Immediate cleanup after successful runs (failed runs kept)
• None: cleanup=never - User manages all cleanup manually

Benefits of This Approach

1. Zero Manual File Management: No need to delete/rename outputs between runs
2. Instant Workspace Clarity: Main directory stays clean
3. Preserved Audit Trail: Historical runs available for comparison/compliance
4. Repeatable Execution: Same skill can be run hourly/daily/weekly without conflict
5. Debugging Friendly: Failed runs preserved by default for investigation
6. Transparent Origin: Every output clearly labeled with its run timestamp

This solves your concern about output file confusion from repeated skill runs by making output management automatic, namespaced, and policy-driven rather than requiring manual intervention.