Orchestrate

Orchestrate

Coordinate headless coding-agent jobs and in-session subagents through a staged, captured, resumable workflow. This is a skill-level coordinator, not a new ak command or scheduler service.

Runtime and model catalogs drift. Resolve every route from live execution-time evidence. Never treat a runtime, provider, model, alias, flag, or agent seen in this file or an older report as currently available.

Inputs

Accepted forms:

/orchestrate "research three implementation options and compare them"
/orchestrate "compare the auth options" --internal
/orchestrate plans/orchestrate-jobs.yaml
/orchestrate plans/orchestrate-jobs.yaml --yes
/orchestrate --resume plans/reports/orchestrate-

Use a YAML job spec for repeatable runs. For a free-form request, create a temporary spec at plans/reports/orchestrate-/jobs.yaml before dispatch.

--internal is a routing preference, not a hard mode. It asks the selection policy to consider in-session subagents first for jobs without an explicit runtime:. A job that needs a separately selectable model, stronger enforced isolation, or a control the current harness lacks may use a live-verified CLI fallback. Never override an explicit runtime, model, or agent pin silently.

Authority Map

Keep durable facts in one place:

• [model-routing.md](references/model-routing.md) is the **sole route-selection

authority**. It owns capability tiers, risk tiers, task defaults, internal selection, fallback qualification, and model-family independence.

• [runtime-matrix.md](references/runtime-matrix.md) owns live candidate

discovery, probing, command verification, OS evidence, and /runtimes.json.

• [harness-profiles.md](references/harness-profiles.md) owns the evidence schema

for permissions, isolation, capture, budgets, and enablement.

• [internal-routing.md](references/internal-routing.md) owns in-session dispatch,

capture, timeout, and resume mechanics.

• [job-spec.md](references/job-spec.md) owns the YAML schema and execution-state

contract.

Do not copy runtime or model catalogs into this file. When references disagree, stop and report the contract mismatch.

Pipeline

1. Brainstorm and intake

• Clarify the desired outcome, constraints, non-goals, and acceptance evidence.
• Read the request or job spec and identify the workspace root.
• Identify dependencies, destructive or external intent, expected outputs, and

runtime constraints.

• Refuse any plan that would place secrets, tokens, credentials, cookies,

private keys, dotenv values, or unrelated private data in prompts or capture.

• Prefer a direct single-agent workflow when orchestration would add no useful

parallelism, staged dependency, runtime diversity, or arbiter value.

2. Build the job graph

• Convert the accepted outcome into jobs with explicit task, cwd, timeout,

expected output, and file ownership.

• Use depends_on to form stages.
• Run same-stage jobs concurrently only when ownership and outputs do not

overlap.

• Mark public-contract, security-sensitive, cross-module, or hard-to-revert

implementation as importance: high.

• Set isolation: worktree for parallel writers, untrusted write prompts, and

any harness whose write boundary is weaker than the job requires.

• Name the skill or instructions each headless job must load; do not rely on

automatic skill discovery in a one-shot process.

3. Discover, profile, and route

• Build a live runtime inventory per

[runtime-matrix.md](references/runtime-matrix.md).

• Profile each candidate per

[harness-profiles.md](references/harness-profiles.md).

• Pass the live evidence and job classification to

[model-routing.md](references/model-routing.md).

• Record the selected runtime, model or agent, capability tier, risk tier,

controls, evidence source, and fallback reason.

• A missing, unauthenticated, unverified, or insufficiently controlled

candidate cannot satisfy a route.

• Re-profile fallbacks and rebuild their commands; never carry model names or

flags between runtimes.

• Mark the job blocked when no candidate meets both capability and risk

floors. Never budget-route judgment or silently weaken safety.

4. Apply the safety gate

• Confirm every job's cwd, allowed files, writable roots, and expected side

effects.

• Use least-privilege permission and tool controls verified on the live runtime.
• Keep every permission-bypass mode disabled by default.
• Require explicit user confirmation for destructive: true, deployment,

release, deletion, credentialed access, or other external side effects unless the user already approved that exact scope through --yes.

• Treat inherently auto-approved headless modes as constrained. Limit them to

read/report work or R2-isolated writes; never shared-tree destructive work.

• Remember that a worktree prevents edit collisions but is not an OS sandbox.
• Give every CLI process an external timeout. Treat internal timeouts as

accounting-only unless the current harness proves cancellation.

5. Dispatch and capture

• Create each required worktree before dispatch and pin the job's cwd to it.
• Start independent jobs together only up to concurrency.
• Update /state.json on every job transition.
• For CLI jobs, capture redacted command, bounded stdout/stderr, exit status,

wall time, artifacts, and usage when reliably reported.

• For runtime: internal, follow

[internal-routing.md](references/internal-routing.md): one subagent per job, final text in result.md, resolved agent in status.json, and no fake subprocess fields.

• Mark timeout, permission prompt, unknown flag/model, or failed checks as

failure. Do not retry silently.

6. Run an arbiter review

• Wait for all runnable jobs to settle.
• Use a separate C3 judgment route selected by

[model-routing.md](references/model-routing.md).

• Prefer independently configured or different-family review when live

evidence proves it; disclose a same-family fallback.

• Compare each result with expected_output and the original intent.
• Run the checks listed in the spec.
• Flag contradictions, unsupported claims, missing artifacts, safety gaps,

timeouts, and failed checks.

• Do not summarize unverified work as complete.

7. Report

• Write plans/reports/orchestrate-/report.md.
• Include per-job status, selected capability/risk tier, resolved runtime and

model or agent, artifacts, errors, arbiter verdict, checks, reproduction commands, worktree diffs awaiting integration, and unresolved questions.

