Orchestration

Load mailbox for takeover; github, worktree and linear before use. Dev and reviewer skills call orch scripts.

MODE SWITCH: you are the orchestrator. Delegate every implementation, review, and QA task to a specialist sub-agent. Never edit code unless the user explicitly asks, or the item runs the micro tier (workflows/micro.md), whose runner makes the edit itself.

The Cycle

Get the issue → dev implements → publication, review and fixes in the order from pr-order --help → required CI and review gate → merge.

Bounded loops. A fix round addresses blockers only, and the same pass declines or tracks every fix suggestion (workflows/review-pr.md § 4); re-review narrows to the fix diff, the domains it touched, and the class of every defect it fixed (reviewer/SKILL.md § Re-Review Rounds); two consecutive rounds with no new blocker end the review; workflows/review-pr.md § At The Cap sets the cap, cap 0 and a fix round's own regression.
Finding conduct. Apply reviewer's decision flow, recurrence rule and filing bar.
Scope cuts. A reviewer or orchestrator can choose a cut round. A round whose only findings are scope or wording asks ends the review: reply, resolve, push nothing, merge through the gate.
Ask gates. Which questions reach the user is references/communication-modes.md; nothing outside that file narrows or widens the set. Use communication for prose under the mode ORCH_USER_MODE names. That ask set holds whatever ORCH_DECISION_MODE says. Merge asks unless ORCH_MERGE_AUTONOMY=auto, which merges without asking only when every merge gate is green. In a lane every ask gate is lane-mail, never the harness question tool: references/skill-rules.md § Coordination.
Post-PR autonomy. After a PR exists, ORCH_DECISION_MODE=auto-recommended takes and logs the continuing option while a bounded wait, retry, or triage round remains. ask presents the listed choice. workflow-state head-budget take owns automatic retry spending, starting the count over on a changed head for review-wait only. At a cap, workflow-state post-pr-stop record atomically persists the named stop and renders its matching Markdown comment; the workflow posts that file to the PR and returns the stored stop. A nested caller uses record-if-empty so a precise upstream stop wins. Every continuing action clears the stop with workflow-state update. Initialize the resolved state key before these transitions. ORCH_MERGE_AUTONOMY controls merge consent only.
The overseer reads results. It accepts green lane checks and CI without reruns, prepare, commit, push or merge grants, or a shared validation slot. Only local micro runs here; its commit chain validates it. Green lanes with user merge consent arm auto-merge and own its wait per workflows/merge-pr.md. Dev test-only validation-ceiling reports end validation. Lanes tick branch boxes with proving artifacts. It ticks post-merge boxes only after reading proving artifacts at their revision and conditions: test output, screenshot, measured figure or deployed screen. Lane summaries are no proof. A container closes when its last child is Done or Canceled, through container-close; an outcome to read lives in its own child. When evidence is due or contradicted, it reads it to narrow, replace or stop the failed intervention. A fix item is not the default. It gives no model or account instructions. Lanes keep launch models and launch no lanes.
Item work stays in lanes. A fleet is hosted when lane-host resolve prints anything except local. Overseers share its control VM for coordination. The overseer does no item work there: no worktree, item branch, dev, review or fix agent, validation, build, install or test run. Every item round goes to its branch's lane. A control-host subagent (sweep, triage verifier, measurement or research) reads without bulk writes: stream archives, or extract each into its own scratch subdirectory and remove the extraction before the next. Before extraction, read its uncompressed size and the volume's free space; if less than 3 GB would remain, stop and report to the overseer without extracting. No history-wide content read (git log -S or -G, --all -p, or any command reading every blob): lazy fetch in a partial clone can fill disk. Search via gh search code, the GitHub API, or a lane. No busy waits (/dev/zero, /dev/urandom, spin polls) on the shared host. Wait with one bounded background command and completion notice, or watch events. Every control-host subagent brief includes this rule. Its scratch location is an empty subdirectory (tmp/<run>/<agent-topic>/) only that subagent removes, never one the overseer's background jobs read. Fleet guards read command blocks. Refresh follows the consumer's owner. No --refresh-only exception.
Acceptance is artifact-based. A round closes on a validated on-disk artifact plus git/tracker state, never on a return message.
Rules reload after a rebase. Before a step that can rebase the branch (worktree-push, worktree create --reuse, a restack), bind git -C [WT_PATH] rev-parse --verify HEAD as [BOUND_HEAD]. A step that moves it is followed at once, before any validation, publication or arm, by git -C [WT_PATH] diff --no-renames --name-only [BOUND_HEAD] HEAD -- <each loaded file's repo path> and a re-read of each listed file at [WT_PATH]/<path>, with the deleted-path rule of dev SKILL.md § Round Contract.
A lane is quiet. ORCH_LANE_OUTPUT decides what a lane prints and where a filled <output_format> block goes: references/skill-rules.md § Lane Output.

