diff --git a/AGENTS.md b/AGENTS.md index 947696c..25c4651 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,12 @@ # offload -Offload is an agent-agnostic, outcome-based delegation skill. The active contract is [SKILL.md](SKILL.md); [CONTEXT.md](CONTEXT.md) and ADR 0012 are the durable project sources of truth. +Offload is an agent-agnostic, outcome-based delegation skill. The active contract is [SKILL.md](SKILL.md); [CONTEXT.md](CONTEXT.md), ADR 0012, and ADR 0013 are the durable project sources of truth. ## Current boundaries - Keep provider, model, reasoning, and command details runtime-dynamic. Do not add copied catalogs, exact model identifiers, role matrices, or integration interfaces to the workflow. +- Offer Offload immediately before native multi-agent delegation for two or more independent, bounded implementation or research assignments; file count alone is not a trigger. +- Require consent before Offload dispatch. Explicit requests, named providers, and accepted offers bypass the proactive threshold; a decline lets native delegation continue and settles the offer for the session. - Keep launch admission simple. A real launch is the usability check; unknown account, entitlement, billing, quota, capacity, or benchmark information must not block it. - Keep implementation changes isolated until the orchestrator reviews the actual diff and relevant checks. - Keep research bounded, source-backed, and explicit about inference and uncertainty. diff --git a/CONTEXT.md b/CONTEXT.md index cd4c56c..185b2e7 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,6 +1,6 @@ # Offload context -Offload is a lean, agent-agnostic workflow for delegating bounded implementation and research work. The orchestrator chooses how to execute the workflow from the tools and evidence available at runtime. See [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md). +Offload is a lean, agent-agnostic workflow for delegating bounded implementation and research work. The orchestrator chooses how to execute the workflow from the tools and evidence available at runtime. See [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md) and [ADR 0013](docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md). ## Core contract @@ -40,3 +40,9 @@ The automatic return of unfinished work to the orchestrator after worker failure **Workspace isolation**: Separation appropriate to the risk of the delegated work, such as a disposable worktree for implementation or a disposable project copy for research. The workflow specifies the outcome, not shell-specific commands. + +**Delegation lane**: +One independent, bounded assignment with its own acceptance criteria. File count does not determine whether work has multiple delegation lanes. + +**Offer gate**: +The point immediately before an orchestrator would start a native multi-agent workflow for two or more delegation lanes. Offload uses implicit skill invocation to ask for consent at this point instead of relying on global host instructions. diff --git a/README.md b/README.md index 177319d..925bad2 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ # Offload -Offload is a small, agent-agnostic delegation contract. It lets an orchestrator hand a bounded implementation or research assignment to a worker while keeping responsibility for review, unfinished work, and the final report. +Offload is a small, agent-agnostic delegation contract. It lets an orchestrator hand a bounded implementation or research assignment to another worker provider, with implicit pre-delegation offers, runtime model and effort selection, and orchestrator verification. ## Contract The orchestrator: -- uses Offload only for an explicit request, a named worker provider, an accepted offer, or a host-approved proactive offer; +- uses Offload when the user explicitly asks to offload, names a worker provider, accepts an offload offer, or implicitly at the offer gate before native multi-agent delegation for two or more independent bounded assignments; - describes the assignment, paths or questions, acceptance criteria, deliverables, and authority boundary; - discovers current worker tools, model choices, and reasoning options at runtime; -- makes a task-based choice using capabilities, availability, cost, judgment, and advisory benchmark evidence; +- chooses the worker, model, and reasoning effort dynamically using task demands, capabilities, availability, cost, judgment, and advisory benchmark references when cost or quality materially matters; - treats a real launch as the usability check. Unknown account, entitlement, billing, quota, capacity, or benchmark information does not block launch; - keeps the worker bounded and forbids nested delegation; - reviews the actual result and relevant verification before accepting it; @@ -25,14 +25,14 @@ Implementation runs in a disposable isolated worktree or project copy. The orche Research starts with bounded questions and evidence responsibilities. The worker uses credible sources, and the orchestrator checks that every material citation resolves and supports its claim. Inference, uncertainty, disagreement, missing evidence, and stale evidence stay visible in the final synthesis. -## Proactive offers +## Proactive offer gate -The host may offer Offload for implementation with at least three independently gated assignments when the repository is clean, or for a read-only audit or research task with at least two independent evidence tracks. The user must consent before dispatch. A refusal settles the offer for the session. +Offload activates implicitly immediately before an orchestrator begins a native multi-agent workflow for two or more independent, bounded assignments (delegation lanes) in implementation or research. The orchestrator asks once, before native worker dispatch, whether the user prefers another available worker provider. File count alone does not trigger an offer. Explicit requests, named providers, and accepted offers bypass the two-lane threshold. The user must consent before dispatch; a refusal settles the offer for the session and allows native multi-agent delegation to proceed. ## Repository layout - [SKILL.md](SKILL.md) is the active delegation contract. -- [CONTEXT.md](CONTEXT.md) and [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md) define the current vocabulary and decisions. +- [CONTEXT.md](CONTEXT.md), [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md), and [ADR 0013](docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md) define the current vocabulary and decisions. - [Benchmark references](docs/research/2026-09-07-benchmark-references-for-runtime-routing.md) are advisory evidence for runtime choices. - [Execution scope](scripts/check-execution-scope.sh) and [execution workspace](scripts/execution-workspace.sh) helpers retain generic implementation safety. - [Research workspace](scripts/make-research-workspace.sh) and [research cleanup](scripts/cleanup-research-workspace.sh) helpers retain bounded disposable snapshots. diff --git a/SKILL.md b/SKILL.md index 8ff693b..761fdae 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,19 +1,19 @@ --- name: offload -description: Use when the user explicitly asks to offload work to another worker, names a worker provider, or accepts an offload offer. Offer proactively for large, independently gated implementation or research work when the host instructions permit it. +description: Delegate bounded implementation or research work to another worker provider. Use when the user explicitly asks to offload, names a worker provider, accepts an offload offer, or when the orchestrator is about to start a native multi-agent workflow for two or more independent, bounded assignments. --- # offload Offload is an optional delegation workflow. The calling agent remains the orchestrator: it owns the assignment, reviews the result, finishes unfinished work, and gives the final report. -Use this skill when the user explicitly asks to offload or run work on another worker, names a worker provider, or accepts a proactive offer. Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local. A worker must not dispatch another worker. +Keep narrow factual answers, explanations, single-source lookups, and focused code reviews local. Explicit requests, named worker providers, and accepted offers bypass the two-lane proactive threshold. A worker must not dispatch another worker. ## Before delegation - Describe one bounded assignment. Include the objective, in-scope paths or questions, acceptance criteria, deliverables, and the boundary of the worker's authority. - If the user named a provider, honor that choice. Otherwise inspect the worker tools currently available to the host. When the choice matters, use each tool's current native help or model-listing facility rather than relying on copied instructions. -- Choose the worker, model, and reasoning effort from the task, required capabilities, current availability, cost, relevant benchmark references, and judgment. The benchmark note is advisory evidence, not a routing table. +- When worker, model, or reasoning-effort choices materially affect expected cost or quality, consult the benchmark reference note. Prefer current evidence for the exact model and effort under consideration. If exact evidence is absent, select from task demands, required capabilities, current availability, cost, and judgment. Missing or stale benchmark evidence never blocks an attempted launch. - Unknown entitlement, billing, quota, capacity, or benchmark information never blocks an attempted launch. The real launch is the definitive usability check. - Start one worker per bounded assignment by default. Split work only when the pieces are genuinely independent and each has its own acceptance criteria. @@ -40,14 +40,16 @@ Do not encode provider command syntax, copied help text, exact model identifiers - Do not hide a failed launch with an Offload-managed second automatic attempt or a silent provider switch. The orchestrator may make a new, explicit decision after reporting what failed. - The orchestrator completes the remaining work when it can do so safely. Otherwise it reports a resumable partial result, the failure, and the precise blocker. -## Proactive offer +## Proactive offer gate -Host instructions may offer Offload without an explicit request only when all of the following are true: +When an orchestrator is about to start a native multi-agent workflow for two or more independent, bounded assignments (delegation lanes) in implementation or research: -- implementation has at least three independently gated assignments and the Git repository is clean, or -- a read-only audit or research task has at least two distinct evidence tracks. - -Ask for consent before dispatching. A refusal settles the offer for the rest of the session. Do not offer it for narrow work. The host keeps the final result and remains responsible for verification. +- Offer Offload once immediately before native worker delegation begins, asking whether the user prefers another available worker provider. +- Keep the offer vendor-neutral unless the user already named a provider. +- Require user consent before dispatching Offload workers. If the user declines, proceed with the native multi-agent workflow and do not offer again during that session. +- File count alone does not trigger an offer; a single coherent change spanning multiple files remains local unless it contains two or more independent assignments. +- Explicit requests, named worker providers, and accepted offers bypass this threshold. +- Implicit activation at this gate is model-selected guidance rather than a guaranteed host lifecycle hook. ## Final report @@ -57,5 +59,6 @@ State the bounded assignment, worker choice when relevant, actual result, files - [CONTEXT.md](CONTEXT.md) defines the project's terms and durable contract. - [ADR 0012](docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md) records why the workflow stays outcome-based and runtime-dynamic. +- [ADR 0013](docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md) records why the proactive offer uses implicit invocation before native multi-agent delegation. - [Benchmark references](docs/research/2026-09-07-benchmark-references-for-runtime-routing.md) records optional decision evidence. - The generic [execution scope checker](scripts/check-execution-scope.sh) and [execution workspace helper](scripts/execution-workspace.sh) enforce the retained implementation safety outcomes. diff --git a/docs/adr/0003-use-a-portable-proactive-offer-contract.md b/docs/adr/0003-use-a-portable-proactive-offer-contract.md index b79fcfc..1d7a704 100644 --- a/docs/adr/0003-use-a-portable-proactive-offer-contract.md +++ b/docs/adr/0003-use-a-portable-proactive-offer-contract.md @@ -1,5 +1,5 @@ --- -status: accepted +status: superseded by ADR 0013 --- # Use a portable proactive-offer contract diff --git a/docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md b/docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md new file mode 100644 index 0000000..8356463 --- /dev/null +++ b/docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md @@ -0,0 +1,9 @@ +--- +status: accepted +--- + +# Use implicit invocation for the offer gate + +Offload will use its skill description to activate when an orchestrator is about to start a native multi-agent workflow for two or more independent, bounded implementation or research assignments. The skill will ask once whether the user prefers another available worker provider before native delegation begins. Explicit requests, named providers, and accepted offers bypass this threshold; a decline lets native delegation continue and suppresses the offer for the session. File count is not a trigger because one coherent change may span many files. This replaces the global host-instruction nudge from ADR 0003, which duplicated routing policy outside the skill and still failed to trigger reliably. + +This is a model-selected gate rather than a guaranteed lifecycle hook. Hosts that support implicit skill invocation can apply it without global configuration; other hosts still require explicit invocation or a host-specific integration. diff --git a/tests/test_repository_consistency.ps1 b/tests/test_repository_consistency.ps1 index d102c4b..2196725 100644 --- a/tests/test_repository_consistency.ps1 +++ b/tests/test_repository_consistency.ps1 @@ -13,6 +13,7 @@ $activeRelative = @( 'SKILL.md', 'README.md', 'AGENTS.md', 'CONTEXT.md', 'CLAUDE.md', '.github/workflows/ci.yml', 'docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md', + 'docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md', 'docs/research/2026-09-07-benchmark-references-for-runtime-routing.md' ) $activeContent = foreach ($relative in $activeRelative) { @@ -55,8 +56,25 @@ foreach ($relative in @( $skill = [IO.File]::ReadAllText((Join-Path $root 'SKILL.md')) $readme = [IO.File]::ReadAllText((Join-Path $root 'README.md')) -foreach ($link in @('CONTEXT.md', 'docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md', 'docs/research/2026-09-07-benchmark-references-for-runtime-routing.md', 'scripts/check-execution-scope.sh', 'scripts/execution-workspace.sh')) { +foreach ($link in @('CONTEXT.md', 'docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md', 'docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md', 'docs/research/2026-09-07-benchmark-references-for-runtime-routing.md', 'scripts/check-execution-scope.sh', 'scripts/execution-workspace.sh')) { Assert-True ($skill.Contains($link) -or $readme.Contains($link)) "active docs retain link: $link" } +$supersededAdrs = @( + '0001-maintain-shell-native-helper-families.md', + '0003-use-a-portable-proactive-offer-contract.md', + '0005-bound-model-routing-to-gemini-and-explicit-rules.md', + '0007-cross-library-publication-boundaries.md', + '0008-runtime-model-selection-through-adapters.md', + '0009-select-compatible-workers-before-offering-offload.md', + '0010-agy-preflight-discovery.md', + '0011-launch-first-admission-and-orchestrator-fallback.md' +) +foreach ($docPath in @('SKILL.md', 'README.md', 'AGENTS.md', 'CONTEXT.md', 'CLAUDE.md')) { + $content = [IO.File]::ReadAllText((Join-Path $root $docPath)) + foreach ($adr in $supersededAdrs) { + Assert-False ($content.Contains($adr)) "$docPath omits link to superseded ADR: $adr" + } +} + [Console]::Out.WriteLine("all repository consistency checks passed ($($script:TotalTests) tests)") diff --git a/tests/test_repository_consistency.sh b/tests/test_repository_consistency.sh index ca2b51e..3856a24 100644 --- a/tests/test_repository_consistency.sh +++ b/tests/test_repository_consistency.sh @@ -9,7 +9,7 @@ assert_file() { [[ -f "$1" ]] || { printf 'FAIL: missing file: %s\n' "$1" >&2; e assert_absent() { [[ ! -e "$1" ]] || { printf 'FAIL: path exists: %s\n' "$1" >&2; exit 1; }; pass "$2"; } active_content='' -for relative in SKILL.md README.md AGENTS.md CONTEXT.md CLAUDE.md .github/workflows/ci.yml docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md docs/research/2026-09-07-benchmark-references-for-runtime-routing.md; do +for relative in SKILL.md README.md AGENTS.md CONTEXT.md CLAUDE.md .github/workflows/ci.yml docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md docs/research/2026-09-07-benchmark-references-for-runtime-routing.md; do assert_file "$root/$relative" "active repository file exists: $relative" active_content=$active_content$(cat "$root/$relative") active_content=$active_content$'\n' @@ -47,9 +47,25 @@ done skill=$(<"$root/SKILL.md") readme=$(<"$root/README.md") -for link in CONTEXT.md docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md docs/research/2026-09-07-benchmark-references-for-runtime-routing.md scripts/check-execution-scope.sh scripts/execution-workspace.sh; do +for link in CONTEXT.md docs/adr/0012-keep-offload-outcome-based-and-runtime-dynamic.md docs/adr/0013-use-implicit-invocation-for-the-offer-gate.md docs/research/2026-09-07-benchmark-references-for-runtime-routing.md scripts/check-execution-scope.sh scripts/execution-workspace.sh; do [[ "$skill" == *"$link"* || "$readme" == *"$link"* ]] || { printf 'FAIL: active docs lack link: %s\n' "$link" >&2; exit 1; } pass "active docs retain link: $link" done +for doc in SKILL.md README.md AGENTS.md CONTEXT.md CLAUDE.md; do + doc_content=$(<"$root/$doc") + for adr in \ + 0001-maintain-shell-native-helper-families.md \ + 0003-use-a-portable-proactive-offer-contract.md \ + 0005-bound-model-routing-to-gemini-and-explicit-rules.md \ + 0007-cross-library-publication-boundaries.md \ + 0008-runtime-model-selection-through-adapters.md \ + 0009-select-compatible-workers-before-offering-offload.md \ + 0010-agy-preflight-discovery.md \ + 0011-launch-first-admission-and-orchestrator-fallback.md; do + [[ "$doc_content" != *"$adr"* ]] || { printf 'FAIL: %s links to superseded ADR: %s\n' "$doc" "$adr" >&2; exit 1; } + pass "$doc omits link to superseded ADR: $adr" + done +done + printf 'all bash repository consistency checks passed (%s tests)\n' "$total" diff --git a/tests/test_workflow_static.ps1 b/tests/test_workflow_static.ps1 index f3a32ac..d8d4b26 100644 --- a/tests/test_workflow_static.ps1 +++ b/tests/test_workflow_static.ps1 @@ -45,13 +45,25 @@ $readme = $activeContent[$activePaths[1]] $ciPath = Join-Path $root '.github/workflows/ci.yml' $ci = [IO.File]::ReadAllText($ciPath) -foreach ($phrase in @('bounded', 'runtime', 'native help', 'acceptance criteria', 'launch', 'unfinished', 'orchestrator', 'disposable', 'citation', 'inference', 'nested')) { +foreach ($phrase in @('bounded', 'runtime', 'native help', 'acceptance criteria', 'launch', 'unfinished', 'orchestrator', 'disposable', 'citation', 'inference', 'nested', 'offer gate', 'two or more', 'consent', 'independent')) { Assert-Contains $skill $phrase "SKILL.md states $phrase" } -foreach ($phrase in @('runtime', 'benchmark', 'launch', 'unfinished', 'isolated', 'citation', 'inference', 'provider')) { +foreach ($phrase in @('runtime', 'benchmark', 'launch', 'unfinished', 'isolated', 'citation', 'inference', 'provider', 'offer gate', 'two or more', 'consent')) { Assert-Contains $readme $phrase "README.md states $phrase" } +$expectedDescription = 'Delegate bounded implementation or research work to another worker provider. Use when the user explicitly asks to offload, names a worker provider, accepts an offload offer, or when the orchestrator is about to start a native multi-agent workflow for two or more independent, bounded assignments.' +Assert-Contains $skill "description: $expectedDescription" 'SKILL.md uses exact settled frontmatter description' + +$frontmatterMatch = [regex]::Match($skill, '(?s)^---\r?\n(.*?)\r?\n---') +Assert-True $frontmatterMatch.Success 'SKILL.md has YAML frontmatter' +Assert-False ($frontmatterMatch.Groups[1].Value.Contains('Do NOT')) 'SKILL.md frontmatter omits negative Do NOT sentence' + +foreach ($stalePhrase in @('host instructions', 'host-approved', 'three independently gated', 'at least three')) { + Assert-NotContains $skill $stalePhrase "SKILL.md omits stale offer phrase: $stalePhrase" + Assert-NotContains $readme $stalePhrase "README.md omits stale offer phrase: $stalePhrase" +} + foreach ($content in @($skill, $readme)) { Assert-NotContains $content '```' 'active contract has no copied command blocks' } diff --git a/tests/test_workflow_static.sh b/tests/test_workflow_static.sh index 1847280..9489aa3 100644 --- a/tests/test_workflow_static.sh +++ b/tests/test_workflow_static.sh @@ -35,12 +35,26 @@ for path in "$root/SKILL.md" "$root/README.md" "$root/AGENTS.md" "$root/CONTEXT. assert_file "$path" done -for phrase in bounded runtime 'native help' 'acceptance criteria' launch unfinished orchestrator disposable citation inference nested; do +for phrase in bounded runtime 'native help' 'acceptance criteria' launch unfinished orchestrator disposable citation inference nested 'offer gate' 'two or more' consent independent; do assert_contains "$skill" "$phrase" "SKILL.md states $phrase" done -for phrase in runtime benchmark launch unfinished isolated citation inference provider; do +for phrase in runtime benchmark launch unfinished isolated citation inference provider 'offer gate' 'two or more' consent; do assert_contains "$readme" "$phrase" "README.md states $phrase" done + +expected_description="description: Delegate bounded implementation or research work to another worker provider. Use when the user explicitly asks to offload, names a worker provider, accepts an offload offer, or when the orchestrator is about to start a native multi-agent workflow for two or more independent, bounded assignments." +assert_contains "$skill" "$expected_description" "SKILL.md uses exact settled frontmatter description" + +frontmatter=$(sed -n '2,/^---$/p' "$root/SKILL.md") +[[ "$frontmatter" != *"Do NOT"* ]] || { printf 'FAIL: SKILL.md frontmatter contains Do NOT\n' >&2; exit 1; } +pass "SKILL.md frontmatter omits negative Do NOT sentence" + +for stale_phrase in "host instructions" "host-approved" "three independently gated" "at least three"; do + [[ "$skill" != *"$stale_phrase"* ]] || { printf 'FAIL: SKILL.md contains stale phrase: %s\n' "$stale_phrase" >&2; exit 1; } + pass "SKILL.md omits stale offer phrase: $stale_phrase" + [[ "$readme" != *"$stale_phrase"* ]] || { printf 'FAIL: README.md contains stale phrase: %s\n' "$stale_phrase" >&2; exit 1; } + pass "README.md omits stale offer phrase: $stale_phrase" +done for content in "$skill" "$readme"; do [[ "$content" != *'```'* ]] || { printf 'FAIL: active contract has copied command blocks\n' >&2; exit 1; } pass 'active contract has no copied command blocks'