run-agent

name	run-agent
description	Execute a universal CLOD agent definition and orchestrate referenced skills.
last_validated	"2026-03-21T00:00:00.000Z"

Inputs

• agent_path (path, required) -- Path to the CLOD agent markdown file.
• args (map, optional) -- Key-value arguments passed to the agent.
• execution_mode (enum: sequential | parallel, default: sequential) -- Whether to run skills sequentially or in parallel.
• max_parallel (integer, default: 4) -- Maximum number of parallel skill invocations.
• timeout_secs (integer, default: 900) -- Timeout for the entire agent run in seconds.
• working_dir (path, optional) -- Working directory for skill execution.
• env (map, optional) -- Environment variables to set during execution.
• log_path (path, optional) -- Path for JSONL event log output.

Outputs

• result (markdown) -- The final result of the agent run.
• steps (array) -- Structured trace with timestamps, skill id, status, and output excerpt per step.
• errors (array) -- Any errors encountered during execution.

Constraints

• Skills must be resolved from ./skills relative to the repo root.
• Must not mutate git state unless explicit in agent policy.
• Timeout must be enforced per agent run.

Contract

• Parse agent_path as CLOD agent markdown.
• Validate required skills exist; fail fast if missing.
• Respect execution_mode or parallelism hints inside the agent document.
• Invoke skills in-order (or concurrently) passing args as needed.
• On failure, surface error and allow caller to trigger fallback agent/model.
• Emit structured trace in steps with timestamps, skill id, status, and output excerpt.

Execution Rules

1. Load agent and normalize into internal plan.
2. For each step: resolve skill, prepare inputs, invoke via platform-native mechanism.
3. If step marked parallel, request platform-native fan-out up to max_parallel; when the platform lacks native parallelism, run sequentially.
4. Collect results; if any required step fails, mark run failed.
5. If log_path provided, append JSONL events for observability.

Invocation guidance by platform

• Routing: cron frontmatter agent selects the adapter (codex | gemini | opencode | claude | copilot).
• Codex: call this skill directly with agent_path + args. Parallel blocks are honored only when the user/agent explicitly requests parallel work; the adapter may spawn background shell tasks when safe, otherwise runs sequentially.
• Gemini: supports explicit multi-agent/parallel requests (e.g., “run X and Y in parallel” or orchestrator commands). The adapter maps CLOD parallel blocks to Gemini’s native fan-out when available.
• OpenCode: accepts explicit instructions to run multiple background agents. The adapter will fan out steps marked parallel; otherwise it executes in order.
• Claude: uses native agent execution when agent: claude; this skill is bypassed.