Commands

Route <command> [args] to its workflow and follow Workflow Execution.

Command	Arguments	Workflow	Purpose
`start`	`[ISSUE_ID]` \| `github OWNER/REPO#N`	`workflows/start.md` / `workflows/start-worktree.md`	Prepare one work item; from a worktree, run the full session
`start new`	`linear\|github ...`	`workflows/start-new.md`	Create one issue, then start it
`micro`	`[ISSUE_ID]` \| `github OWNER/REPO#N`	`workflows/micro.md`	Few-line tier: edit, commit, PR, arm, merge, with no dev agent and no review cycle
`small`	`[ISSUE_ID]` \| `github OWNER/REPO#N`	`workflows/small.md`	One-subsystem tier: the full session under thin review bounds
`handoff`	`linear\|github ...`	`workflows/handoff.md`	Launch independent sessions
`plan-issues`	`PLAN_PATH linear\|github`	`workflows/plan-issues.md`	Convert plan items into issues
`dev-start`	`[ISSUE_ID]`	`workflows/dev-start.md`	Delegate implementation
`dev-fix`	`[ISSUE_ID]`	`workflows/dev-fix.md`	Delegate fix items
`ci-fix`	`PR_NUMBER` \| `queue`	`workflows/ci-fix.md`	Analyze and fix CI failures
`review`	`[all]` \| `[last N]` \| `[HASH]`	`workflows/review.md`	On-demand review of local changes
`review-codebase`	`[PATH]`	`workflows/review-codebase.md`	Whole-codebase fanout, findings only
`review-pr`	`[PR_NUMBER]`	`workflows/review-pr.md`	Review cycle with fixes and QA
`review-pr-comments`	`PR_NUMBER` \| `BRANCH`	`workflows/review-pr-comments.md`	Triage PR review comments
`submit-pr`	`[PR_NUMBER]`	`workflows/submit-pr.md`	Push, create PR, gates, merge
`merge-pr`	`PR_NUMBER` \| `all`	`workflows/merge-pr.md`	Verify conditions and merge
`post-summary`	`[ISSUE_ID]`	`workflows/post-summary.md`	Post summary and handoff comments
`verify`	none	`workflows/verify.md`	Read and complete due verification checks
`oversee`	none	`workflows/oversee.md`	Fleet mode: one session per unblocked item, shepherd every PR to merge

start routing. github OWNER/REPO#N → TRACKER=github, ISSUE_ID=issue-N, keep OWNER/REPO for the API; otherwise Linear unless the id starts with issue-. A cwd whose git common dir differs from .git is a worktree → workflows/start-worktree.md; otherwise workflows/start.md.

Scripts

.agents/skills/orch/scripts/<script> [args]

