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:

bash
1# Model + skills + prompt
2scripts/run-agent.sh --model MODEL --skills SKILL1,SKILL2 -p "PROMPT"
3
4# Model + prompt (no skills)
5scripts/run-agent.sh --model MODEL -p "PROMPT"
6
7# With labels and session grouping
8scripts/run-agent.sh --model MODEL --skills SKILLS \
9    --session SESSION_ID --label KEY=VALUE -p "PROMPT"
10
11# With template variables
12scripts/run-agent.sh --model MODEL \
13    -v KEY1=path/to/file1 -v KEY2=path/to/file2 \
14    -p "Task using {{KEY1}} and {{KEY2}}"
15
16# Dry run — see composed prompt + CLI command without executing
17scripts/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:

toml
1[skills]
2pinned = ["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:

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

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

Helper Scripts