Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions CONTEXT.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Offload context

Offload delegates bounded work to `agy` processes while the calling agent remains responsible for scope, verification, and reporting.
Offload delegates bounded work through compatible worker adapters while the calling agent remains responsible for scope, verification, and reporting. The repository includes a reference adapter, but selection is provider-neutral.

## Publication boundary

Expand All @@ -24,9 +24,17 @@ The calling agent that plans assignments, dispatches workers, and verifies their
_Avoid_: Controller, parent agent

**Worker**:
An `agy` process assigned one bounded role. Its process environment is marked as worker context, so the dispatch, launcher, and execution-workspace lifecycle interfaces reject nested assignment, process, or worktree creation.
A process launched through a compatible adapter and assigned one bounded role. Its process environment is marked as worker context, so the dispatch, launcher, and execution-workspace lifecycle interfaces reject nested assignment, process, or worktree creation.
_Avoid_: Subagent, child agent

**Compatible worker adapter**:
An adapter that implements the worker contract and has verified support for the assignment's required capabilities. An installed agent CLI alone does not establish compatibility.
_Avoid_: Any installed CLI, universal worker support

**Worker selection**:
The orchestrator's choice of a configured, compatible worker provider before making an offload offer. Selection checks authenticated access, current entitlement, and usage limits against the assignment, verification, and one retry, accounting for workers sharing quota. Rank eligible workers by task capability and expected quality, with remaining capacity as the tie-breaker. Unknown usage excludes automatic selection but permits explicit user selection with disclosed uncertainty and otherwise established access. An explicit user provider choice takes precedence, subject to eligibility checks. The offer names the selected worker and explains the choice. The protocol-2 selector and capacity ledger implement this behavior. See ADR 0009.
_Avoid_: Always offer one provider, implicit provider switch

**Dispatch ledger**:
The orchestrator-owned `offload-dispatch-state-v1` record for admitted assignments. It records parentage, depth, child IDs, budgets, owned and frozen paths, lifecycle state, artifacts, and rejected nested-dispatch events.
_Avoid_: Worker tree, implicit scheduler state
Expand Down
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# offload

`offload` is an agent-agnostic skill for delegating bounded code and research work to headless workers. The calling agent remains responsible for isolation, verification, cleanup, and reporting; the worker handles the assigned task. The reference adapter launches `agy`.
`offload` is an agent-agnostic skill that delegates bounded plan execution and research tasks to headless workers through a configured vendor adapter. The calling agent remains responsible for isolation, verification, cleanup, and reporting; the worker handles the assigned task. The repository includes a reference adapter, but selection and admission use a provider-neutral contract.

Whatever CLI coding agent loads this skill serves as the orchestrator: Claude Code, Codex CLI, or any agent that can read instructions and run shell commands. `agy` is the worker, not the orchestrator. The orchestrator never accepts worker claims at face value. It verifies work mechanically through test gates, execution scope checks, verbatim quote matching, independent citation auditing, and direct repository checks.
Whatever CLI coding agent loads this skill serves as the orchestrator: Claude Code, Codex CLI, or any agent that can read instructions and run shell commands. The configured adapter launches the worker, not the orchestrator. The orchestrator never accepts worker claims at face value. It verifies work mechanically through test gates, execution scope checks, verbatim quote matching, independent citation auditing, and direct repository checks.

Offload's online-research workflow is adapted from Asa by Achibukz, used with permission. Do not publish a private repository URL, branch, commit, screenshots, or copied text.

