orchestrate

Orchestrate

Intent-first multi-model primary-agent toolkit for Claude Code, Codex, and OpenCode.

A run is model + skills + prompt. Skills are discovered at runtime from orchestrate/skills/*/SKILL.md frontmatter — no static agent definitions.

NOTE: currently rewriting in Python and not using shell scripts: https://github.com/haowjy/meridian-channel

What's Inside

Core skills (always installed)

Skill	Description
orchestrate	Multi-model primary agent that discovers skills, picks models, and composes runs. Use when executing multi-step plans across multiple models
run-agent	Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs

Optional skills

Skill	Description
reviewing	Reviews code against project rules and curated reference files. Use when auditing files for violations, reviewing changes, or generating cleanup tasks
researching	Explores codebases and evaluates approaches before planning. Use when investigating a problem space, comparing alternatives, or gathering context for a plan
scratchpad	Conventions for disposable scratch code and verification scripts. Use when writing smoke tests, quick probes, or temporary artifacts during task execution
plan-task	Breaks the next task from a plan into an implementable task file. Use when decomposing a multi-step plan into ordered work units
mermaid	Rules and validation for Mermaid diagrams. Use when creating or editing Mermaid diagrams in documentation
spec-aligning	Verifies implementation aligns with stated requirements and acceptance criteria. Use before implementation for scope clarity and before sign-off to detect gaps

Agent profiles

Agent	Description
coder	Implementation agent with full tool access
researcher	Research and investigation with read-only access and web lookup
reviewer	Code review with read-only access and web lookup
orchestrator	Supervisor orchestration agent that delegates implementation, review, and verification runs

Installation

Tell your LLM agent:

Fetch and follow instructions from https://raw.githubusercontent.com/haowjy/orchestrate/refs/heads/main/INSTALL.md

This works with any agent that can fetch URLs — Claude Code, Codex, OpenCode, Cursor, etc. The install guide walks the agent through setup interactively (submodule vs clone, location, skill/agent selection).

Alternative: plugin install

Plugin install discovers skills and agents but skips runtime directory setup and MANIFEST.toml-based filtering.

Claude Code:

/plugin marketplace add haowjy/orchestrate
/plugin install orchestrate@orchestrate-marketplace

Cursor:

/plugin-add orchestrate

Manual install

1. Add orchestrate as a submodule (recommended) or clone:

# Submodule (tracked by parent repo, collaborators get it automatically)
git submodule add https://github.com/haowjy/orchestrate orchestrate

# Or clone (simpler, but untracked)
git clone https://github.com/haowjy/orchestrate orchestrate
echo 'orchestrate/' >> .gitignore

2. Sync skills and agents:

bash orchestrate/sync.sh pull              # all skills + agents (default)
bash orchestrate/sync.sh pull --skills reviewing,mermaid   # selective
bash orchestrate/sync.sh pull --agents reviewer         # selective
bash orchestrate/sync.sh --help            # see all options

If orchestrate lives outside the repo: bash /path/to/orchestrate/sync.sh pull --workspace /path/to/project

3. Update:

# Submodule
git submodule update --remote orchestrate && bash orchestrate/sync.sh pull

# Clone
cd orchestrate && git pull && cd - && bash orchestrate/sync.sh pull

Uninstall

# If submodule:
git submodule deinit -f orchestrate
git rm -f orchestrate
rm -rf .git/modules/orchestrate

# If clone:
rm -rf orchestrate

# Remove synced files:
rm -rf .agents/skills/ .claude/skills/ .agents/agents/ .claude/agents/ .orchestrate/

Directory Layout

Source (orchestrate/ — submodule/clone):

• orchestrate/skills/*/SKILL.md — self-describing capability building blocks
• orchestrate/agents/*.md — agent profiles (convenience aliases with permission defaults)
• orchestrate/MANIFEST.toml — skill & agent registry for sync.sh
• orchestrate/docs/ — design documents

Runtime (.orchestrate/ — gitignored):

• .orchestrate/runs/agent-runs/<run-id>/ — flat per-run artifacts
• .orchestrate/index/runs.jsonl — append-only two-row index (start + finalize)
• .orchestrate/config.toml — optional runtime config (auto-created with commented defaults)

Runtime Config (.orchestrate/config.toml)

run-agent.sh auto-creates .orchestrate/config.toml on first use.
By default it is commented out; uncomment and edit as needed.

Example pinned skills:

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