// Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs.
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.
Multi-model supervisor that discovers skills, picks models, and composes runs. Use when executing multi-step plans across multiple models.
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.
| 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 |