Expand Down Expand Up @@ -38,7 +38,7 @@ and acceptance gates.
- **Filesystem isolation.** Research workflows run inside disposable workspaces outside the live repository. Workers receive only scoped snapshots of declared files, keeping live repository files untouched.
- **Mechanical verification.** Execution workflows require a clean git working tree, execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen path checks, and automated test gates.
- **Prohibition on nested dispatch.** Assignments instruct workers not to dispatch nested workers.
- **Vendor-neutral worker adapters.** [`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md) defines the assignment, lifecycle, capability/model discovery, ownership, and normalized-result boundary. The current AGY launcher is the reference adapter; verification and cleanup remain with the orchestrator.
- **Vendor-neutral worker adapters.** [`docs/worker-adapter-contract.md`](docs/worker-adapter-contract.md) defines the assignment, lifecycle, capability/model discovery, ownership, and normalized-result boundary. The included launcher is a reference adapter; verification and cleanup remain with the orchestrator.
- **Orchestrator-owned dispatch.** `dispatch-worker.sh` or `dispatch-worker.ps1` is the only workflow entry point that admits an assignment, creates its worktree, and starts its worker process. The dispatcher sets `OFFLOAD_WORKER_CONTEXT=1` for the worker. Worker-context calls to the dispatcher, launcher, or execution-workspace lifecycle helpers fail closed and record a `nested_dispatch_rejected` event.
- **Structured follow-up requests.** A worker may return a request for more work in `structured_output`, but that request is data for the orchestrator to review. It never starts a process automatically.
- **Bounded assignment ledger.** The dispatcher records assignment ID, parent ID, depth, child IDs, role, owned and frozen paths, lifecycle timestamps, output and error paths, worktree manifest, and timeout/resource budget in an `offload-dispatch-state-v1` ledger. Root limits for depth, child width, timeout, and total resource units are immutable for descendants; admission rejects attempts that would exceed them.
Expand All @@ -48,14 +48,14 @@ and acceptance gates.

| Host path | Required runtime | Required tools | CI system |
|---|---|---|---|
| Native Windows | PowerShell 7+ | Git and `agy` | `windows-latest` |
| Linux with Bash | Bash 3.2+ | Git, `agy`, `jq`, and Python 3 | `ubuntu-latest` |
| macOS with Bash | Bash 3.2+ | Git, `agy`, `jq`, and Python 3 | `macos-latest` |
| Linux or macOS with PowerShell | PowerShell 7+ | Git and `agy` | Supported by contract, not a required CI job |
| Native Windows | PowerShell 7+ | Git and a configured adapter | `windows-latest` |
| Linux with Bash | Bash 3.2+ | Git, `jq`, Python 3, and a configured adapter | `ubuntu-latest` |
| macOS with Bash | Bash 3.2+ | Git, `jq`, Python 3, and a configured adapter | `macos-latest` |
| Linux or macOS with PowerShell | PowerShell 7+ | Git and a configured adapter | Supported by contract, not a required CI job |

### Helper family selection

Orchestrators select helper scripts based on their current shell (`.sh` for Bash, `.ps1` for PowerShell), never by host operating system detection or universal launchers. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`.
Orchestrators select helper scripts based on their current shell (`.sh` for Bash, `.ps1` for PowerShell), never by host operating system detection or universal launchers. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`.

### Worker adapters

Expand All @@ -77,7 +77,7 @@ the caller checkout into a sandbox.
## Requirements

- A CLI coding agent that can read skills and run shell commands (Claude Code, Codex CLI, or similar).
- [`agy`](https://antigravity.google), the Antigravity CLI, available on `PATH`, user-local bin (`~/.local/bin/agy` on POSIX, `%USERPROFILE%\.local\bin\agy.exe` on Windows), or configured via `AGY_BIN`.
- The configured adapter, available on `PATH` or at the path accepted by the launcher. The included reference adapter can use `agy`, but no provider is assumed by the public contract.
- For execution workflows: a git repository with a clean working tree (`git status --porcelain` is empty). Research workflows run in disposable workspaces.

## Installation
Expand Down Expand Up @@ -359,11 +359,11 @@ Place this instruction block in your agent's project context file (`AGENTS.md`,
```markdown
## Offload delegation

- Use Offload when the user asks to offload, run work through a specific vendor adapter, or accepts an AGY offer.
- Offer AGY once, before starting, when implementation splits into three or more independently gated tasks in a clean Git repository, or when a read-only audit or external research requires multiple distinct work lanes. Count research lanes by distinct questions or evidence responsibilities, not browser tabs.
- Use Offload when the user asks to offload, run work through a specific vendor adapter, or accepts a compatible-worker offer.
- Offer a selected compatible worker once, before starting, when implementation splits into three or more independently gated tasks in a clean Git repository, or when a read-only audit or external research requires multiple distinct work lanes. Count research lanes by distinct questions or evidence responsibilities, not browser tabs.
- Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local.
- Ask before dispatching.
- Ask once per session. If the user declines, continue locally without offering AGY again in that session.
- Ask once per session. If the user declines, continue locally without offering another worker in that session.
- When Offload applies, let its skill instructions choose the appropriate workflow mode.
```

Expand Down
19 changes: 10 additions & 9 deletions SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ If you are a dispatched worker, stop here. Return worker results to your orchest

## What this skill does

`offload` delegates execution and research tasks to headless workers through a vendor adapter. The reference adapter launches `agy`, but the workflow contract does not depend on a vendor or exact model ID. You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection.
`offload` delegates execution and research tasks to headless workers through a configured adapter. A reference adapter is included, but the workflow contract does not depend on a vendor or exact model ID. You remain the orchestrator. You decompose tasks, set acceptance criteria or bounded questions, and verify evidence and gates. Workers handle exploration, test authoring, code implementation, diff review, and research evidence collection.

You never accept worker claims at face value. You verify output through mechanical checks, test execution, diff inspections, or secondary reviews.

Expand All @@ -32,19 +32,20 @@ checks, cleanup, and acceptance gates.

Select the helper family matching your current host shell:

- **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `agy`, `jq`, and Python 3.
- **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require only PowerShell 7 (`pwsh`), Git, and `agy`. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`.
- **POSIX shells (Bash 3.2+)**: Use `.sh` scripts in `scripts/`. Requires Git, `jq`, Python 3, and the configured adapter's own executable.
- **PowerShell (PowerShell 7+)**: Use `.ps1` scripts in `scripts/`. Native Windows orchestrators require PowerShell 7 (`pwsh`), Git, and the configured adapter. Windows workflows do not require Bash, WSL, Git Bash, Python, or `jq`.

Check these requirements before dispatching workers:

1. **Offer before dispatch.** When reaching this skill unprompted, offer the choice to the user first following the proactive offer contract. Describe the planned dispatch and ask for confirmation. Ask once per session. A negative response settles the decision for the rest of the session.
2. **Local factual lookups.** Keep a single factual lookup local with the orchestrator; do not offer or route it to offload.
3. **`agy` availability.** Verify `agy` is invokable. The launcher resolves `AGY_BIN` first if set, then `PATH`, then the user-local bin directory (`~/.local/bin/agy` on POSIX, `%USERPROFILE%\.local\bin\agy.exe` on Windows). An invalid explicit `AGY_BIN` fails immediately without fallback.
3. **Adapter availability.** Verify the configured adapter is invokable and can return a protocol-2 catalog. The adapter must prove authenticated access, current entitlement, billing route, and usage capacity for the selected account and model. An installed CLI or static catalog entry is not enough.
4. **Git working tree.** Writing workflows (`modes/execution.md`) require a clean git repository (`git rev-parse --is-inside-work-tree` and empty `git status --porcelain`). Research workflows (`modes/repo-research.md`, `modes/web-research.md`) operate in isolated disposable workspaces.
5. **Preflight model availability check.** Before dispatching the first worker in a run:
5. **Preflight compatible-worker check.** Before dispatching the first worker in a run:
- Read repository-root `model-policy.json` (resolved relative to helper scripts, never the caller's working directory).
- Ask the configured adapter for its live catalog, then filter by availability, quota, required capabilities, and supported effort.
- If no eligible model exists or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently switch providers or fall back to an unverified default.
- Ask the configured adapters for live catalogs, then filter by verified access, entitlement, billing route, fresh usage, required capabilities, and supported effort.
- Estimate assignment, verification, and one retry unit, including active shared reservations. If no eligible worker exists or availability cannot be established, block dispatch and return the affected work to the caller. Do not silently switch providers or fall back to an unverified default.
- An explicit provider is checked first and is never replaced silently. Unknown usage is allowed only for an explicit provider after the other checks pass, and the selection records the uncertainty.
- Avoid repeating catalog discovery for every worker in the same run unless the adapter reports that availability changed.
6. **Policy installation, updates, and revert.**
- `model-policy.json` is located at repository root alongside helper scripts. Installation must copy the entire skill directory (including `model-policy.json`).
Expand Down Expand Up @@ -80,8 +81,8 @@ Offload routes all workers through the repository-root `model-policy.json` and t

Execution workers must use `scripts/dispatch-worker.sh` or `scripts/dispatch-worker.ps1`, which calls this lower-level launcher after admission. The direct forms below are for the isolated research stages described in the research mode documents.

- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role <role> [--route <default|quality-retry>] --output <out> --error <err> --lifecycle <lifecycle.json> --assignment-id <worker_id> --attempt <1|2> --mode <mode> --verification-baseline <baseline> --resource-ledger <ledger.json> -- <agy args...>`
- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role <role> [--route <default|quality-retry>] --output <out> --error <err> --lifecycle <lifecycle.json> --assignment-id <worker_id> --attempt <1|2> --mode <mode> --verification-baseline <baseline> --resource-ledger <ledger.json> '--' <agy args...>`
- **POSIX shells**: `"$OFFLOAD_ROOT/scripts/run-agy-json.sh" --role <role> [--route <default|quality-retry>] --adapter <adapter> --provider <provider> --output <out> --error <err> --lifecycle <lifecycle.json> --assignment-id <worker_id> --attempt <1|2> --mode <mode> --verification-baseline <baseline> --resource-ledger <ledger.json> -- <adapter args...>`
- **PowerShell**: `& "$OffloadRoot/scripts/run-agy-json.ps1" --role <role> [--route <default|quality-retry>] --adapter <adapter> --provider <provider> --output <out> --error <err> --lifecycle <lifecycle.json> --assignment-id <worker_id> --attempt <1|2> --mode <mode> --verification-baseline <baseline> --resource-ledger <ledger.json> '--' <adapter args...>`

In PowerShell command expressions, always quote the delimiter (`'--'`).

Expand Down
Loading
Loading