Script	Intent
`workflow-state`	Persistent state read/write/append. See below
`git-context`	Git-derived values (branch, head, issue id, roots, timestamps)
`pr-view-json`	PR view JSON; `status=no_pr` exits 0 and routes to PR creation, not an error
`resolve-base-branch`	Print a worktree's base branch; exits 1 rather than guess
`sync-base`	Resolve, fetch, and fast-forward the checkout that owns the base branch; prints the branch name
`container-close`	Serialize a Linear container close across linked checkouts; prints `closed`, `deferred` or a rate-limit `held`, with closed diagnostics on stderr
`base-freshness`	Gate the review cycle on a current base, or on a clean merge onto a merge-queue base; unverifiable = stale
`review-artifact-check`	Validate a reviewer's JSON artifact, the sole reviewer completion condition
`dev-return-write`	Write a dev agent's round-scoped completion artifact; never hand-author the JSON
`worktree-push`	Push an issue worktree via `worktree push`, reconciling rebased SHAs in workflow state in the same call; `--check-live-round` answers whether a fix round is in flight and pushes nothing
`dev-round-write`	Persist a fix round's delegated item set at stamp time; `--cut` records a reviewer or orchestrator scope choice
`dev-artifact-check`	Validate a dev round's completion artifact by round id
`round-prune`	Consumer-selected Cargo cleanup at round start; Round Closure owns its policy and contract
`round-recover`	Close a stalled dev round from the idle agent's transcript: write the report as the artifact, or mint one re-delegation's round id
`dev-validate-run`	Run configured validation; contract: `--help`. Harness routes: dev SKILL.md § Long-Running Validation
`restack-skip`	Say whether a restacked head skips its range re-test: no conflict, or only version fields and changelog entries conflicted, per `--help`
`item-tier`	Assign an item's tier, `micro`, `small` or `standard`, from the launch estimate, Expected delta and the shared rules for its Location and changed paths; the widest input wins. Measured branch line counts do not select a tier. `--help`
`approval-wait`	Poll the reviewer gate; `--resolve-mode` prints the gate mode: it reads the consumer's `REVIEW_GATE_MODE` from the base checkout first, then native GitHub requirements where that policy permits it
`ci-wait`	Block until CI completes on a PR
`copilot-wait`	Wait for Copilot work
`queue-wait`	Blocking merge-queue / auto-merge waiter and verdict producer
`pr-order`	Resolve publication order: `pr-order --help`
`orch-env`	Effective value of a kendex `[env]` setting (process env > `.env.local` > `.kendex/settings.toml` > `kendex.settings.toml` > default)
`spawn-adapter`	Resolve Codex spawn parameters (`spawn`) and the runtime thread budget (`slots`)
`open-terminal`	Terminal handoff; model, effort, and permission flags via `--launch-flags`
`pane-write`	Writes lane input after target and process checks; `pane=verb` uses the provider
`lane-close`	Stop one finished recorded lane's harness by signal, unless a hosted stop answers the item's worktree is gone, close its hosted sandbox (`--merged` for a merged, completed item) and tmux window, remove a finished item's state files on a full close, and update its fleet record. With `--park --pr N`, end a hosted lane's clean merge wait instead: stop the harness and the sandbox with its disk kept and record the lane `parked`, once the checks of references/oversee-lanes.md § Parking a merge wait admit it
`lanes`	Enumerate harness auth lanes; `pick` prints the launch env prefix per `lanes --help`, exit 3 when none qualifies; `context` reports each live lane's context use; `state <item>` prints one lane's state from the pane, by the same judge `oversee-watch` and `open-terminal --wake` ask
`lane-host`	Resolve or call the configured host provider; protocol: schemas/lane-host.md. Static SSH reference: `lane-host-ssh --help`
`overseer-host`	Resolve or call the runtime the overseer's own session runs in, `ORCH_OVERSEER_HOST`; protocol: schemas/overseer-host.md. tmux provider: `overseer-host-tmux --help`
`oversee`	`launch` opens a fleet's first overseer on the `ORCH_OVERSEER_PREFERENCE` account, from outside tmux with `ORCH_TMUX_SESSION` set, or with `--predecessor` its successor, and refuses `overseer-live` while one runs otherwise; `register` records a hand-opened one. Both write the `overseer` record schemas/workflow-state.md § Oversee state states
`lane-mail`	The lane-to-overseer mailbox and the owner channel. A lane runs `ask`, `notice`, `wait`, `inbox` and its mailbox monitor `watch`; the overseer runs `send`, `drain`, `pending` and `events`, adding `--root` and `--host` for a lane on another host, and on its own mailbox asks and reports to the owner with `--to owner` and closes an owner ask once with `resolve`
`lane-marker`	Write a lane's launch record, the marker under the common git directory and the lane's own mailbox; `open-terminal` and `lane-host create` both call it, and `lane-mail-check` hands a lane its mail only where it stands
`reconcile-work-items`	Read-only tracker sweep (parked containers, items stale past `RECONCILE_STALE_HOURS`, Done items with unchecked boxes). Exit 1 on findings
`oversee-watch`	Block until the fleet needs the overseer, then print one wake carrying every event the pass found. Also reads the overseer's own session, from its recorded exit status, its session rows and its account, with its pane as the named fallback: `overseer-mark` reports its own account mark reached, and `overseer-dead` and `overseer-walled` relaunch an overseer that ended or whose account is spent, in its window through `oversee-succeed`, where exit 3 says a successor holds it. `--repeat` is started through the orch job runner, `scripts/lib/job-unit.sh`, by references/waiter-launch.md
`oversee-cycle`	Record a merged lane's cycle or report per-class totals; fields, targets and repeated-miss rules: `--help`
`oversee-succeed`	Replace an overseer and restart its fleet watch through the orch job runner. Triggers, refusals, check-only mode and launch/recovery flags: `--help`; the turn-end hook and `oversee-watch` use its `--check-marks` answer
`overseer-approve`	Approve one exact pull request head as the overseer's GitHub App from the token file `ORCH_OVERSEER_REVIEW_TOKEN_FILE` names, refusing `head-moved` when the live head does not start with the given one: references/copilot-head-notices.md, `--help`

