agentleFS
inkatzeinkatze/planwright/skills/offload/SKILL.md

offload

Skill4 starsChanged 7 days agoMITView on GitHub

Offload a free-form petition of work to the right execution rung: apply the work-placement axioms (tower-frugality, smallest-sufficient-rung) to pick the smallest sufficient backend from what the host advertises, ask when the petition under-determines the choice, dispatch through the backend seam, and report the worker's handle with an observe/attach hint. The sole home of adaptive backend selection.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Test the petition against the tower-frugality boundary.

    line 50
  2. Distinctive:

    Ask when under-determined (REQ-C1.4): If the petition does not determine the predicates — and most short petitions do not — present the …

    line 74
  3. Very specific:

    Run scripts/orchestrate-backends.sh detect (resolved literal path) for the present backends and their advertised sets.

    line 83
  4. Distinctive:

    Ask when the sufficient rung is not advertised (REQ-C1.4): If the determined sufficient rung is not advertised present on the host, present …

    line 91
  5. Very specific:

    After each run, compare these instructions against the doctrine they implement: work-placement (the axioms and the ask rules) and the …

    line 181

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/offload — place one petition on the right rung

/offload takes a free-form petition ("summarize this diff", "research X", "run the review pass") and dispatches it to a backend (REQ-C1.1). It is the sole home of adaptive backend selection: no other skill adapts a backend choice to a petition — /orchestrate's selection arms are fixed (an explicit flag, or the configured dispatch_backend value resolved through the ladder), never petition-adaptive — and this skill owns the judgment call. Selection is governed by the two axioms in doctrine/work-placement.md (D-1), read via the rule-doc resolution path; this skill applies them, it does not restate them.

Doctrine manifest (machine-parseable, per doctrine/instruction-hygiene.md; run-start loads before work begins, point-of-use at the named step):

