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
18 changes: 18 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ jobs:
- name: Run execution scope suite
run: bash tests/test_execution_scope.sh

- name: Run publication compatibility suite
run: bash tests/test_publication_compatibility.sh

- name: Check Codex adapter syntax
run: bash -n scripts/run-codex-json.sh

macos-bash:
name: macOS Bash contract suite
runs-on: macos-latest
Expand All @@ -33,6 +39,12 @@ jobs:
- name: Run execution scope suite
run: bash tests/test_execution_scope.sh

- name: Run publication compatibility suite
run: bash tests/test_publication_compatibility.sh

- name: Check Codex adapter syntax
run: bash -n scripts/run-codex-json.sh

windows-powershell:
name: Windows PowerShell contract suite
runs-on: windows-latest
Expand All @@ -48,3 +60,9 @@ jobs:

- name: Run execution scope suite
run: pwsh -File tests/test_execution_scope.ps1

- name: Run publication compatibility suite
run: pwsh -File tests/test_publication_compatibility.ps1

- name: Run Codex adapter suite
run: pwsh -File tests/test_codex_adapter.ps1
20 changes: 8 additions & 12 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy

## Key decisions and architecture

- **Orchestrator-agnostic, worker-fixed**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. `agy` is reserved for the worker role. The self-guard stops an `agy` process that loads this skill. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it.
Dispatch control: `dispatch-worker.sh` and `dispatch-worker.ps1` are orchestrator-owned admission interfaces. They record bounded assignment parentage and budgets, create worktrees, and start workers. Worker-context calls to dispatch, launch, or execution-workspace lifecycle helpers fail closed and are recorded; worker follow-up requests remain data until the orchestrator admits them.

