VividKit Crystal clear AI coding
VI
Choose Your Setup Get Started with AgentKit Continue with ClaudeKit Migrate from ClaudeKit to AgentKit Clean cutover from ClaudeKit What Is AgentKit? How AgentKit Works AgentKit Kits, Skills, Agents & Hooks AgentKit Runtime Support AgentKit Desktop App AgentKit Configuration AgentKit CLI Quick Reference AgentKit Skills Cheatsheet AgentKit Workflows AgentKit Statusline Update AgentKit CLI & Kits AgentKit Helper Clean reinstall of AgentKit AgentKit Troubleshooting What is ClaudeKit? ClaudeKit CLI Guide Command Finder Commands Cheat Sheet Workflow Recipes CLI Quick Reference Claude Mechanics Permission Modes ClaudeKit Hooks Coexistence ClaudeKit x Codex CK → Other coding tools How ClaudeKit Works Inside ClaudeKit Finding Your Unknowns Session Recovery Fix from Logs UI/UX Guide Accounts Switcher IDE Config Remote Control Codex App System Diagramming UI Review Gate Promotions Support VividKit

Quick Ref / Command

Engineer Kit

/ak:orchestrate

Coordinate captured agent runs

Coordinate staged or parallel jobs across live-verified coding-agent runtimes and in-session subagents with risk-based routing, worktree-isolated writes, resumable state, capture, safety gates, and independent arbiter review.

01

Brainstorm and intake

02

Build job graph

03

Discover, profile, route

04

Apply safety gate

Rule 01

Prefer direct single-agent work when orchestration adds no useful parallelism, staged dependency, runtime diversity, or arbiter value

Rule 02

Resolve every runtime, model, alias, flag, and agent from live execution-time evidence

Rule 03

Same-stage jobs run concurrently only with non-overlapping ownership and outputs

Rule 04

Worktrees prevent edit collisions but are not OS sandboxes

Rule 05

Arbiter review is required before handoff claims

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

01

Start

Input, scope, route

  1. 1 Brainstorm and intake Clarify outcome, constraints, non-goals, acceptance evidence, workspace root, dependencies, destructive or external intent, expected outputs, and runtime constraints.
  2. 2 Build job graph Convert the accepted outcome into jobs with task, cwd, timeout, expected output, file ownership, dependencies, importance, isolation, concurrency, and explicit skill instructions.
02

Work

Agent / skill execution

  1. 3 Discover, profile, route Build a live runtime inventory, profile candidates, invoke model-routing, and record selected runtime, model or agent, capability tier, risk tier, controls, evidence, and fallback reason.
  2. 4 Apply safety gate Confirm cwd, allowed files, writable roots, side effects, least-privilege controls, approval for destructive or external actions, worktree needs, and external timeouts before dispatch.
03

Verify

Gate, review, validation

  1. 5 Dispatch and capture Create required worktrees, start independent jobs up to concurrency, update state.json on transitions, use ak orchestrate lifecycle delegation where supported, and capture redacted outputs and artifacts.
  2. 6 Run arbiter review After runnable jobs settle, use a separate C3 judgment route to compare outputs with expected artifacts, checks, original intent, route floors, safety gaps, contradictions, and unresolved questions.
04

Close

Report, handoff, artifact

  1. 7 Report captured result Write report.md, metrics history, job status, resolved routes, artifacts, errors, arbiter verdict, checks, reproduction commands, worktree diffs awaiting integration, and unresolved questions.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:orchestrate <job-spec.yaml | task description> [--yes] [--internal]

or

/ak:orchestrate --resume <run-dir>

Arguments

<job-spec.yaml | task description>

Job spec or task

YAML job-spec path for repeatable runs, or a natural-language outcome that the skill converts into a temporary jobs.yaml before dispatch. Omit only when using --resume <run-dir>.

/ak:orchestrate plans/orchestrate-jobs.yaml

Shared options

