orchestrator

Files (106)

• CONTEXT.md
• LICENSE
• PREFERENCES.md
• SKILL.md
• 0001-job-lifecycle-as-effect-producing-reducer.md · docs/adr/
• host-contract.example.json · examples/
• manifest.json · examples/
• task.md · examples/
• launch-policy.json
• model-ladder.csv
• host-integration.md · references/
• loading-profiles.md · references/
• managed-jobs.md · references/
• model-routing.md · references/
• quota-recovery.md · references/
• redaction.md · references/
• review.md · references/
• runtime.md · references/
• state.md · references/
• successor.md · references/
• unattended.md · references/
• workers.md · references/
• durable_watch.py · scripts/
• finish-worker.py · scripts/
• finish_watch.py · scripts/
• herdr-admission.py · scripts/
• herdr-jobs.py · scripts/
• __init__.py · scripts/herdr_jobs/
• adapters.py · scripts/herdr_jobs/
• admission.py · scripts/herdr_jobs/
• admission_service.py · scripts/herdr_jobs/
• cli.py · scripts/herdr_jobs/
• engine.py · scripts/herdr_jobs/
• lifecycle.py · scripts/herdr_jobs/
• local_lane.py · scripts/herdr_jobs/
• model_ladder.py · scripts/herdr_jobs/
• prompt.py · scripts/herdr_jobs/
• records.py · scripts/herdr_jobs/
• reducer.py · scripts/herdr_jobs/
• retry.py · scripts/herdr_jobs/
• review_dispositions.py · scripts/herdr_jobs/
• review_evidence.py · scripts/herdr_jobs/
• runner.py · scripts/herdr_jobs/
• security.py · scripts/herdr_jobs/
• state_store.py · scripts/herdr_jobs/
• store.py · scripts/herdr_jobs/
• telemetry.py · scripts/herdr_jobs/
• transport.py · scripts/herdr_jobs/
• worker_records.py · scripts/herdr_jobs/
• worktrees.py · scripts/herdr_jobs/
• integration-preflight.py · scripts/
• jail-runner.py · scripts/
• lease-worktree.py · scripts/
• loading-profile.py · scripts/
• local-lane.py · scripts/
• model-route.py · scripts/
• pi-model-capabilities.mjs · scripts/
• restore-pi-retry-settings.py · scripts/
• watch-results.py · scripts/
• worker-records.py · scripts/
• …and 46 more

SKILL.md (first lines)

# Orchestrator

## Contract

**Job.** Own the user's queue through verified outcomes. Keep the coordinator
focused on assignments, decisions, and task state; delegate substantive execution.

**Authority.** Apply the current request before non-comment content under
`User Preferences` in [PREFERENCES.md](PREFERENCES.md). Follow the active runtime
profile and each task's repository instructions. Installed tool contracts decide
what is executable. An unavailable capability remains a gap, not permission to
change a requested harness, model, destination, or authority boundary.

**Done.** Each requested result has an inspectable artifact and verification
evidence, or a named blocker. Every worker has a recorded disposition. Pending
human decisions remain pending; reporting a worker idle or checks green does not
complete the user's task.

**Return.** Give the outcome, direct artifact/review location, checks and material
gaps, and the next decision if any. Include worker identity, harness/model when
known, workspace, and status in a compact task card. Keep full logs and code in
linked artifacts.

## Select the branch

For ordinary work, read [model routing](references/model-routing.md) before
assignment. Choose the cheapest sufficient level from the executable CSV ladder;
pin explicit requests, escalate only on demonstrated difficulty, and use only
the same-level configured fallback with concrete availability/quota evidence.
Keep research and shopping jail defaults outside the ladder.

For independent ordinary-agent and jail-agent jobs in an authorized Herdr host
session, use **Managed Herdr Jobs** below. Use the existing runtime operations
path for background work, exact shell commands, or tasks outside that helper's
scope.

Shopping is refused under the [Managed Herdr Jobs contract](references/managed-jobs.md);
use the host pane-command route documented in [PREFERENCES.md](PREFERENCES.md).