• Append one metrics record per finished job to the cross-run history.
• Never let metrics or a previous run silently rewrite routing policy.

Routing Invocation

After live inventory and profiling, invoke [model-routing.md](references/model-routing.md) and record its resolved route. Do not restate, override, or infer its task defaults, tier floors, candidate ranking, internal-agent choice, or fallback rules elsewhere.

Worktree Isolation

• Create one worktree per isolated job from the accepted base ref.
• Use a unique branch under the run namespace and set the job's cwd to that

worktree.

• Never share a worktree across jobs or reuse a failed attempt without an

explicit cleanup/recovery decision.

• Sequence jobs that must edit the same generated artifact, lockfile,

migration sequence, or shared configuration. Separate worktrees defer those conflicts; they do not resolve them.

• Integration is coordinator-owned and happens only after the arbiter pass.

Summarize diffs first; merging or cherry-picking is a separate reviewed step.

• Remove only integrated or explicitly discarded worktrees. Preserve failed

worktrees for diagnosis and list them in the report.

Metrics and Self-Improvement

Append one JSON line per finished job to plans/reports/orchestrate-history.jsonl with:

• run id and job id;
• runtime and resolved model or agent;
• task, capability tier, and risk tier;
• duration, status, exit state, timeout, and attempts;
• arbiter verdict;
• usage/cost only when reliably reported by the harness.

Use a meaningful sample of comparable jobs before suggesting policy changes. Include evidence-backed suggestions in the report; edit routing references only through a separate human-reviewed change.

Job Spec

Read [job-spec.md](references/job-spec.md) for the full schema. This abbreviated example uses placeholders deliberately; preflight resolves them from live evidence:

version: 1
concurrency: 2
jobs:
  - id: scout-session-api
    runtime: internal
    task: scout
    cwd: 
    prompt: "Inspect the session API and report extension points."
    timeout: 10m
    expected_output: "Markdown report with files read and recommended seams."

  - id: independent-review
    runtime: 
    fallback_runtime: []
    task: review
    cwd: 
    prompt: "Review the proposed change and verify its evidence."
    timeout: 10m
    expected_output: "Independent verdict with checks and unresolved risks."

Do not replace placeholders from memory. Resolve and record them during that run.

Safety Defaults

• Every job has an explicit cwd, timeout, expected output, and ownership.
• Capture stays under plans/reports/orchestrate-/.
• Redact secrets and sensitive values from prompts, commands, logs, and reports.
• Start with read-only or scoped-write behavior.
• Permission bypasses remain off unless the user approved the exact action and

a stronger external isolation boundary contains the residual risk.

• Parallel writers use separate worktrees and disjoint ownership.
• Preserve failed output for diagnosis; never hide or relabel it.
• Keep destructive and credentialed external actions off prompt-only internal

isolation.

Output Layout

plans/reports/orchestrate-/
  jobs.yaml
  runtimes.json
  state.json
  report.md
  worktrees/
    /
  /
    command.txt         # CLI jobs only
    stdout.txt          # CLI jobs only
    stderr.txt          # CLI jobs only
    result.md           # internal jobs only
    status.json
    artifacts/
    attempt-/
plans/reports/orchestrate-history.jsonl

status.json records the resolved live route rather than a documented default:

{
  "id": "independent-review",
  "runtime": "",
  "model": "",
  "agent": "",
  "task": "review",
  "capabilityTier": "C3",
  "riskTier": "R0",
  "status": "success",
  "exitCode": 0,
  "durationMs": 0,
  "timedOut": false,
  "attempts": 1,
  "worktree": null
}

Arbiter Checklist

The final report is blocked until the arbiter answers:

• Did every required job produce its expected artifact?
• Did any job fail, time out, request permission, or emit uncertainty?
• Do outputs contradict each other?
• Were all listed checks run, and did they pass?
• Are claims supported by paths, command output, citations, tests, or artifacts?
• Did every route meet its capability and risk floor?
• Was runtime/model/agent availability revalidated for this run?
• Are destructive actions approved and reversible?
• Are unresolved questions listed plainly?

Failure Modes

• Missing or unauthenticated runtime: evaluate declared fallbacks through

the same live policy; otherwise block.

• Missing internal agent: re-resolve against the live agent list; use a CLI

fallback only when it meets the same floors.

• Unknown flag or model: fail the attempt, return to live probe, and never

guess a replacement.

• Permission prompt: stop the job and report the exact approval boundary.
• Timeout: preserve bounded partial output, fail the job, and block

dependents.

• Interrupted run: reload jobs.yaml and state.json; keep successful

outputs, preserve prior attempts, revalidate live routes, and redispatch only interrupted jobs.

• Ambiguous ownership: sequence the jobs or assign separate worktrees and

an explicit integration step.

• Reference disagreement: stop and report the contract mismatch instead of

choosing whichever copied route looks newer.

Limitations

• Jobs do not share implicit memory; pass required artifacts through explicit

dependencies.

• Internal jobs may not support force cancellation, per-job sandboxing, or

model selection.

• CLI commands, models, authentication, and safety behavior drift; every run

revalidates them.

• Worktrees require a git repository and disk headroom and do not provide

process isolation.

• Metrics are advisory and cannot authorize an automatic route-policy change.
• Orchestrate coordinates existing runtimes; it does not add a daemon,

dashboard, account pool, or provider adapter.

Completion Report

End with:

**Orchestrate Result**
- Spec: 
- Report: 
- Jobs: //
- Arbiter: pass|fail|blocked
- Checks: 

Unresolved questions:
- None

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bestagentkits
• Source: bestagentkits/orchestrate
• License: MIT
• Homepage: https://agentkit.best

Install and usage instructions live in the source repository linked above.