name: run-agent description: Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs.

Run-Agent — Execution Engine

Single entry point for agent execution. A run is model + agent (opt) + skills (opt) + prompt. Routes to the correct CLI (claude, codex, opencode) based on the model, logs everything, and writes structured index entries.

Skills source: sibling skills (../). Runtime artifacts: .orchestrate/.

Runner scripts (relative to this skill directory):

• scripts/run-agent.sh — launch a subagent run
• scripts/run-index.sh — inspect and manage runs

Run Composition

Compose runs dynamically by specifying model, skills, and prompt:

# Model + skills + prompt
scripts/run-agent.sh --model MODEL --skills SKILL1,SKILL2 -p "PROMPT"

# Model + prompt (no skills)
scripts/run-agent.sh --model MODEL -p "PROMPT"

# With labels and session grouping
scripts/run-agent.sh --model MODEL --skills SKILLS \
    --session SESSION_ID --label KEY=VALUE -p "PROMPT"

# With template variables
scripts/run-agent.sh --model MODEL \
    -v KEY1=path/to/file1 -v KEY2=path/to/file2 \
    -p "Task using {{KEY1}} and {{KEY2}}"

# Dry run — see composed prompt + CLI command without executing
scripts/run-agent.sh --model MODEL --skills SKILLS --dry-run -p "PROMPT"

Key Flags

Runtime Config (.orchestrate/config.toml)

On first run in a workspace, run-agent.sh auto-creates .orchestrate/config.toml with commented examples.

Use this file to pin skills that should be auto-added on every run:

[skills]
pinned = ["orchestrate", "run-agent", "mermaid"]

Notes:

• Pinned skills are merged with agent-profile skills and CLI --skills (deduplicated by name).
• Default template is fully commented; uncomment/edit to enable.

Output Artifacts

Each run writes to .orchestrate/runs/agent-runs/<run-id>/:

• params.json — run parameters and metadata
• input.md — composed prompt
• prompt.raw.md — composed prompt before runtime-generated output/report sections
• output.jsonl — raw CLI output (stream-json or JSONL)
• stderr.log — CLI diagnostics (also streamed to terminal)
• report.md — written by the subagent (or extracted as fallback)
• files-touched.nul — NUL-delimited file paths (canonical machine format)
• files-touched.txt — newline-delimited file paths (human-readable)

Run Index

Two-row append-only index at .orchestrate/index/runs.jsonl:

• Start row (written before execution): status: "running" — provides crash visibility.
• Finalize row (written after execution): status: "completed"|"failed" with exit code, duration, token usage, git metadata.

A start row with no matching finalize row means the run crashed or is still in progress.

Structured Exit Codes

Model Routing

Routing is automatic from the selected model.

Run Explorer CLI

scripts/run-index.sh provides index-based run inspection:

scripts/run-index.sh list                          # List recent runs
scripts/run-index.sh list --failed --json          # Failed runs as JSON
scripts/run-index.sh show @latest                  # Show last run details
scripts/run-index.sh report @latest                # Read last run's report
scripts/run-index.sh logs @latest --tools          # Tool call summary
scripts/run-index.sh files @latest                 # Files touched
scripts/run-index.sh stats                         # Aggregate statistics
scripts/run-index.sh continue @latest -p "PROMPT"  # Continue a run's session
scripts/run-index.sh retry @last-failed            # Retry a failed run
scripts/run-index.sh maintain --compact            # Archive old index entries

Run references: full ID, unique prefix (8+ chars), @latest, @last-failed, @last-completed.

Helper Scripts