Imported from quanganh208/chatofy (.claude/skills/ak-orchestrate/SKILL.md). Install upstream with npx skills add quanganh208/chatofy --skill ak-orchestrate. Copyright stays with the author (MIT).

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:

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

Use a YAML job spec for repeatable runs. For a free-form request, create a temporary spec at plans/reports/orchestrate-<timestamp>/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 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 owns live candidate discovery, probing, command verification, OS evidence, and <run-dir>/runtimes.json.
• harness-profiles.md owns the evidence schema for permissions, isolation, capture, budgets, and enablement.
• internal-routing.md owns in-session dispatch, capture, timeout, and resume mechanics.
• 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.
• Profile each candidate per harness-profiles.md.
• Pass the live evidence and job classification to 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 <run-dir>/state.json on every job transition.
• For CLI jobs on a platform where ak orchestrate is supported, delegate the actual process lifecycle (spawn, PID/PGID ownership, TERM-then-grace-then-KILL, survival past this coordinating session) to it instead of tracking a raw subprocess handle in this skill's own process — see job-spec.md. On a platform where ak orchestrate reports unsupported, fall back to directly spawned, coordinator-owned subprocesses and record that fallback in the report; a coordinator interruption on that fallback path can leave a job running with no supervisor to reconnect to, which is a known, disclosed platform gap rather than a solved case.
• 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: 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.
• 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-<timestamp>/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 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 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: <workspace-root>
    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: <verified-cli-runtime>
    fallback_runtime: [<verified-fallback-runtime>]
    task: review
    cwd: <workspace-root>
    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-<timestamp>/.
• 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-<timestamp>/
  jobs.yaml
  runtimes.json
  state.json
  report.md
  worktrees/
    <job-id>/
  <job-id>/
    command.txt         # CLI jobs only
    stdout.txt          # CLI jobs only
    stderr.txt          # CLI jobs only
    result.md           # internal jobs only
    status.json
    artifacts/
    attempt-<n>/
plans/reports/orchestrate-history.jsonl

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

{
  "id": "independent-review",
  "runtime": "<resolved-runtime>",
  "model": "<resolved-model-or-null>",
  "agent": "<resolved-agent-or-null>",
  "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. For any job whose CLI process was delegated to ak orchestrate, reconnect first with ak orchestrate resume <run-id> <job-graph.json> (the same graph file used at dispatch) — this either confirms the still-running worker matches the original launch digest, or reclassifies it as orphaned for this step to act on; it never redispatches a second process tree for a run the supervisor is still tracking.
• 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.
• ak orchestrate process-lifecycle delegation is Darwin-only in its current version; every other platform reports it unsupported and this skill falls back to coordinator-owned subprocesses with the disclosed interruption gap above, not a silent equivalent guarantee.

Completion Report

End with:

**Orchestrate Result**
- Spec: <path or inline request>
- Report: <plans/reports/orchestrate-.../report.md>
- Jobs: <success>/<failed>/<blocked>
- Arbiter: pass|fail|blocked
- Checks: <commands or none>

Unresolved questions:
- None