- **Orchestrator-agnostic, adapter-backed workers**: Any agent capable of reading `SKILL.md` and running shell commands can orchestrate, including Claude Code, Codex CLI, and similar agents. Worker execution runs through the adapter contract, with `agy` as the reference adapter. The self-guard stops a dispatched worker that loads this skill, and the dispatcher plus worker-context guards enforce that workflow boundary. Every assignment instructs workers not to dispatch nested workers, but the skill cannot enforce that prohibition if a worker ignores it.
- **Modular mode architecture**: Root `SKILL.md` is a lightweight router under 500 lines owning shared preconditions, mode inference, explicit overrides, mode loading, and the shared report contract. Workflows are isolated into dedicated mode documents: `modes/execution.md` (code and file mutations), `modes/repo-research.md` (bounded local investigations and audits), and `modes/web-research.md` (online research, synthesis, and citation auditing).
- **Routing hierarchy**: Once invoked, the router resolves mode in this order:
1. Honor explicit mode override.
Expand All @@ -15,21 +17,15 @@ Agent-agnostic skill that delegates plan execution and research to headless `agy
6. Route mixed local and external questions to `web-research` with a scoped snapshot.
Single factual lookups stay local with the orchestrator.
- **Shell-native helper families with platform parity**: Offload maintains two shell-native helper families: Bash 3.2+ for POSIX shells and PowerShell 7+ for PowerShell orchestrators. Orchestrators select the helper family for their current shell. Native workflows on Windows require only PowerShell 7+, Git, and `agy` without WSL, Git Bash, Python, or `jq`. Platform parity ensures equivalent workflow behavior, workspace isolation, provenance artifacts, and safety checks across supported shells.
- **Worker roles, models, and modes**:
- Worker routing is governed centrally by `model-policy.json` targeting the Gemini 3.8 Flash baseline:
- `scout` (`gemini-3.8-flash-low`, `--mode plan`): Discovers file paths for provisional tasks.
- `gate-author` (`gemini-3.8-flash-high`, `accept-edits`): Generates automated test files from acceptance criteria.
- `implementer` (`gemini-3.8-flash-high`, `accept-edits`): Modifies owned code files.
- `reviewer` (`gemini-3.8-flash-high`, `--mode plan`): Evaluates recorded review artifacts adversarially against criteria.
- `researcher` (`gemini-3.8-flash-high`, `--mode plan`): Collects structured findings for bounded questions within assigned scopes.
- `synthesizer` and `auditor` (`gemini-3.8-flash-high`, `--mode plan`): Synthesizes claim ledgers and audits citation veracity for web research.
- A historical live smoke comparison against Gemini 3.7 retained Flash for every role because the proposed Pro split did not complete its mandatory synthesis stage.
- **Worker roles, preferences, and modes**:
- Worker routing is governed centrally by `model-policy.json` and a vendor adapter. The policy stores each role's internal preference, independent effort, and required capabilities. The adapter provides the live catalog and translates the selected model into worker arguments.
- Selection is deterministic after filtering for availability, quota, effort, capabilities, and static security constraints. Family hints are descriptive only.
- **Model routing policy and recovery accounting**:
- Preflight model availability check against the resolved `agy` installation before first dispatch.
- Launchers take `--role <role>` and optional `--route default|quality-retry`, resolving models dynamically and rejecting caller `--model` or `--effort` arguments.
- Stable assignment identity across attempts with a strict ceiling of at most one retry (maximum two attempts per worker).
- Operational failures (crashes, timeouts, unparsable output) trigger at most one same-model retry (`--route default`). Quality failures (gate failures, scope violations, audit rejections) may use `--route quality-retry` only when an evidence-backed escalation target is configured in policy.
- Explicit Gemini quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers.
- Operational failures (crashes, timeouts, unparsable output) trigger at most one retry of the pinned selection (`--route default`). Quality failures (gate failures, scope violations, audit rejections) retry the pinned selection or require an explicit fallback or handoff when the pin is unavailable.
- Explicit quota exhaustion triggers immediate handoff of unfinished work to the calling orchestrator without blocking on sibling workers.
- The orchestrator records all attempts and verification verdicts in `routing-outcomes.json` in the scratch workspace. Web research provenance optionally records routing attempt records in `provenance.json`.
- **Corrected worker guarantees**: `--mode plan` is a version-sensitive behavioral hint, not a write barrier. The accepted `agy 1.1.25` probe blocked the tested direct write outside the permitted artifact area, but plan mode is not a sole safety control. `--add-dir` grants access without confining writes. Security and containment rely on filesystem isolation (disposable workspaces with scoped file snapshots for research) and mechanical verification (clean git working trees, execution scope checks, frozen path diffs, and test gates for execution).
- **Verification over claims**: Worker JSON status (`SUCCESS`/`ERROR`) is not trusted alone. Implementers are verified via mechanical execution scope checks (`check-execution-scope.sh` or `check-execution-scope.ps1`), frozen paths, and gate commands. Reviewers are verified against the recorded artifact digest and verbatim quote matching. Research findings are verified against the live repository with read-only orchestrator commands after scope validation, with direct checks on high-priority claims and sampling on lower-priority claims.
Expand Down
25 changes: 22 additions & 3 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,35 @@

Offload delegates bounded work to `agy` processes while the calling agent remains responsible for scope, verification, and reporting.

## Publication boundary

Published source skills remain vendor-neutral. `grill-with-docs` owns its
interview and documentation workflow and can run without offload. Offload is
an optional delegation layer, while adapters own vendor launch syntax, model
catalogs, capability probes, and output parsing. Consumers depend on stable
capabilities, model preferences, separate reasoning effort, and normalized
results, not vendor names or exact model IDs.

Capability support does not enforce security. The orchestrator remains
responsible for isolation, ownership, cleanup, execution scope checks, and
acceptance gates. The source repository is authoritative; generated and
installed copies are release outputs. See
`docs/contracts/publication-compatibility.md` and ADR 0007.

## Language

**Orchestrator**:
The calling agent that plans assignments, dispatches workers, and verifies their results.
_Avoid_: Controller, parent agent

**Worker**:
An `agy` process assigned one bounded role and prohibited from dispatching more workers.
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.
_Avoid_: Subagent, child agent

**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

**Helper family**:
A shell-native set of scripts that implements the same offload operations and command contracts for one supported shell.
_Avoid_: Port, rewrite
Expand All @@ -37,11 +56,11 @@ The host-independent rule that defines when an orchestrator offers offloading, h
_Avoid_: Hook, Claude hook

**Model routing**:
The policy that selects a Gemini model and reasoning effort for an offload worker assignment. It uses role defaults and explicit escalation rules, prioritizing verified task success, then elapsed time and quota use.
The policy and adapter process that selects an available model and independent reasoning effort for an offload worker assignment. It uses a role preference, task capabilities, live availability, static security rules, and quota state.
_Avoid_: Mode routing, unrestricted model selection

**Role default**:
The model and reasoning effort assigned to an offload role unless a documented escalation rule applies.
The internal preference, reasoning effort, and required capabilities assigned to an offload role. The adapter resolves those requirements to a current model.
_Avoid_: Best model, permanent model assignment

**Model policy**:
Expand Down
Loading
Loading