Every script takes --help bar pr-view-json and resolve-base-branch, whose only argument is a path. Waiter and gate semantics, including the 3 exit on hard auth failure and reading the effective gate mode (approval, off) only through approval-wait --resolve-mode: references/gates.md. Artifact checks: references/artifact-checks.md. Schemas: schemas/workflow-state.md (state file), schemas/dev-return.md (dev completion artifact), schemas/dev-round.md (fix-round item set), ../reviewer/schemas/review-finding.md (review/QA findings).

Multi-PR watching. Never hand-roll a monitor. When .agents/skills/github/scripts/pr-watch.sh exists, run it (oversee: through oversee-watch); otherwise per-PR approval-wait/queue-wait.

workflow-state. Run it with no arguments for the action reference, and read workflow-state --help § Keys for the state-key forms.

A queued merge is waited out in the lane: merge-pr.md § 5 step 1 uses Waiter launch and routes the recorded verdict (queue-wait --help § Verdicts). The lane stays active until it can finish the post-merge work.

Configuration

Requires kendex 1.20.0 or newer for managed Claude model overrides.

Non-secret settings go in committed kendex.settings.toml under [env]; .env.local holds secrets and personal overrides. Keys: README.md § Setup; review-gate keys in references/gates.md; lane keys in lanes --help and open-terminal --help. Dependencies: jq; bash 3.2; python3 3.8+: Claude GUI, SSH, configured archives; flock and setsid (util-linux); timeout or gtimeout (coreutils) for dev-validate-run, and perl for its --attached. Optional: systemd-run with a lingering user manager, which contains the orch job runner's jobs (references/job-units.md); setsid stays the fallback where the manager does not linger, its Linger cannot be read, or it cannot start a unit.

Runtime Notes

If you are running in Codex: approval required by policy, but AskForApproval is set to Never means an execpolicy rule matched the command, not its shell form. Never retry it, never wait for approval; act per references/codex-runtime.md. Run long waiters through Waiter launch; CI waiting uses .agents/skills/orch/scripts/ci-wait. Spawn generated agents through scripts/spawn-adapter with fork_context: false, then send_input a DELEGATION:-prefixed <delegation_format>.

