Project Instructions

Problems with a kendex-owned skill go through kendex report; check ownership in the file first.

A worktree created as an orch lane follows the Refresh ownership and committed outputs heading in these orch Project Instructions, including its local-fleet case when no refresh workflow exists. Respect the lane refresh restriction. A lane explicitly launched to refresh runs kendex refresh or kendex apply only with --lane-refresh, as its brief permits. An ordinary worktree follows its own project resolution and retains actionable drift repair details. Use the explicit lane record to distinguish them.

The hosted overseer coordinates from the control VM. Run item implementation, builds, installation, tests and validation in an owned lane. Where the fleet runs a control-host guard, that guard reads control-host-toolchain.conf. It blocks cargo, npm, pnpm, yarn, npx, tsc, vitest, biome, eslint and next; tools/guard, dev-validate-run and post-merge; and commands from DEV_VALIDATE_CMD or ORCH_POST_MERGE_CMD. This block includes post-merge --refresh-only. The absence of a guard does not permit item builds, installation, tests or validation on the control host. For refresh ownership and synchronization after merge, follow the Refresh ownership and committed outputs heading in these orch Project Instructions. Do not run a blocked command through a wrapper.

Refresh ownership and committed outputs

Use the repository-declared owner for kendex refresh outputs. Kendex uses its lock-record Actions workflow and rolling kendex/lock pull request. Consumers with automatic refresh use their kendex-refresh Actions workflow and rolling kendex/refresh pull request. When no refresh workflow exists and the fleet is local, the overseer owns refresh in the base checkout. Keep the local-fleet full post-merge route. This local owner is not a hosted control VM. Confirm the execution owner and its output paths before adoption. A hosted consumer without a refresh workflow must confirm an authorized owner outside the control VM. The hosted overseer runs sync-base to receive committed outputs after they merge. It does not run post-merge or post-merge --refresh-only on the control VM. Post-merge does not refresh or verify a base checkout that holds .github/workflows/kendex-refresh.yml; in other base checkouts, it reports refresh changes and keeps them. Preserve unrelated tracked and untracked work. Keep each refresh workflow under its existing owner.

Validation routing

• Fix rounds keep their delegated round base. Every kendex change is queue-only, per D027: CI holds the full validation record, and the merge waits on the merge-group run. In kendex a red merge-group run is never answered by merge-pr § 5's rerun-in-place: the lane re-arms only a new head. Where ci-fix leaves the head unchanged, for a flake or a fault ci-fix § 4 places in another pull request, the lane hands back to the overseer with the failing run.

Owner messages

• The owner's time zone is Pacific (America/Los_Angeles). Use the time format in skills/communication/references/messages.md § Times.
• The owner's night, for skills/orch/references/communication-modes.md § Owner asks, is 11 pm to 8 am Pacific.

Proposals

• A kendex Proposal: comment, per skills/orch/references/skill-rules.md § Coordination, Tracked issue creation, carries a Symptom: line (where, when and what broke) or an Owner: line (the owner's note or ask) beside Reached by:, at every source and priority. audit-issues § 6 declines one with neither, per the project-management skill's § Intake.

Consumer refresh review

• This organization's consumers route their kendex refresh pull request to the overseer, never to Copilot, since kendex already reviewed its packages (KEN-3338). Each consumer's committed kendex.settings.toml [env] declares REVIEW_GATE_REFRESH_REVIEW = "overseer", REVIEW_GATE_REFRESH_BRANCH = "kendex/refresh" and REVIEW_GATE_REFRESH_AUTHOR = "vanillagreen-fleet-lanes[bot]". A consumer without them gets a Copilot request on that head; add them there through a lane in that repository.

Cargo round cleanup

At each development round boundary, run the owner-scoped worktree cleanup policy for Cargo output. Use ORCH_ROUND_PRUNE_DISK_PCT as the configured disk threshold. Prune only the owned worktree target directory. If CARGO_TARGET_DIR is elsewhere, report the separate cleanup need and do not delete another owner's output. Use .agents/skills/orch/scripts/round-prune between the round-id and delegation-time stamps.

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.

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]

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.