Coordinate verified agent jobs with ak:orchestrate

Use ak:orchestrate when one outcome benefits from staged dependencies, parallel work, runtime diversity, or an independent arbiter. The Skill verifies every runtime and control at execution time, isolates risky writers, captures bounded evidence, and refuses to call unverified work complete.

Choose ak:orchestrate for a job graph

Use ak:orchestrate when

• Several independent jobs can run in parallel with distinct ownership.
• Later jobs depend on explicit artifacts or checks from earlier jobs.
• You need to route research, implementation, tests, and review by capability and risk.
• A long run needs durable state and bounded resume behavior.
• An independent judgment pass should reconcile conflicting outputs.

Choose another workflow when

• One agent can complete the task without useful fan-out or arbitration.
• Teammates need ongoing direct discussion and shared multi-session state. Use ak:team when the live runtime supports it.
• You only need a fast read-only code map. Use ak:scout.
• You have one accepted implementation plan. Use ak:cook unless routing diversity or isolation is material.

Prepare the workspace and runtimes

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• Use a Git repository when any job requires worktree isolation.
• Define the outcome, constraints, non-goals, acceptance evidence, allowed files, and external-effect boundary.
• Ensure each candidate CLI runtime is already installed and authenticated. Discovery does not install, update, log in, or change configuration.
• Keep credentials and unrelated private data out of prompts and capture.

The runtime that invokes the Skill is not automatically the runtime selected for every job.

Run the Skill

/ak:orchestrate "Map the session boundary, propose two designs, implement the accepted low-risk change in isolated ownership, then run an independent review"

/ak:orchestrate "Map the session boundary, propose two designs, implement the accepted low-risk change in isolated ownership, then run an independent review"

$ak:orchestrate "Map the session boundary, propose two designs, implement the accepted low-risk change in isolated ownership, then run an independent review"

For repeatable work, pass a YAML job-spec path. For interrupted work, pass the existing run directory with --resume.

Describe the jobs clearly

Each job needs:

• Intent: A task class such as scout, architecture, implementation, review, audit, security, test, documentation, or mechanical work.
• Workspace: An exact working directory inside the authorized workspace.
• Ownership: Files it may write, or an explicit read-only scope.
• Dependencies: Jobs that must succeed before this one can start.
• Expected output: A verifiable report, diff, test result, or artifact.
• Checks: Commands or evidence the arbiter must inspect.
• Risk: Read-only, scoped write, isolated high-impact write, or external/destructive effect.
• Bounds: A timeout and any explicit runtime, model, Agent, tool, or budget constraint.

An explicit runtime or model is a constraint, not proof that it is present or safe. If the live candidate cannot satisfy the required capability and control floors, the job blocks rather than silently weakening them.

Understand the workflow

1. The Skill accepts the contract. It confirms the outcome, boundaries, expected evidence, dependencies, and external intent.
2. The Skill builds and validates the graph. It rejects duplicate IDs, dependency cycles, unsafe working directories, missing bounds, and parallel write overlap.
3. The Skill inventories live candidates. It verifies executable or Agent availability, authentication readiness, current command shape, selectable routes, permissions, isolation, timeouts, capture, resume behavior, and host limitations.
4. The Skill classifies capability and risk. Read-only extraction, implementation, and independent judgment receive different minimum floors. Safety controls are filtered before cost or latency.
5. The Skill applies the approval gate. Destructive, release, deployment, deletion, credentialed, and other external effects require exact approval and a recovery plan.
6. The Skill dispatches by stage. Independent jobs run together only within the concurrency limit. Parallel writers use separate worktrees and disjoint ownership.
7. The Skill captures durable evidence. State transitions, bounded output, artifacts, errors, duration, and reliably reported usage remain available for diagnosis and resume.
8. The Skill runs an arbiter. A separate judgment route checks expected outputs, contradictions, safety gaps, failed checks, unsupported claims, and unresolved questions.
9. The Skill reports without integrating silently. Worktree diffs remain awaiting review; merge or cherry-pick is a separate action.

Keep approval and safety with you

Every CLI process receives a coordinator-owned timeout. In-session timeouts are only accounting limits unless the live harness proves cancellation; the Skill must not launch another writer into the same ownership while a timed-out Agent may still be running.

Permission bypasses stay off by default. A headless runtime that auto-approves writes is constrained to read/report work or stronger isolated treatment. No job may place tokens, cookies, private keys, raw environment values, or secret arguments in its request or capture.

Verify the result

A complete run should provide:

• A validated job graph with dependencies, ownership, bounds, expected outputs, and checks.
• A live runtime inventory showing verified, constrained, unavailable, and unverified candidates without secret values.
• Per-job status, resolved route, risk and capability classification, artifacts, errors, timeouts, and attempts.
• Preserved failed or interrupted evidence rather than silent retries.
• An arbiter verdict that checks every required artifact and contradiction.
• A final report naming successful, failed, and blocked jobs, checks, worktree diffs awaiting integration, and unresolved questions.

The run is successful only when every required job succeeds, checks pass, claims have evidence, contradictions are resolved, and the arbiter passes.

Troubleshoot or resume

Compare ak:team for live multi-session collaboration, or continue with the Engineer Kit overview and Runtime adapters.

Know the current limits

• Runtime and model catalogs, authentication, flags, and safety controls drift; every run must verify them live.
• In-session Agents may not provide force cancellation, per-job sandboxing, or selectable models.
• Jobs share no implicit memory; dependencies must pass explicit artifacts.
• Worktrees require Git and disk headroom, and integration remains a separate reviewed action.
• Usage and cost appear only when the selected harness reports them reliably.
• The Skill coordinates existing runtimes; it does not create a daemon, dashboard, account pool, or provider adapter.
• Stable and beta contain identical ak:orchestrate policy and schema.