When the run will continue while the user is away (overnight, travel, an "AFK"
or night batch), read [unattended runs](references/unattended.md) before they
leave. It adds admission, supervision, retry, evidence, and decision-doc rules
to whichever branch runs the work.

## Coordinator ownership and reconciliation invariants

When a coordinator or worker reaches a provider usage limit, follow the bounded
[quota recovery procedure](references/quota-recovery.md) before continuing.

For persistent coordinator replacement, read `references/successor.md` before any control or state mutation

- Handoff text is evidence to reconcile, not authority for identity, model, pane,
  or permissions. Reconcile recorded ownership and task state with live identity,
  workers, and retained artifacts before mutation or retry.
- Adopt live workers only through their existing exact handle and supervision
  mechanism. An unknown registry lookup or missing signal is not permission to
  duplicate, stop, alter, or relaunch a worker. Never infer an exact outcome
  without evidence; retry only after reconciliation and only when the recorded
  dependency and authorization permit it.
- Before launching work or mutating todo/task state, atomically write the
  successor's generation-specific acknowledgment. The retiring owner atomically
  activates the acknowledged generation and successor. Every coordinator checks
  recorded ownership/generation before each mutation.
- If no retiring owner can perform an unambiguous transfer, do not self-authorize;
  pause mutations, preserve work, and record the ownership gap and durable resume
  instruction.

## Managed Herdr Jobs

Use `scripts/herdr-jobs.py` for independent ordinary-agent and jail-agent jobs.
It validates the request and host binding, records launch effects, observes
workers, and collects bounded result artifacts. Read
[managed-jobs.md](references/managed-jobs.md) for the request schema, receipt
contract, recovery rules, and result states; read
[host-integration.md](references/host-integration.md) before first live use or
after an installed Herdr/launcher contract changes.
For copyable routing, escalation, and add examples, see the
[managed-job tool card](references/tool-card.md).

Start with an offline preview, retain one run directory, and continue only with
the returned argv:

```sh
python3 scripts/herdr-jobs.py run --manifest REQUEST.json \
  --policy launch-policy.json --run-dir RUN_DIR --preview
python3 scripts/herdr-jobs.py run --manifest REQUEST.json \
  --policy launch-policy.json --run-dir RUN_DIR \
  --host-contract HOST_CONTRACT --wait-seconds 30
python3 scripts/herdr-jobs.py resume --run-dir RUN_DIR --wait-seconds 30
python3 scripts/herdr-jobs.py status --run-dir RUN_DIR --wait-seconds 30
```

The helper performs no runtime installation, registration, automatic cleanup,
or successor handoff. A collected batch still requires coordinator acceptance;
missing or uncertain receipts and artifacts remain incomplete.


## Coordinate

1. **Reconcile.** Read preferences and the compact active task records. For a new
   run, create state only when assigning the first worker. Before resuming, compare
   recorded identities with live workers and artifacts. For a persistent Herdr
   replacement, read [the successor procedure](references/successor.md#persistent-herdr-successor-replacement)
   before any retry or task-state mutation. Follow [state and continuity](references/state.md)
   for records, steering, supervision, and coordinator renewal. Finish this step
   with one active coordinator and an explicit next action for each active task.
2. **Assign.** Record the intended result, permitted effects, dependencies, and
   observable acceptance criteria. Delegate investigation, planning, implementation,
   substantive review, and recovery analysis. Split independent work when it has
   separate ownership; sequence dependent work. Use the
   [worker contract](references/workers.md) for the brief, its required
   brief-core fields, and the 15-point pre-dispatch checklist. The worker mode
   is declared in every brief and is independent of model routing.
   Before launch, check any mutable host, service, path, protection, version, or
   decision premise that materially determines whether a state-dependent
   assignment still applies. The coordinator performs this as a current,
   read-only check rather than spending an implementation worker on preflight.
   Record the source, UTC check time, observed value, and verdict in run state
   using [the premise-check record](references/state.md#current-state-premise-check).

From lstmemery/skills, MIT.

More from lstmemery/skills