Repository navigation
Description
Summary
Simplify Offload from an adapter-backed orchestration framework into a lean, outcome-based skill. The orchestrator should discover available worker CLIs and current model choices at runtime, choose a vendor, model, and reasoning level for the task, launch the worker, and judge the result.
The skill must stop trying to make every orchestrator route identically. In particular, it must not block a usable worker because entitlement, billing route, quota, or capacity cannot be proven before launch. A real launch is the usability check.
This issue implements the accepted direction recorded in docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md. The issue is self-contained because that ADR may not yet exist in every installed copy.
Problem
Offload began as a practical way to delegate work to AGY. Its scope grew into a general orchestration framework with:
- vendor adapter contracts and normalized catalogs;
- a central model policy and role matrix;
- entitlement, billing, quota, and capacity admission checks;
- retry routes, pinned selections, outcome histories, and resource ledgers;
- separate Bash and PowerShell implementations of the same workflow;
- long mode documents containing commands, schemas, and step-by-step recipes.
These controls added failure points without making worker output reliable. The clearest failure is admission. A CLI can exist and be usable, yet Offload refuses to launch it because the adapter cannot prove account entitlement, billing route, or remaining capacity. The skill then falls back before any worker has run.
The current design also freezes model behavior that should remain contextual. Models, CLI syntax, prices, limits, and benchmark results change. Copying them into the skill makes the instructions stale and constrains the orchestrator to a protocol that may fit the previous release better than the current task.
Desired result
Offload is a workflow contract for fallible collaborators. It tells the orchestrator what outcomes it must protect, while leaving runtime discovery and routing to the orchestrator's judgment.
The finished skill should be short enough to read as one workflow. It may branch between implementation and research, but those branches must state obligations rather than reproduce shell sessions. Installed worker tools provide their own current help and model listings.
User stories
- As a user asking to offload work, I want the orchestrator to try an installed worker without speculative account admission, so that unknown quota or billing data does not reject a usable worker.
- As a user who names AGY or another vendor, I want the orchestrator to honor that choice when the tool is usable, so that Offload remains useful for my preferred worker.
- As a user who does not name a vendor, I want the orchestrator to choose a suitable available worker at runtime, so that I do not have to maintain routing configuration.
- As an orchestrator, I want to inspect current CLI help, model listings, and other native discovery features when useful, so that I do not depend on copied commands or stale catalogs in the skill.
- As an orchestrator, I want to choose the vendor, model, and reasoning level from the assignment's difficulty, required capabilities, expected cost, current availability, and relevant evidence, so that routing remains contextual.
- As an orchestrator, I want benchmark references to inform but never determine routing, so that missing, stale, or mismatched benchmark data cannot block work.
- As a maintainer, I want vendor commands, model identifiers, and pricing facts to stay outside the skill, so that ordinary provider changes do not require an Offload release.
- As a worker, I want a bounded assignment with explicit deliverables, constraints, and acceptance criteria, so that I can return a result the orchestrator can judge.
- As an orchestrator delegating implementation, I want worker changes isolated from the live checkout until review, so that an incomplete or out-of-scope result cannot silently become accepted work.
- As an orchestrator accepting worker implementation, I want to inspect the actual changes and run checks relevant to the assignment, so that a worker's success claim is never the acceptance decision.
- As an orchestrator delegating research, I want workers to use credible sources and return claim-level support, so that the synthesis is grounded rather than plausible-sounding.
- As an orchestrator accepting research, I want to check citations, source quality, conflicts, and unsupported inference, so that the final answer distinguishes evidence from judgment.
- As a user, I want unfinished work to return to the orchestrator when a worker fails or reaches a limit, so that recovery stays hands-off.
- As a user, I want worker failure to avoid silent provider switching and hidden retry loops, so that I can understand which worker actually ran and what failed.
- As a user, I want temporary workspaces and worktrees removed after accepted work is integrated or retained evidence is collected, so that delegation does not leave local clutter.
- As a user, I want the final report to name the worker work performed, verification completed, unresolved claims, and any fallback to the orchestrator, so that I can judge the result.
- As a maintainer, I want the repository tests to enforce the outcome contract instead of the deleted routing protocol, so that tests do not recreate the same framework in another form.
Architectural decisions
One public workflow contract
Rewrite SKILL.md as the primary agent-facing contract. Keep only the trigger, delegation boundary, runtime choice guidance, implementation branch, research branch, failure fallback, cleanup duty, and final reporting duty.
Collapse modes/execution.md, modes/repo-research.md, and modes/web-research.md into concise branches in SKILL.md, unless a separate document has a clear responsibility that would make SKILL.md harder to follow. Do not retain separate mode documents merely to preserve the current structure.
The workflow must not include vendor invocation examples, copied --help output, exact model names, model-role tables, command recipes, JSON result schemas, lifecycle state machines, or numbered shell procedures.
Runtime discovery and routing
The orchestrator discovers available worker tools when Offload runs. It may use native help, model listing, a harmless probe, or a real bounded launch. Offload defines no normalized adapter API and no universal catalog format.
If the user names a worker vendor, prefer it. Otherwise, the orchestrator chooses based on the task. Cost-sensitive work may favor a cheaper capable worker. Difficult implementation, synthesis, or review may justify a stronger model or more reasoning. These are judgment calls, not fixed role mappings.
The benchmark note in docs/research/2026-09-07-benchmark-references-for-runtime-routing.md is advisory context. DeepSWE is the initial coding reference. LiveBench is the initial general-capability reference. FutureSearch Deep Research Bench and DeepResearch Bench are the initial research references. Missing coverage or disagreement between a benchmark and the current task must not stop launch.
Launch-first admission
Remove all Offload requirements to prove entitlement, billing route, quota, remaining capacity, or retry capacity before launch. Checking that a worker command exists is useful. A provider's own launch response determines whether the selected worker can run.
Do not add a replacement prediction layer. If launch fails, the orchestrator resumes or completes the unfinished assignment. It may tell the user what happened in the final report. Offload does not retry through its own routing engine and does not silently switch vendors.
Verification owns trust
Treat all workers as fallible collaborators.
For implementation, the orchestrator must:
- give each worker a bounded assignment and acceptance criteria;
- keep changes isolated until review;
- inspect the actual worker-authored change for scope and intent;
- run the smallest relevant tests, checks, or direct verification;
- accept and integrate only work that passes review;
- finish rejected or unfinished work itself;
- remove disposable worktrees after integration and verification.
For research, the orchestrator must:
- give each worker bounded questions or evidence responsibilities;
- keep repository snapshots and temporary artifacts separate from the live checkout when needed;
- prefer primary and authoritative sources for factual claims;
- check that cited sources resolve and support the claims attributed to them;
- identify inference, disagreement, missing evidence, and stale evidence;
- synthesize the answer itself or review a worker synthesis before accepting it;
- remove disposable workspaces after retaining the evidence needed for the final answer.
The skill promises these procedures, not infallible output.
Delete obsolete machinery
Remove model-policy.json and code, tests, fixtures, and active documentation whose only purpose is any of the following:
- vendor adapter normalization;
- model catalog normalization or deterministic selection;
- entitlement, billing, quota, or capacity preflight;
- model pins, quality routes, or Offload-managed retries;
- routing outcome history;
- capacity, resource, assignment, or lifecycle ledgers created for the old framework;
- paired shell implementations that only encode the deleted orchestration protocol;
- publication compatibility rules for adapters;
- prescribed worker role matrices and structured output envelopes.
Historical ADRs and research notes may remain when they explain why the design changed. Mark superseded decisions clearly. Remove or rewrite active documentation that still presents the old machinery as current behavior.
Do not delete a generic helper only because it is a script. A helper may remain if it directly enforces one of the current safety outcomes, such as checking execution scope or cleaning a marked disposable workspace, and if its interface does not depend on the removed adapter, routing, quota, retry, or ledger system. Keep the minimum set. The skill should state the required outcome without embedding the helper's command syntax.
Keep the existing invocation boundary
Keep the existing user-facing trigger and proactive offer policy. Explicit requests to use AGY, another worker, or Offload still invoke the skill. Narrow work stays local. Proactive offers remain subject to the repository's existing thresholds and user consent rules.
Workers must not dispatch nested workers. This remains an instruction and scope boundary, not a claim that Offload can enforce every worker's behavior across vendors.
Documentation changes
- Rewrite
SKILL.mdaround the desired workflow. - Rewrite
README.mdto describe the same behavior without commands or protocol details. - Keep
CONTEXT.mdand ADR 0012 aligned with the implementation. - Keep the benchmark reference note separate from the skill so references can change without changing workflow semantics.
- Mark older specs, contracts, and ADRs as historical or remove them when they no longer explain a retained decision.
- Remove stale links and installation claims that refer to deleted modes, policies, adapters, scripts, fixtures, or tests.
Verification plan
Replace protocol-level tests with tests at the highest useful boundaries.
- Add a static contract test for
SKILL.mdandREADME.md. It should confirm that the required outcomes are present and that active instructions contain none of the removed concepts, vendor commands, exact model IDs, routing matrices, quota admission, retry engines, or ledger schemas. - Keep or simplify isolation and execution-scope tests around the generic boundary that remains after cleanup. Test that worker changes stay outside the live checkout until accepted, out-of-scope changes fail review, accepted changes can be integrated, and the disposable worktree is removed afterward.
- Keep or simplify research acceptance tests around source support. Test that unsupported claims or broken citations are rejected and that a supported result can be accepted without a routing or provenance schema.
- Add a failure-path test with a fake worker command. A failed launch must return the assignment to the orchestrator path without retrying or choosing another provider.
- Add a repository consistency test that rejects references to removed active files and verifies that the installed skill package includes the remaining required files.
Avoid rebuilding vendor CLIs in fixtures. Tests should simulate only success, unsupported output, or launch failure at the process boundary.
Acceptance criteria
-
SKILL.mdreads as an outcome-based workflow and contains no vendor CLI commands, copied help, exact model IDs, model-role matrix, adapter interface, normalized catalog, quota protocol, routing algorithm, retry engine, outcome history, or ledger schema. - The skill tells the orchestrator to discover available workers and current options at runtime when useful.
- The skill permits dynamic vendor, model, and reasoning-level choice, with relevant benchmarks used only as advice.
- Missing or unknown entitlement, billing, quota, capacity, or benchmark data never blocks a worker launch.
- A real launch is the definitive usability check.
- A failed worker launch or run returns unfinished work to the orchestrator without an Offload-managed retry or silent provider switch.
- Every worker receives a bounded assignment and may not dispatch nested workers.
- Worker-authored implementation remains isolated until the orchestrator reviews the actual change and runs relevant verification.
- Research acceptance requires credible sources, checked claim support, valid citations, and labeled inference or uncertainty.
- The orchestrator owns the final result and reports what it verified, what remains uncertain, and whether it completed worker work itself.
- Disposable implementation worktrees are removed after accepted changes are integrated and verified.
- Disposable research workspaces are removed after necessary evidence is retained.
-
model-policy.jsonand obsolete adapter, preflight, routing, retry, ledger, and duplicated protocol machinery are removed. - Any retained helper directly enforces a current safety outcome and has no dependency on the removed orchestration framework.
-
README.md,CONTEXT.md, active ADRs, tests, and installation instructions describe the same current behavior. - Historical documents are clearly marked and no active document links to a deleted artifact.
- The remaining test suite passes on each environment the simplified repository still claims to support.
Out of scope
- A universal worker adapter API.
- A normalized cross-vendor model catalog.
- Automatic benchmark scraping, caching, or score normalization.
- Usage, quota, entitlement, billing, or price prediction.
- Cross-run worker performance history or learned routing.
- Offload-managed provider failover or retries.
- Adding support for a new vendor as part of this cleanup.
- Guaranteeing worker correctness or treating a vendor sandbox as a complete security boundary.
- Changing the proactive offer thresholds or user consent policy.
Implementation note
Prefer deletion over compatibility shims. The repository should end with fewer concepts, files, and tests. If a retained component needs the old adapter, routing, quota, retry, or ledger vocabulary to make sense, it probably belongs in the deletion set.
Activity