--internal

Prefer internal agents

Considers qualified in-session subagents first for jobs without an explicit runtime. It is a routing preference, not a hard mode, model guarantee, or permission bypass.

/ak:orchestrate "compare the auth options" --internal
--yes

Use exact prior approval

Carries approval only for the destructive or external scope already described. It does not authorize broader credentials, files, releases, deployments, or safety bypasses.

/ak:orchestrate plans/orchestrate-jobs.yaml --yes
--resume <run-dir>

Resume run

Reloads an existing captured run directory, preserves successful outputs and prior attempts, revalidates live routes, and redispatches only interrupted work.

/ak:orchestrate --resume plans/reports/orchestrate-20260829

Composable flags

How options work together on one invocation. This does not replace the option cards above.

--internal is a routing preference.

--yes covers only exact already-approved destructive or external scope.

--resume uses captured state rather than starting over.

Modes / Routes

--internal

Prefer in-session subagents for jobs without explicit runtime pins, while still allowing live-verified CLI fallback when capability, model selection, or isolation requires it.

Research:
live
Review:
arbiter
Validate:
required
--yes

Treat only the exact pre-approved destructive or external scope as confirmed; it never waives live route evidence, least-privilege controls, or safety gates.

Research:
live
Review:
arbiter
Validate:
required
--resume <run-dir>

Reload the captured jobs.yaml and state.json, preserve successful outputs and prior attempts, revalidate live routes, and redispatch only interrupted jobs.

Research:
revalidate
Review:
arbiter
Validate:
required

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Free-form staged run Recommended 
/ak:orchestrate "research three implementation options and compare them"
Use when:
Use when independent research or implementation jobs can run in stages and need captured evidence plus arbiter review before handoff.
Expected:
Creates a temporary jobs.yaml under plans/reports/orchestrate-<timestamp>/, live-routes each job, captures state and artifacts, runs the arbiter checklist, and writes report.md.
Repeatable YAML spec 
/ak:orchestrate plans/orchestrate-jobs.yaml
Use when:
Use for repeatable job graphs with explicit dependencies, expected outputs, ownership, isolation, checks, and concurrency.
Expected:
Reads the YAML job spec, validates stages and ownership, discovers live runtimes, records runtimes.json and state.json, executes runnable jobs, and reports arbiter findings.
Internal-first routing 
/ak:orchestrate "compare the auth options" --internal
Use when:
Use when in-session subagents should be considered first, but a live-verified CLI fallback may still be required for model control or stronger isolation.
Expected:
Profiles internal dispatch and CLI candidates, records the resolved agent or fallback runtime in status.json, captures internal result.md without fake subprocess fields, and blocks unsafe downgrades.
Resume interrupted run 
/ak:orchestrate --resume plans/reports/orchestrate-20260829
Use when:
Use after an interruption when jobs.yaml and state.json already exist and successful outputs or prior attempts must be preserved.
Expected:
Reloads the run directory, reconnects delegated ak orchestrate jobs where possible, revalidates live routes, preserves completed work, redispatches only interrupted jobs, and updates report.md.
Apply without prompt 
/ak:orchestrate plans/orchestrate-jobs.yaml --yes
Use when:
The job spec is already reviewed and mutating steps should run without an extra confirmation prompt.
Expected:
Validates the YAML spec, skips the extra confirmation prompt, executes runnable jobs, and still records arbiter findings in report.md.

Handled Scope

  • Brainstorm and intake
  • Build job graph
  • Discover, profile, route
  • Apply safety gate
  • Dispatch and capture
  • Run arbiter review

Artifacts Produced

Orchestrate Result

Pattern

plans/reports/orchestrate-<timestamp>/report.md

Final report lists spec, job counts, resolved runtime/model/agent routes, capability and risk tiers, artifacts, errors, arbiter verdict, checks, reproduction commands, worktree diffs awaiting integration, and unresolved questions.

Next