multi-agent-run

name	multi-agent-run
description	Run a multi-agent workflow on any complex task. One command to decompose, parallelize, and synthesize. Triggers on: run agents, parallel analysis, multi-agent, decompose and run, orchestrate task.

Multi-Agent Run — One Command to Orchestrate

This skill decomposes any complex task into parallel subtasks, executes them with multiple agents, and synthesizes a coherent answer.

One-line trigger:

[$oh-my-dynamic:multi-agent-run] 用 dynamic workflow 处理这个任务；App runtime 可用时使用内部 Codex subagents，否则走 in-chat fallback；大规模走 Codex CLI swarm。

Current v3.5.0 status:

• Preferred developer imports now use oh_my_dynamic.*; root-level files such as dynamic_workflow.py, codex_cli_swarm.py, and agent_broker.py are compatibility shims.

• Stable: Codex CLI swarm, adaptive dynamic workflow planner/replanner, broker reducer, examples/real_repo_review.py, static observability dashboards, round-aware compact evidence, and deterministic quality evals.

• Trust gates: sanitized evidence, python -m doctor --json, Bandit CI, MIT license, threat model docs, deterministic benchmark dry-runs, real v3.2 benchmark stability evidence, v3.5 official brief/demo/outreach docs, GitHub issue templates, and pytest coverage fail-under 80.

• Beta: worktree patch mode, checkpoint/resume, streaming progress events, and capability routing.

• Experimental: Codex App bridge, A2A gateway, and TEA protocol.

Codex App Default: Runtime-Gated Subagents

When triggered inside Codex App, this skill must work immediately after installation:

• If Codex subagent runtime/tools are available and the user asks for dynamic workflows, real subagents, parallel agents, or equivalent multi-agent execution, spawn real Codex internal subagents by default.
• Do not set a model override for spawned subagents. Let them inherit the current Codex App internal LLM/runtime.
• Do not require provider API keys or .env configuration for App-native subagent execution.
• Do not tell the user to use Codex CLI for ordinary App usage.
• Do not run the Python pipeline unless the user explicitly asks for the local Python engine, real provider calls, or dashboard files.
• If the user asks for dynamic workflow or adaptive workflow but not huge scale, use the planner/replanner flow conceptually in App mode; outside App-native subagents, the local dynamic_workflow.py runtime and scripts/record_adaptive_workflow_evidence.py are the matching CLI backends.
• Exception: if the user explicitly asks for dozens/hundreds of real Codex agents, maximum fan-out, CLI swarm, or equivalent large-scale execution, use the local codex_cli_swarm.py backend instead of the ordinary in-chat fallback. This backend launches many codex exec processes, feeds each worker prompt through stdin, streams stdout/stderr to per-agent files, keeps a run manifest/trace, and ingests JSON envelopes into AgentBroker.
• If the user asks for a release-quality adaptive evidence run, use python scripts/record_adaptive_workflow_evidence.py --goal "..." --required-coverage security,tests,docs --max-agents 50 --max-parallel 5 --dashboard; use --dry-run --output-dir /tmp/ohmy-adaptive only for shape checks.
• If the user asks to prove real replanner-generated agents, add --force-missing-coverage replanner-proof --max-rounds 2 so the deterministic trigger policy must ask the real replanner for follow-up agents.
• If the user asks for a real repo review demo or evidence run, use python examples/real_repo_review.py --agents 5 --max-parallel 3; use --dry-run --output-dir /tmp/ohmy-evidence only for CI/demo shape checks that must not launch Codex CLI.
• If the user asks to inspect progress/evidence after a run, use python scripts/render_workflow_observability.py --run-id RUN_ID --source .orchestry --output docs/evidence/RUN_ID-dashboard.html.
• If the user asks whether agent output quality is good enough, or asks for an eval, use python scripts/run_quality_eval.py --sample --output docs/evidence/sample_quality_eval.md for deterministic CI-safe shape checks, or pass a redacted responses JSON with --responses.
• If the user asks whether adaptive workflow is better than a baseline, use python scripts/run_benchmark.py --suite benchmarks/repo_review.json --mode single,fixed,adaptive --output docs/evidence/benchmark_v310_dry.json for a deterministic benchmark shape check, or add --real --fixtures security_command_surface,install_five_minute,tests_dynamic_workflow,evidence_redaction,docs_boundary_claims --output docs/evidence/benchmark_v310.json for release-quality Codex CLI evidence.
• If the user asks whether installation is healthy, use python -m doctor --json; before real Codex CLI workers, use python -m doctor --json --strict-real-codex.
• If the user asks for streaming progress or resume, use python -m dynamic_workflow "goal" --stream-events --checkpoint-dir .orchestry/checkpoints and resume with python -m dynamic_workflow --resume RUN_ID.
• Treat src/oh_my_dynamic/runtime/dynamic_workflow.py as the planner/replanner/reducer orchestration layer and src/oh_my_dynamic/codex/codex_cli_swarm.py plus codex_swarm_* helpers as the Codex CLI worker execution layer. Root-level modules are deprecated compatibility shims for one major version; see docs/V3_MIGRATION_GUIDE.md.
• If the user explicitly asks for concurrent code writing, use worktree mode: workspace_mode="worktree" and write_intent="patch". Do not auto-merge agent worktrees.
• If the user has not clearly granted write intent, stay read-only review by default.
• Use the Codex App bridge contract for real subagents: dispatch plan, per-subagent prompt, structured JSON envelope, and AgentBroker ingestion.
• Coordinate subagent collaboration through registered agents, explicit messages, artifacts, handoffs, review requests/responses, inboxes, and auditable synthesis. Prefer parent-orchestrated A2A-style exchange over hidden peer-to-peer communication.
• Use broker_gateway.py only when the user asks for a local HTTP/SSE transport surface or external tool integration; ordinary Codex App usage should stay inside the App-native subagent path.
• If native Codex subagent runtime/tools are unavailable, fall back to zero-config in-chat workflow execution using the current Codex App assistant/model.