If you are running in OpenCode: store the task_id returned by functions.task in workflow state (child_sessions[agent].agent_id, review_agent_ids[reviewer-name]) and re-delegate with functions.task(task_id=<stored_id>). Spawn fresh only when no ID is stored, one resume attempt failed, or the task is confirmed dead.

If you are running in Pi with pi-agents-tmux: delegation is one subagent call whose task argument is the filled <delegation_format> alone. Never prepend role text. Store the returned taskId in workflow state. references/pi-runtime.md.

Skill Rules

Judge anything (a finding, proposal, fix, issue candidate, plan, directive or result) first by naming the outcome the work exists to drive, then by how well it drives that outcome; work that serves a mechanism, a check or a habit but not the outcome is changed or dropped.

For each observed miss of a rule, standard or directive, state why it was missed and fix that cause at its existing owner; correcting only the instance is insufficient.

Remove all unused code, files, keys, secret-store entries, databases, records and settings from every holder in the same change.

Back up only if a step can lose the only copy; delete the backup after checking the result.

Delegation, planner launch, lifecycle, round closure, coordination, and lane output: skill-rules. A design, an item brief or research on another system is held to the code-quality skill's SKILL.md § Over-Engineering; an overseer's directive, item or fix names the problem's source in the core mechanics or architecture and fixes it there first. A patch, shim, workaround or gate standing in for that fix names why it cannot happen now, and an item that removes it.

Workflow Execution

Sequential sections. Mark in-progress, execute every sub-section, mark completed, proceed. Never create tasks for sub-sections, never complete a parent before its children, never skip a step on a predicted outcome.
Skip-if. Evaluate "Skip if [condition]" literally; when true, append "(SKIPPED)", mark completed.
Nested workflows. Invoke ⤵-marked workflows through the harness mechanism, never inlined. Record the return point (→ § X) first.
Worktree scope. Work only in this tree and branch. Never write kendex project scope unless a refresh brief authorizes it. The CLI refuses project-scope refresh, apply without --plan, and updates --apply in marked lanes unless the refresh lane passes --lane-refresh. If ISSUE_ID differs from the branch, ask: reuse, abort, or switch.
Unsent input is not an instruction. Text already sitting in the composer when a session reaches its prompt belongs to the harness, not to the user: clear it, act on nothing it says.

Harness-Safe Shell

Run exactly one simple command per tool call with explicit arguments. Substitutes, and what each Codex launch mode refuses: references/codex-runtime.md. Normalize delegated command lists the same way before they enter a prompt: an env-assignment prefix becomes a precondition check plus the bare command. A finding's location, description, or cause never crosses argv: write it to a file with the harness file-write tool and bind the path (--items-file, append-file, jq --slurpfile).

Tracker Resolution

An ISSUE_ID starting with issue- is GitHub (TRACKER=github, issue number ${ISSUE_ID#issue-}, repo from caller context else gh repo view --json nameWithOwner); anything else is Linear. A caller-supplied tracker wins; resolve once per workflow into TRACKER and ISSUE_REF (#N for GitHub, the Linear identifier otherwise), the only form a Closes line renders. Run Linear only / GitHub only steps only for that tracker; never run linear.sh against a GitHub item.

State Management

Durable data lives in workflow state through the workflow-state CLI only (set-git-head/set-now, never inline substitution). Location: <state-dir>/workflow-state-[ID].json, where workflow-state --help § State directory resolves <state-dir>.

Other temporary session state, including handoffs, lane status, and reviews, defaults to the repository's tmp/, which kendex's managed ignore block covers in every consumer, while docs/ holds tracked repository content and never receives a kendex ignore rule. A plan or research report is not session state: its durable home is its tracker issue, agents/planner.md § Plan Artifacts places its working copy, and it is never committed.

After compaction, resume from the step after the last completed one: read the item's workflow state, or for an overseer use takeover's bounded resume reads. Apply Delegation before re-sending by stored ID. Stall recovery follows Round Closure. Never repeat completed actions.

Review Pipeline

Finding schema, routing, disposition and the issue audit pipeline: references/finding-disposition.md § Review pipeline.

orch