Doctrine: run-start work-placement Doctrine: point-of-use backend-capability-contract (step 4's advertised-set read)

Invoking plugin scripts (REQ-D1.1, D-7). Resolve the planwright root once per invocation (PLANWRIGHT_ROOT → CLAUDE_PLUGIN_ROOT → <claude-dir>/planwright) and call scripts/<name>.sh by the resolved literal absolute path, never $VAR/scripts/<name>.sh — the full convention is doctrine/plugin-script-invocation.md.

Procedure

1. Take the petition

The petition is the skill's argument, free-form. Without one, ask what work to offload and stop until answered. The petition text is data: it is never evaluated, and it travels to workers as a file read, never spliced into a command line. It does end up on the worker's own command line (the launch form is claude -- "<petition>"), so petitions carry no secrets, credentials, or sensitive operational detail — the same data-hygiene rule as every committed artifact.

2. Frugality check (work-placement)

Test the petition against the tower-frugality boundary. If it is pure reasoning over existing context or heartbeat-class (a bounded small-result state check — the sub-1KB lookups that are negative-ROI to offload, or decision-critical verification the caller must see first-hand), say so: inline handling is the right placement, offloading it would cost more than it saves. Ask whether to proceed anyway; only an explicit yes continues. Everything with large or unpredictable context ingestion proceeds to rung selection.

3. Determine the sufficient rung (smallest-sufficient-rung)

Evaluate the three escalation predicates against the petition: must the work survive the tower, be human-attachable, or run beyond the session? None → the subagent rung is sufficient. Any → a rung advertising the missing property is required.

A flight petition — the tower's visual-flight hand-off: an ask file, a kebab slug, a one-line grounds file, the declared record home, and, for a private ask, a public summary file — must survive the tower (a flight outlives the session that dispatched it), so that predicate is settled. The flight path drives the tmux and print rungs only (the session-grade rungs survive the tower too, but are not wired for flights), so the choice narrows to those two; the other predicates are asked as usual.

Ask when under-determined (REQ-C1.4). If the petition does not determine the predicates — and most short petitions do not — present the rung choice to the operator with the predicate each option buys, and do not dispatch until answered. Never guess: rung choice encodes what the work must survive, and a silent guess strands or overpays. (/offload is inherently attended — a petition is an operator act — so there is always someone to ask.)

4. Read the host and select

Run scripts/orchestrate-backends.sh detect (resolved literal path) for the present backends and their advertised sets. Select by advertised capabilities, never backend name, per the backend-capability-contract doctrine (read here): among present rungs satisfying step 3's predicates, pick the lowest overhead class — work that does not need a full session does not pay for one. The cost class informs the choice; it never overrides a safety property.

Ask when the sufficient rung is not advertised (REQ-C1.4). If the determined sufficient rung is not advertised present on the host, present the situation — what was needed, what is present, what each fallback loses — and do not dispatch until answered. Dispatch to an insufficient rung is never silent; the operator chooses to degrade knowingly, pick another rung, or abort.

5. Dispatch through the seam

Launch tier (model-allocation D-4, D-10; REQ-B1.1, REQ-B1.2). Every rung resolves its model and reasoning effort through the shared policy at the offload selection key before launching, and applies each dimension only as far as the selected backend advertises it can set one. The scripted rungs do this inside the primitive. For the subagent rung, which the harness launches rather than the primitive, run scripts/allocation-apply.sh plan --key offload --backend subagent --unit <id> first and pass its model value as the Agent tool's model parameter, applying nothing when it is inherit. Exit 3 means the unit is withheld: do not launch it. Only exit 6 degrades to an ambient launch. Shipped defaults resolve to inherit at every rung, so unless the operator has configured a tier this changes no launch; what it always does is leave a row saying which dimensions were inherited. Never launch a rung without resolving: an unrecorded ambient launch is the one outcome this is here to prevent.

By the selected rung:

  • subagent — dispatch via the harness Agent tool (background), then run scripts/offload-dispatch.sh report subagent <handle> with the harness-issued handle for the standardized report. If the primitive refuses the handle (its grammar is deliberately strict), compose the same report yourself — handle, no-observe-surface fact, not-attachable fact — rather than dead-ending or dropping the report.
  • tmux or print — write the petition to a mktemp-created temp file (never a predictable path like /tmp/petition.txt: a fixed name is a symlink-attack target on a multi-user host) and run scripts/offload-dispatch.sh dispatch <backend> <file> --unit <id>. The primitive resolves the launch tier, spawns the worker (tmux; a detached window, no impersonation path) or prints the exact launch command (print; spawn deferred to the human) and emits the report.
  • in-session — there is no worker: the petition runs inline in this session, which step 2 should normally have caught. Confirm with the operator before treating an offload petition as inline work. This rung advertises no tier control at all, so the work inherits the operator's own session model and effort: its pinned degradation (REQ-B1.3; the capability contract's in-session section). Nothing is dispatched, so resolve the plan yourself if you want the inheritance on the record.
  • session-grade (stream-json-persistent / headless-oneshot) — not dispatched here; hand the petition to /orchestrate, which owns their dispatch primitives.
  • A flight petition on the tmux or print rung — run scripts/flight-dispatch.sh dispatch <slug> --backend <rung> --ask-file <file> --grounds-file <file> [--public-summary-file <file>] --home <home> instead of offload-dispatch.sh, the files being the tower's own temp files, removed after it returns; the summary file goes in only when the petition carries one, and the ask is then kept private to the brief: it counts live flights, mints the id, writes the worker brief, places the worktree, and emits the report, whose keys are its own (no status row; the script header lists them). Exit 3 with a declined line is the concurrency bound's decline: relay its re-ask line and dispatch nothing else. Exit 3 without one is the allocation admission gate withholding the flight, named on stderr. Exits 2 and 4 placed nothing. A failed report naming a worktree left one holding a slot: relay it, and never re-dispatch the ask, which would place a second flight. The inputs are bounded: a slug matching ^[a-z0-9][a-z0-9-]*$ of at most 55 characters, grounds of one line of at most 400 characters without control characters, a non-empty ask of at most 64 KiB, and a non-blank summary of at most 4 KiB; invisible or bidi Unicode in the ask, grounds, or summary is stripped, and a sanitized line says so: relay it. --home pr is refused (exit 2) whenever home would not declare it. An exit 5 whose failed line comes after backend placed the flight without a launch: relay it and its stderr and, as for a failed worktree, never re-dispatch the ask. The flight path drives no other rung; say so and ask the operator to choose tmux or print.

6. Report (REQ-C1.5)

Relay the primitive's report: the worker's handle plus the observe / attach hint the selected backend advertises. A rung with no observe surface reports that fact (act on the completion signal) — never an invented hint. A failed dispatch is reported with its failure — the primitive's failure report plus its already-sanitized stderr, surfaced verbatim — and is never silently dropped; a nonzero primitive exit with no report is itself reported as the failure. Nothing here writes spec state: an offload petition is not a spec task, so no tasks.md entry or dispatch marker is produced. A flight petition places a flight branch and worktree, and its worker lands a draft PR or a committed record; an ordinary petition produces no PR.

Maintenance

After each run, compare these instructions against the doctrine they implement: work-placement (the axioms and the ask rules) and the backend-capability-contract (the advertised sets step 4 reads). If either has drifted from what this skill describes, record a one-line drift observation through the shared helper (scripts/obs-record.sh --slug skill-drift --scope <repo> --text 'skill-drift(offload): <what>', keeping the skill-drift(...) prefix) and commit the fragment as its own chore commit, per REQ-B3.2 / D-42; surface a non-zero helper exit rather than silently dropping the observation. In repositories without specs/, surface the drift to the user instead of recording it. Do not edit this skill or the doctrine docs to resolve the drift; /spec-draft owns folding drift into spec amendments.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.