Boundary: local Python runtime, including native_runtime.py, cannot directly call the Codex App internal LLM API unless Codex App/runtime exposes an explicit bridge. Python runtime mode still uses the supplied llm_fn or external provider APIs when configured. codex_cli_swarm.py is different: it does not call App internals from Python; it shells out to the user's installed codex exec, so it uses the existing Codex CLI login/config.

For fallback App usage, or for synthesizing after native subagents return, present the multi-agent workflow directly in the response:

1. Decompose the request into 3-7 tasks.
2. Assign roles such as planner, researcher, builder, reviewer, synthesizer.
3. Mark dependencies and identify which tasks can run in parallel.
4. For real App subagents, require the structured bridge JSON envelope and ingest results into AgentBroker.
5. For explicit large-scale Codex fan-out, use CodexCliSwarmRuntime with a user-visible parallelism setting and broker ingestion.
6. Track registered workers, messages, artifacts, handoffs, review requests/responses, and inboxes explicitly.
7. Produce worker results for each task.
8. Review the combined result for gaps.
9. Replan as needed until the task is ready for reducer, max rounds are reached, or no useful new agents remain.
10. Synthesize a final answer.

When to Trigger

• User asks to analyze something complex with multiple angles
• User wants parallel execution of subtasks
• User says "run agents on..." or "multi-agent..."
• User needs comprehensive research/analysis on a topic

Workflow

Step 1: Codex App Execution

For ordinary Codex App usage, skip local prerequisite checks. If App-native Codex subagent tools are available and the request calls for real/parallel agents, use those tools to spawn real internal subagents without any model override. Otherwise, run the workflow in-chat.

Example trigger:

$multi-agent-run 用多角度分析：学校是否应该引入 AI 作业助手？

Step 2: Understand the Task

Infer reasonable defaults:

1. Main goal/query from the user request.
2. Subtasks: auto-detect, usually 3-7.
3. Perspectives: choose based on domain.
4. Time budget: one concise App response unless user asks for deeper work.
5. Token budget: stay concise but complete.

Only ask for clarification when the request is ambiguous enough that execution would be misleading.

Step 3: Optional Local Python Engine

Use this only if the user explicitly asks for local engine execution, real provider calls, JSON output, or dashboard generation.

import sys
from pathlib import Path

project_root = Path.cwd()
if not (project_root / "pipeline.py").exists():
    raise RuntimeError("Run this local engine snippet from the oh-my-Dynamic repository root.")
sys.path.insert(0, str(project_root))

from pipeline import DynamicPipeline
from llm_client import call_llm

def llm_fn(sys, user):
    return call_llm(system_prompt=sys, user_prompt=user)

pipeline = DynamicPipeline(
    llm_fn=llm_fn,
    max_iterations={{iterations or 2}},
    max_tokens={{token_budget or 500000}},
    max_parallel={{parallel or 3}},
    completeness_threshold={{threshold or 0.80}},
)

result = pipeline.run("""{{user_query}}""")

Step 4: Present Results

Show the user:

1. Summary stats: tasks completed, duration, tokens used
2. Final answer: the synthesized result
3. DAG structure: which tasks ran in parallel vs sequential
4. Optional: Offer a visual dashboard only if local Python engine mode was used.

from visualize import generate_dashboard, open_dashboard
html = generate_dashboard(result, "dashboard.html")
open_dashboard(html)

Step 5: Optional Follow-ups

• Deep dive: "Want me to expand on any specific subtask?"
• Replan: "Should I iterate more? There may be gaps."
• Export: Save results as JSON or Markdown report
• TEA evolve: If a tool failed, offer to auto-evolve it

Output Format

Always present results in this structure:

## 🚀 Multi-Agent Results

**Query**: [original query]
**Tasks**: X/Y completed | **Time**: Xs | **Tokens**: X

### Final Answer
[synthesized result]

### Task Breakdown
- ✅ Task 1: [name] (Xs)
- ✅ Task 2: [name] (Xs)  
- ❌ Task 3: [name] (failed: reason)

Pitfalls

• Codex App native-subagent mode should not ask the user for API keys.
• Codex App native-subagent mode should not set a model override; spawned subagents inherit the current App internal LLM/runtime.
• Codex App native-subagent mode should not imply uncontrolled P2P messaging; keep collaboration explicit and auditable through the orchestrator/broker contract.
• Codex App fallback mode is zero-config and should not ask the user for API keys.
• Codex App fallback mode is an in-chat workflow implementation, not a separate CLI command.
• Local Python native_runtime.py cannot directly call Codex App's internal LLM API unless an explicit App/runtime bridge is exposed; it uses the supplied llm_fn or external providers.
• GLM-5.1 is slow (~40s/call). Warn user if local provider mode generates 5+ subtasks.
• JSON parsing can fail — pipeline has fallback but results may be less structured.
• Token budget is estimated. Keep budget generous for complex queries.
• In local external-provider mode, keep provider rate limits in mind; GLM and other API providers may need lower parallelism.