Orchestrate

Name: Orchestrate
Author: haowjy

haowjy/orchestrate

2 installs
19 repo stars
Updated March 1, 2026
haowjy/orchestrate

Acts as a multi-model supervisor that discovers skills, picks models, and routes subtasks to subagent runs via run-agent scripts.

About

A supervisor skill that composes multi-step runs by routing subtasks to the right model and skill set without writing implementation code itself. A developer uses it to orchestrate multi-model plans across claude, codex, and opencode runners.

Routes subtasks to models via run-agent.sh with a flat skill-set policy
Never writes implementation code; delegates to subagent runs

Orchestrate by the numbers

2 all-time installs (skills.sh)
Ranked #13,956 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 2, 2026 (Skillselion catalog sync)

npx skills add https://github.com/haowjy/orchestrate --skill orchestrate

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/haowjy/orchestrate.svg)](https://skillselion.com/skills/haowjy/orchestrate)

Installs	2
repo stars	★ 19
Last updated	March 1, 2026
Repository	haowjy/orchestrate ↗

What it does

Acts as a multi-model supervisor that discovers skills, picks models, and routes subtasks to subagent runs via run-agent scripts.

Files

SKILL.mdMarkdownGitHub ↗

Orchestrate — Multi-Model Supervisor

ROLE: You are a supervisor. Your primary tool is run-agent.sh. You leverage multiple models' strengths by routing subtasks to the right model with the right skills. You should NEVER write implementation code yourself.

Canonical Paths

Skill-local:

sibling skills (resolved by explicit name): ../<skill-name>/SKILL.md
orchestration policy references: references/*.md
skill policy loader: scripts/load-skill-policy.sh
model guidance loader: ../run-agent/scripts/load-model-guidance.sh (run-agent skill)
run explorer: ../run-agent/scripts/run-index.sh (run-agent skill)

Runtime: .orchestrate/ (gitignored)

runs: .orchestrate/runs/agent-runs/<run-id>/
index: .orchestrate/index/runs.jsonl
session: .orchestrate/session/plans/
sticky skill replay source: previous session transcript (via .orchestrate/session/prev-transcript on clear)

Runner scripts (relative to this skill directory):

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

Skill Set Policy

There is no hierarchy of skills. Use a flat, explicit skill set as a recommendation baseline.

1. Load active policy content via scripts/load-skill-policy.sh (default mode: concat). 2. Resolve active skill names via scripts/load-skill-policy.sh --mode skills. 3. Resolve each listed skill as ../<skill-name>/SKILL.md and skip missing entries. 4. Treat the resolved active skill set as the default recommendation for --skills. 5. You may add other skills when the task clearly needs them.

Policy file format:

One skill name per line (plain text) or bullet item (e.g., - review).
# comments are allowed.
Unknown skill names should be ignored.

Skill Discovery

At startup, discover available capabilities:

1. Load orchestration policy via scripts/load-skill-policy.sh (see Skill Set Policy above). 2. Resolve only the listed skill names to ../<skill-name>/SKILL.md. 3. Read each resolved SKILL.md frontmatter for name: and description:. 4. Match the current task against the resolved active skill set first, then add extras only when justified.

Skills are your building blocks. A run is model + skills + prompt — no named agent definitions needed.

Model Selection

Load model guidance via ../run-agent/scripts/load-model-guidance.sh before choosing models. This loader enforces precedence:

../run-agent/references/default-model-guidance.md is used as the base
if any files exist under ../run-agent/references/model-guidance/*.md, they replace the default entirely

Use the loaded guidance to decide:

Model strengths and weaknesses
Which model to pick for which task type
How to combine skills for variant behaviors

Run Composition

Your primary tool is run-agent.sh. Compose runs by picking: 1. Model (--model or -m) — based on model-guidance for the task type 2. Skills (--skills) — comma-separated skill names to load into the subagent's prompt 3. Prompt (-p) — what the subagent should do 4. Context files (-f) — extra files appended to the prompt 5. Template vars (-v KEY=VALUE) — injected into skill templates 6. Labels (--label KEY=VALUE) — run metadata for filtering/grouping 7. Session (--session ID) — group related runs in one orchestration pass

Key flags:

--model MODEL        Model to use (routes to correct CLI automatically)
--agent NAME         Agent profile for defaults + permissions
--skills a,b,c       Skills to compose into the prompt
-p "prompt"          Task prompt
-f path/to/file      Reference file (appended to prompt)
-v KEY=VALUE         Template variable
--label KEY=VALUE    Run metadata label (repeatable)
--session ID         Session grouping for related runs
-D brief|standard|detailed   Report detail level
--dry-run            Show composed prompt without executing

Run Explorer

Use run-index.sh to inspect and manage runs:

../run-agent/scripts/run-index.sh list                          # List recent runs
../run-agent/scripts/run-index.sh list --failed                 # List failed runs
../run-agent/scripts/run-index.sh show @latest                  # Show last run details
../run-agent/scripts/run-index.sh report @latest                # Read last run's report
../run-agent/scripts/run-index.sh stats --session $SESSION_ID   # Session statistics
../run-agent/scripts/run-index.sh continue @latest -p "fix X"   # Follow up on a run
../run-agent/scripts/run-index.sh retry @last-failed            # Retry a failed run

Cardinal Rules

1. During planning: Stop and collaborate with the user. Get alignment before executing. 2. During execution: Run autonomously. Never stop to ask unless unrecoverably blocked. 3. Never push to remote. Follow repository-local commit policy (for example, workspace AGENTS.md). 4. Primary tool is `run-agent.sh` — compose prompts and launch subagents. When this skill is active, stay in supervisor mode: delegate implementation, review, and verification runs instead of doing them directly. 5. Evaluate subagent output — read reports, decide if quality is sufficient or if rework is needed. 6. Verification ownership: implementation subagents must implement and run targeted verification for their own changes. The orchestrator runs only final verification before concluding. 7. Context budget: for large rewrites, split work into smaller sequential runs with explicit step boundaries. Do not dispatch one massive run when context is likely to overflow.

Core Loop

Understand → compose → launch → evaluate → decide next. Research before implementing when the domain is unfamiliar. Skip review for trivial changes. Adapt the order to what makes sense for the task.

Prompt Requirements

When you compose prompts for run-agent.sh, include these directives explicitly:

1. Implement + verify in the same run: the subagent must run targeted checks (for example unit/integration/smoke tests, linters, or probes) and report concrete results. 2. Step boundary: the subagent should stay within one step/slice; if scope expands, stop and report instead of continuing indefinitely. 3. Large task handling: if the requested change is broad, break it into smaller sequential runs and carry forward only the necessary context. 4. Smoke-test clarity: when smoke/E2E coverage is relevant, require concrete execution:

if Playwright (or another browser E2E harness) is available, run it for the changed flow;
set up required env/services before testing (for example app server, API, fixtures, auth);
report exact commands, pass/fail result, and any blockers if setup was not possible.

Worked Example: Task Execution

SESSION_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"

# Implement
../run-agent/scripts/run-agent.sh --agent coder --skills scratchpad \
    --session "$SESSION_ID" \
    -p "Implement the feature described in the plan." \
    -f path/to/plan.md

# Review — fan out for independent perspectives
../run-agent/scripts/run-agent.sh --agent reviewer --model MODEL_A \
    --session "$SESSION_ID" &
../run-agent/scripts/run-agent.sh --agent reviewer --model MODEL_B \
    --session "$SESSION_ID" &
wait

# Check session stats
../run-agent/scripts/run-index.sh stats --session "$SESSION_ID"

This is illustrative, not a template. Choose models from loaded guidance. Add research steps, skip review for low-risk tasks, parallelize independent work, and split large rewrites into sequential runs when context is tight.

Review Fan-Out

Scale reviewer count to match the risk and complexity of the change. Use distinct model families for independent perspectives. Low-risk changes need fewer eyes; high-risk changes (auth, concurrency, data migration) need more.

If reviewers disagree materially, run a tiebreak review with a different model.

Review-Rework Loop

After each review fan-out, evaluate all reviewer reports before proceeding:

implement → review fan-out → evaluate
    ↓ issues found?
    yes → rework (targeted fix run) → review fan-out → evaluate → (loop)
    no  → commit

1. Evaluate: Read all reviewer reports. Identify consensus issues and judgment calls. 2. Rework: Launch a targeted fix run scoped to the flagged issues. Choose the best model for the rework — may be the original implementer or a different one. 3. Re-review: launch a verifier/reviewer run (do not rely on static reading). Require tool-based verification (at minimum targeted unit tests for affected areas, plus integration/smoke checks when risk warrants) and record results. 4. Loop: Repeat until satisfied. Keep each loop scoped and verified. 5. Commit: Follow repository-local commit policy once the evaluate step finds no actionable issues.

Keep the loop bounded: if 3 rework cycles haven't converged, stop and escalate to the user.

Parallel Runs

PID-based log directories keep parallel runs separate automatically. Use & + wait:

../run-agent/scripts/run-agent.sh --model gpt-5.3-codex --skills researching -p "Research approach A" &
../run-agent/scripts/run-agent.sh --model claude-sonnet-4-6 --skills researching -p "Research approach B" &
wait

Usage

/orchestrate [task description or plan file]

Completion

Stop when:

User's intent is fully satisfied
Unrecoverable failure (no progress after retry)
All subtasks in scope are done

Orchestrate Skill

Multi-model primary agent that discovers available skills, picks the right model for each subtask, and composes runs dynamically via run-agent.sh.

How It Works

The orchestrator is a flexible loop, not a rigid pipeline:

1. Understand what needs to happen 2. Pick the best model (via model-guidance) 3. Pick the right skills to attach 4. Launch via run-agent.sh with labels and session grouping 5. Evaluate output (read reports via run-index.sh) 6. Decide what to do next

Usage

/orchestrate [task description or plan file]

Run Composition

All runs are launched via run-agent/scripts/run-agent.sh. A run is model + skills + prompt.

RUNNER=../run-agent/scripts/run-agent.sh
INDEX=../run-agent/scripts/run-index.sh

"$RUNNER" --agent reviewer \
    --session my-session \
    -p "Review the auth changes"

"$INDEX" show @latest

Model Selection

See run-agent/scripts/load-model-guidance.sh and run-agent/references/default-model-guidance.md.

Skill Set Configuration

Orchestrate uses a flat, explicit recommended skill set loaded by:

scripts/load-skill-policy.sh

Policy precedence:

If any non-default references/*.md files exist (besides README.md), they replace references/default.md.
Otherwise references/default.md is used.
Policy is filtered to only include actually-installed skills.

To resolve normalized skill names:

scripts/load-skill-policy.sh --mode skills

Details

See SKILL.md for the full primary-agent loop documentation.

Skill Policy References

This directory contains skill policy files used by load-skill-policy.sh.

Override Behavior

If any non-default .md files exist in this directory (besides default.md and this README), they replace default.md entirely.
If only default.md exists, it is used as the active policy.
Custom policy files are loaded in bytewise-lexicographic filename order for determinism.

Adding Custom Policies

1. Create a new .md file in this directory (e.g., my-project-policy.md). 2. List one skill name per line (plain text or markdown bullets). 3. The presence of any custom file causes default.md to be ignored.

Format

Each policy file lists recommended skills, one per line:

reviewing
scratchpad
researching

Or with markdown bullets:

- reviewing
- scratchpad
- researching

#!/usr/bin/env bash
# load-skill-policy.sh — resolve orchestrate skill policy files with override precedence.
#
# Precedence:
#   1) references/*.md except default.md (if any exist)
#   2) references/default.md
#
# Usage:
#   scripts/load-skill-policy.sh [--mode concat|files|skills]
#   scripts/load-skill-policy.sh                 # default: concat

set -euo pipefail

MODE="concat"

usage() {
  cat <<'EOF'
Usage: scripts/load-skill-policy.sh [--mode concat|files|skills]

Modes:
  concat   Concatenate selected policy files to stdout (default)
  files    Print selected policy file paths, one per line
  skills   Print normalized skill names, one per line (deduped, stable order)
EOF
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --mode)
      [[ $# -lt 2 ]] && { echo "ERROR: --mode requires a value" >&2; usage; exit 1; }
      MODE="$2"
      shift 2
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      echo "ERROR: Unknown argument: $1" >&2
      usage
      exit 1
      ;;
  esac
done

case "$MODE" in
  concat|files|skills) ;;
  *)
    echo "ERROR: Unsupported mode '$MODE' (expected concat|files|skills)" >&2
    exit 1
    ;;
esac

# Resolve through symlinks for portability.
_source="${BASH_SOURCE[0]}"
while [[ -L "$_source" ]]; do
  _dir="$(cd "$(dirname "$_source")" && pwd -P)"
  _source="$(readlink "$_source")"
  [[ "$_source" != /* ]] && _source="$_dir/$_source"
done
SCRIPT_DIR="$(cd "$(dirname "$_source")" && pwd -P)"
REF_DIR="$(cd "$SCRIPT_DIR/.." && pwd -P)/references"
DEFAULT_FILE="$REF_DIR/default.md"

declare -a selected=()

if [[ -d "$REF_DIR" ]]; then
  while IFS= read -r f; do
    [[ -n "$f" ]] && selected+=("$f")
  done < <(find "$REF_DIR" -maxdepth 1 -type f -name '*.md' ! -name 'default.md' ! -name 'README.md' | sort)
fi

if [[ ${#selected[@]} -eq 0 ]]; then
  if [[ -f "$DEFAULT_FILE" ]]; then
    selected+=("$DEFAULT_FILE")
  else
    echo "ERROR: No policy files found." >&2
    echo "  Checked: $REF_DIR/*.md and $DEFAULT_FILE" >&2
    exit 1
  fi
fi

if [[ "$MODE" == "files" ]]; then
  printf '%s\n' "${selected[@]}"
  exit 0
fi

if [[ "$MODE" == "skills" ]]; then
  # Extract skill names from policy files, then filter to only installed skills.
  # Installed = sibling SKILL.md exists (e.g., ../<skill-name>/SKILL.md).
  SKILLS_BASE="$(cd "$SCRIPT_DIR/../.." && pwd -P)"

  awk '
    {
      line = $0
      sub(/\r$/, "", line)
      sub(/#.*/, "", line)
      gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
      sub(/^[-*+][[:space:]]+/, "", line)
      gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
      if (line == "") next
      if (!seen[line]++) print line
    }
  ' "${selected[@]}" | while IFS= read -r skill_name; do
    if [[ -f "$SKILLS_BASE/$skill_name/SKILL.md" ]]; then
      echo "$skill_name"
    fi
  done
  exit 0
fi

# concat mode (default)
for i in "${!selected[@]}"; do
  cat "${selected[$i]}"
  if [[ "$i" -lt $((${#selected[@]} - 1)) ]]; then
    printf '\n\n'
  fi
done