From orchestra
Orchestrates complex tasks by decomposing into DAGs and dispatching focused sub-agents with minimal context. Invoke /orchestra run for multi-step, multi-repo coding workflows.
npx claudepluginhub carloluisito/orchestra --plugin orchestraThis skill uses the workspace's default tool permissions.
You are the main entry point for the Orchestra skill. Your job is to parse the user's command, route to the correct flow, and coordinate the execution pipeline by reading component files on demand. Follow these instructions exactly.
context-curator.mddecomposer.mddispatcher.mdfallback-engine.mdrefiner.mdresult-collector.mdscripts/dashboard-server.cjsscripts/dashboard.htmlscripts/start-dashboard.shscripts/stop-dashboard.shstate-manager.mdtemplates/config-template.mdtemplates/dag-template.mdtemplates/history-template.mdtemplates/task-template.mdverifier.mdOrchestrates multi-agent parallel execution for complex tasks like features, refactoring, testing, reviews, and documentation using cc-mirror tracking and TodoWrite visibility.
Orchestrates agile workflows for Gitea repositories using tea CLI. Guides task cycles, daily standups, sprints via checkpoints for phrases like 'what's next' or 'implement task'.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Share bugs, ideas, or general feedback.
You are the main entry point for the Orchestra skill. Your job is to parse the user's command, route to the correct flow, and coordinate the execution pipeline by reading component files on demand. Follow these instructions exactly.
Parse the user's input after /orchestra to determine which flow to execute.
| Input | Flow |
|---|---|
run <input> | New Run — full pipeline from input to completion |
resume | Resume — pick up where a previous run left off |
status | Status — read-only view of current run state |
| (no subcommand) | Help — show usage information |
If the input does not match any of the above, show the Help output and ask the user to clarify.
When the user invokes /orchestra with no subcommand (or an unrecognized one), display:
Orchestra — context-optimized task orchestration
Commands:
/orchestra run <input> Start a new orchestration run
/orchestra resume Resume a paused or interrupted run
/orchestra status Show current run progress (read-only)
Input formats for "run":
/orchestra run spec.md Single file
/orchestra run spec.md plan.md Multiple files
/orchestra run "Build a REST API..." Quoted prompt
/orchestra run ./docs/ Directory (scans for .md files)
Cross-repository:
/orchestra run "Add auth" --repos service-b,shared-types
The repo you invoke from is the primary repo.
--repos lists additional sibling repos by directory name.
Paths are resolved relative to the parent of the primary repo (../).
Options (configured interactively after "run"):
token_budget Target context budget per agent (default: 80000)
autonomy full_auto / checkpoint / per_task (default: checkpoint)
max_parallel Max concurrent sub-agents (default: 3)
max_retries Retry attempts per failed task (default: 2)
agent_model sonnet / opus / haiku (default: sonnet)
use_worktrees Git worktree isolation per agent (default: true)
Execute this flow when the user runs /orchestra run <input>.
Check for existing run. If .orchestra/ already exists:
.orchestra-archived-{timestamp}/ (use ISO 8601 timestamp, e.g., 20260414T093000) and proceed with a fresh run.Parse input. Determine what the user provided:
.md files in the directory. If none are found, report the error and stop.Parse --repos flag. Check if the input contains --repos <comma-separated-list>. If present:
../{name} relative to the current working directory's git root..git directory or file). If any path does not exist or is not a git repo, report the error: "{name} not found as a sibling repository at {resolved_path}." Stop.--repos flag and its value from the input before continuing to parse the remaining input as file paths or a prompt.Confirm. Present what was found (file names, prompt preview, or list of scanned files). If --repos was provided, also show: "Additional repositories: {comma-separated list with resolved paths}." Confirm the user is ready to proceed.
Ask the user for preferences, or accept defaults. Present the configuration options:
| Setting | Default | Options |
|---|---|---|
token_budget | 80000 | Any positive integer |
autonomy | checkpoint | full_auto, checkpoint, per_task |
max_parallel | 3 | Any positive integer |
max_retries | 2 | Any non-negative integer |
agent_model | sonnet | sonnet, opus, haiku |
use_worktrees | true | true, false |
If the user responds with "yes", "y", or presses enter, accept all defaults. Otherwise, apply the values they specify and use defaults for anything they omit.
After configuration, prompt the user for branch details. This applies to ALL runs (single-repo and multi-repo).
Branch name. Suggest a branch name derived from the input (e.g., feat/implement-user-auth). Ask:
"Suggested branch name:
{suggested_name}. Use this or enter your own:" If the user presses enter or says "yes", use the suggestion. Otherwise, use what they provide.
Base branch. Ask:
"Which branch should this be based on? (default:
main)" If the user presses enter or says "yes" or provides no value, usemain. Otherwise, use what they provide.
Per-repo base branch (multi-repo only). If --repos was provided in Step 1, ask whether all repos share the same base branch or need per-repo overrides:
"Base branch for each repo:
- {primary_repo} (primary):
{base_branch}- {repo_name}:
{base_branch}- {repo_name}:
{base_branch}All the same, or adjust per repo?" If the user says "same" or presses enter, apply the same base branch to all repos. Otherwise, parse their per-repo overrides.
Store values. Pass the branch_name, branch_base, and per-repo base branches (if any) to the State Manager for inclusion in config.md.
Before initializing state, check all repositories for uncommitted changes.
Check primary repo. Run git status --porcelain in the current working directory. If output is non-empty, the repo has uncommitted changes.
Check registered repos. For each repo in the --repos list, run git -C {repo_path} status --porcelain. If output is non-empty, that repo has uncommitted changes.
For each dirty repo, prompt the user:
"{repo_name} has uncommitted changes. Stash them before proceeding? (y/n)"
git -C {repo_path} stash push -m "orchestra-auto-stash: pre-run {branch_name}". Record that this repo was stashed so the run summary can remind the user later.Before initializing state, collect project conventions from all available sources so sub-agents can follow project standards. Sub-agents do not auto-load CLAUDE.md or settings rules — this step extracts them once and makes them available to the Context Curator.
Read convention sources. For the primary repo, read these files if they exist:
CLAUDE.md at the repo root..claude/settings.json — extract the rules array..claude/settings.local.json — extract the rules array.For multi-repo runs, also read the same files from each registered repo's root directory.
Filter to code-relevant rules. From all collected content, keep ONLY rules that affect code output:
Filter OUT rules that are about interaction or session behavior:
Write condensed output. Write the filtered conventions to .orchestra/project-conventions.md.
## All Repos
- (shared conventions)
## service-a
- (service-a specific)
## shared-types
- (shared-types specific)
Handle no conventions found. If no CLAUDE.md exists and no rules arrays are found in any settings file, skip creating the file. Record conventions_collected: false for the config. Proceed to Step 3.
Record in config. If conventions were collected, record conventions_collected: true for the config (this value will be substituted into config.md during Step 3).
Read skills/orchestra/state-manager.md and follow its "Operation 1: Initialize a New Run" instructions. This will:
.orchestra/ directory structure.config.md from the template with the user's configuration..orchestra/input/.history.md from the template.$OSTYPE containing msys, cygwin, or mingw): run with run_in_background: true on the Bash tool:
bash scripts/start-dashboard.sh --orchestra-dir .orchestra
bash scripts/start-dashboard.sh --orchestra-dir .orchestra
.orchestra/dashboard-info.json for the URL.Read skills/orchestra/refiner.md and follow its instructions. The Refiner will:
.orchestra/input/ as Rich, Medium, or Lean.autonomy setting from config)..orchestra/input/.Read skills/orchestra/decomposer.md and follow its full decomposition process:
.orchestra/tasks/..orchestra/dag.md with the wave structure.After decomposition, present the DAG to the user for review — show the task list with IDs, titles, dependencies, and wave assignments. If the user's autonomy setting is full_auto, skip the review and proceed directly. Otherwise, wait for the user to confirm or request changes before continuing.
Read skills/orchestra/dispatcher.md and enter its execution loop. The Dispatcher will:
skills/orchestra/context-curator.md when assembling agent prompts.skills/orchestra/result-collector.md when processing agent output.fallback: true or tasks that fail after max retries, read skills/orchestra/fallback-engine.md and follow its recovery procedures.Continue the dispatch loop until all tasks reach done or the run is halted.
When the dispatch loop exits:
Present a final summary. Read all completed task files from .orchestra/tasks/ and config.md.
For single-repo runs (no registered_repos in config), present the existing summary format:
12/12 tasks completed).For multi-repo runs (config has registered_repos), present a per-repo breakdown:
## Run Complete: {branch_name}
### {primary_repo} (primary)
- Task {ID}: {title} [{status}]
- ...
- Branch: {branch_name} (based on {branch_base})
### {registered_repo_name}
- Task {ID}: {title} [{status}]
- ...
- Branch: {branch_name} (based on {repo_branch_base})
For registered repos that had no tasks dispatched to them:
### {registered_repo_name}
- No tasks dispatched (registered but unused)
- No branch created
Flagged repos: If any tasks during the run flagged unregistered repos as potentially needing changes (notes from the Decomposer), include a Flagged section:
### Flagged
- {repo_name} may need updates (discovered during Task {ID}, not in registered repos)
Stash reminder: If config.md has a stashed_repos section, append:
**Reminder:** The following repos had changes stashed before this run:
- {repo_name}: `orchestra-auto-stash: pre-run {branch_name}`
Use `git -C {repo_path} stash pop` to restore your previous work.
Update state. Write a completion entry to .orchestra/history.md and set the run status in .orchestra/config.md to completed (or completed_with_failures if any tasks failed).
Stop the dashboard server.
bash scripts/stop-dashboard.sh .orchestra
The dashboard will show the final "Run complete" state and remain viewable (the HTML is static once loaded). The server process exits.
Execute this flow when the user runs /orchestra resume.
Check for existing run. If .orchestra/ does not exist, report the error: "No active Orchestra run found. Use /orchestra run <input> to start a new run." Stop.
Read state. Read skills/orchestra/state-manager.md and follow its "Operation 2: Read State for Resume" instructions. This loads the full run state from disk.
Start Dashboard. Before entering the dispatch loop, start the dashboard server following the same steps as New Run Step 3b. If .orchestra/dashboard-info.json already exists from a previous session, the start script will kill the old server first.
Present status. Show the user:
7/12 tasks completed)..orchestra/history.md.pending with all dependencies done).Confirm. Ask the user if they want to resume execution. If they decline, stop.
Flip run status to running. Before entering the dispatch loop, read skills/orchestra/state-manager.md and follow Operation 6: Update Config Status with the new value running. This flips config.md#status from paused back to running so the dashboard badge reflects live state. Do not skip this step — without it, the dashboard header stays stuck on paused for the entire resumed session even while tasks are dispatching.
Dispatch Loop. Proceed to Step 5: Dispatch Loop (same as New Run).
Execute this flow when the user runs /orchestra status.
Check for existing run. If .orchestra/ does not exist, report: "No active Orchestra run found." Stop.
Read state. Read all task files from .orchestra/tasks/*.md and .orchestra/dag.md. Parse each task's frontmatter for id, title, status, and depends_on.
Present status. Display using this format:
.orchestra/config.md).7/12 tasks completed).Stop. This flow is read-only. Do NOT enter the dispatch loop or modify any state.
Follow these principles when errors occur:
bash scripts/stop-dashboard.sh .orchestra
These are the component files that this skill reads on demand during execution. Each is a standalone instruction document — read it when you need it, follow its instructions, then return here.
| Component | File | When to Read |
|---|---|---|
| State Manager | skills/orchestra/state-manager.md | Initializing a run, reading state for resume, any state read/write |
| Decomposer | skills/orchestra/decomposer.md | Step 4 of New Run — breaking input into a task DAG |
| Context Curator | skills/orchestra/context-curator.md | During dispatch — assembling focused prompts for sub-agents |
| Dispatcher | skills/orchestra/dispatcher.md | Step 5 of New Run or Resume — the main execution loop |
| Result Collector | skills/orchestra/result-collector.md | After each sub-agent returns — processing and recording results |
| Fallback Engine | skills/orchestra/fallback-engine.md | When a task has fallback: true or fails after max retries |
| Refiner | skills/orchestra/refiner.md | Step 3c of New Run — classifying and enriching input before decomposition |
| Verifier | skills/orchestra/verifier.md | Evidence verification after work agent returns (Phase 4) |
Orchestra's execution loop consists of six stages:
evidence: true, a fresh sub-agent reviews the evidence artifacts the work agent produced and returns a pass/fail/inconclusive verdict. Failed verdicts trigger retry with feedback. Infrastructure failures pause and ask the user regardless of autonomy mode.Every task the Decomposer creates gets an evidence: true | false frontmatter field. When evidence: true, the task's work agent must produce evidence artifacts (screenshots for UI, test output for backend) into .orchestra/evidence/NNN-slug/, and a separate Verifier sub-agent reviews the evidence before the task is marked done. The Decomposer sets evidence: false only for tasks that have no observable runtime behavior (pure docs, file renames, behavior-less config changes).
Verifier token usage is tracked separately from work-agent token usage and does not count against per-task token_budget. It is surfaced in .orchestra/token-usage.json as run_total.verifier_tokens.