// Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs.
| name | run-agent |
| description | Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs. |
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 runscripts/run-index.sh — inspect and manage runsCompose 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"
| Flag | Description |
|---|---|
--model MODEL / -m | Model to use (auto-routes to correct CLI) |
--agent NAME | Agent profile for defaults + permissions |
--skills a,b,c | Skills to compose into the prompt |
--strict-skills | Fail fast when any listed skill is unknown |
-p "prompt" | Task prompt |
-f path/to/file | Reference file appended to prompt |
-v KEY=VALUE | Template variable substitution (repeatable) |
--session ID | Session ID for grouping related runs |
--label KEY=VALUE | Run metadata label (repeatable) |
-D brief|standard|detailed | Report detail level (default: standard) |
--continue-run REF | Continue a previous run's harness session |
--fork | Fork the session on continuation (default where supported) |
--in-place | Resume without forking (always for Codex) |
--dry-run | Show composed prompt without executing |
-C DIR | Working directory for subprocess |
.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:
--skills (deduplicated by name).Each run writes to .orchestrate/runs/agent-runs/<run-id>/:
params.json — run parameters and metadatainput.md — composed promptprompt.raw.md — composed prompt before runtime-generated output/report sectionsoutput.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)Two-row append-only index at .orchestrate/index/runs.jsonl:
status: "running" — provides crash visibility.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.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Agent/model error (bad output, task failure) |
| 2 | Infrastructure error (CLI not found, harness crash) |
| 3 | Timeout |
| 130 | Interrupted (SIGINT / user cancel) |
| 143 | Terminated (SIGTERM) |
| Pattern | CLI |
|---|---|
claude-*, opus*, sonnet*, haiku* | Claude (claude -p) |
gpt-*, o1*, o3*, o4*, codex* | Codex (codex exec) |
opencode-*, provider/model | OpenCode (opencode run) |
Routing is automatic from the selected model.
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.
| Script | Purpose |
|---|---|
run-index.sh | Run explorer CLI (list, show, report, logs, files, stats, continue, retry, maintain) |
log-inspect.sh | Inspect run logs (summary, tools, errors, files, search) |
extract-files-touched.sh | Extract file paths from run output |
extract-harness-session-id.sh | Extract harness session/thread ID from output |
extract-report-fallback.sh | Extract last assistant message as report fallback |
load-model-guidance.sh | Load model guidance with override precedence |
Multi-model supervisor that discovers skills, picks models, and composes runs. Use when executing multi-step plans across multiple models.
Multi-model supervisor that discovers skills, picks models, and composes runs. Use when executing multi-step plans across multiple models.
Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs.
Verifies implementation aligns with stated requirements and acceptance criteria. Use before implementation (to clarify scope) and before final sign-off (to detect gaps).
Breaks the next task from a plan into an implementable task file. Use when decomposing a multi-step plan into ordered work units.
Explores codebases and evaluates approaches before planning. Use when investigating a problem space, comparing alternatives, or gathering context for a plan.
