git:20260901.da763a3 to git:20260907.e7e2dcd

# cheap-dev-workers Development

## Local setup

Claude Code auto-discovers `agents/` once the plugin is installed; no setup

script needed on that side.

GitHub Copilot CLI also auto-discovers `agents/` from the installed plugin,

reading the same `.claude-plugin` manifests — no Copilot-specific copy of the

role definitions exists. From the repository root, install it without touching

Codex agents with:

```bash

bash scripts/setup.sh --plugin cheap-dev-workers

```

Select GitHub Copilot CLI in the interactive installer. Scripts and CI may use

`--runtime copilot --yes`. See @../../docs/agents/copilot-cli.md.

Codex CLI has no plugin-bundled agent mechanism, so its subagents must be

copied into a personal or trusted-project agents directory:

```bash

bash scripts/setup.sh --plugin cheap-dev-workers

```

Select Codex CLI in the interactive installer. This copies

`codex-agents/*.toml` into `~/.codex/agents/` (personal scope only — this

plugin does not install into a project's `.codex/agents/`).

## Worker Role sources

`roles/` is the authority. `agents/*.md` and `codex-agents/*.toml` are

projections of it and must never be hand-edited: the runtimes and the

installers read those fixed paths, so they stay committed, but

`scripts/render-roles.sh --check` fails the moment they stop matching

`roles/`.

```bash

plugins/cheap-dev-workers/scripts/render-roles.sh --check # read-only

mise run render-roles # regenerate

```

The artifacts carry no generated-by header, deliberately: adding one would

change the prompt bytes that reach the model. Ownership is marked out of band

instead — by this section, by `linguist-generated=true` in `.gitattributes`,

and by the failing check.

`roles/shared.role` holds semantics, not bytes. It declares each invariant's

id, which roles carry it, and a `class`:

- `shared` — same meaning in both runtimes; the wording still differs, which is

unfinished normalization rather than design

- `runtime` — deliberately different because the runtimes differ (Claude plugin

subagents cannot nest; Codex allows one hop)

- `drift` — differs with no runtime justification

Per-role, per-runtime prose lives in `roles/<role>.role`, because the same

invariant is worded differently in all four roles today. The grammar has no

quoting, escaping, or continuation: anything it cannot hold verbatim is

rejected with a `file:line` error rather than silently transformed.

### What the checks do and do not prove

`--check` proves the eight artifacts are exactly what `roles/` projects, and

`tests/cheap-dev-workers-agents-content.sh` proves the native seams (required

fields, `tools:` / `sandbox_mode`, no model or effort pins, no unsupported

Claude nesting claim). Neither proves the semantics are right, and no test here

observes an actual dispatch.

Verifying real behaviour — that a role is launched, keeps its permission

boundary, and gets the requested model — needs an installed plugin plus runtime

event metadata (`subagent.started` / `subagent.completed`). That is a separate

integration seam, not part of this renderer. The Waza suites evaluate skills

that *describe* routing; they never load these artifacts.

Normalizing the divergent wording is blocked on that seam: collapsing four

wordings into one changes prompt behaviour, and nothing here can currently

observe a regression.

## Checks

From the repository root:

```bash

for test in tests/cheap-dev-workers-*.sh; do bash "$test"; done

bash tests/plugin-version-bump.sh

mise run lint

```

## Releases

Bump `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` together

whenever shipped files under this plugin directory change. Claude Code uses

that string as the update cache key, so `claude plugin update` is a no-op

until it changes. See [version management](https://code.claude.com/docs/en/plugins-reference#version-management).

Copilot uses the same `.claude-plugin/plugin.json` version string as its

update key. Codex personal agents are copies in `~/.codex/agents/`; after a

release run root `scripts/upgrade.sh --plugin cheap-dev-workers`.

The repository-root setup, upgrade, and uninstall scripts are the only public

lifecycle entry points. They detect installed plugin state before acting;

plugin-local scripts are internal post-action helpers.

## Routing contract

- Skills request roles, never plugin identities or provider models. Runtime

adapters resolve them: Claude Code and Copilot CLI dispatch

`cheap-dev-workers:<role>`; Codex requests the installed role name.

- Choose the role before the model. Prefer an available named worker for

bounded, context-heavy work. If the role is unavailable or unsupported,

callers may use one generic worker only when they can reproduce its

permission and task boundary. Explicit pre-execution dispatch/runtime errors

such as capacity, rate-limit, rejected-model, or launch errors follow the same

fallback; a generic pre-execution failure continues in primary. Once a worker

begins its workload, its failure is the task result. If execution status is

ambiguous, stop instead of risking duplicate work.

- When a named worker's tools cover only part of the work, split the part it

can do and keep the rest in primary. Falling back to a generic worker for

the whole task because one sub-question needs an unavailable tool defeats

the routing contract.

- State the preference in each role's `description`, not only here. Runtimes

surface the description to the dispatching agent and nothing else from this

plugin, so a routing rule that lives only in this file cannot be followed.

- Keep architecture, implementation, scope, test selection, Git mutation, and

remote-state decisions in primary.

- Limit a root task to four concurrent workers and one nested hop. No same-role

recursion. Claude plugin subagents cannot nest, so primary relays

`repo-explorer` → `check-runner` and `check-runner` → `log-summarizer`. Other

runtimes may use the same paths only when supported.

- Pass minimum caller-scoped context. Potentially sensitive logs cross a model

boundary only after `scripts/sanitize-log.sh` succeeds.

## Model choice

Claude, Codex, and Copilot role definitions leave model and reasoning effort

unset. Callers request the cheapest available model capable of each bounded

task and the lowest sufficient effort, starting routine work at `low`, when the

runtime supports per-dispatch selection. Otherwise the runtime inherits its

parent or configured defaults. Skills name no provider or model, so targets can

change without coupling workflow instructions.

The `agents/*.md` (Claude Code and Copilot CLI) and `codex-agents/*.toml`

(Codex CLI) definitions carry the same hard rules and instructions in each

tool's native format. Both are rendered from `roles/`, so they cannot be kept

in sync by hand — edit the source and re-render. A role's single `capability`

becomes the `tools:` frontmatter and the `sandbox_mode` together; Copilot maps

that `tools:` list onto its own tool names, so the permission boundary survives

without a Copilot-specific list.

Claude plugin subagents do not support `hooks` or `permissionMode`, so the

check-runner's Bash mutation boundary is prompt-enforced. The primary supplies

exact commands and treats an unexpected tracked-source change as failure.

## Codex CLI dispatch gotchas

- [codex-cli] A prompt that both names an `agent_type` and asks the

orchestrator to fully inherit conversation history gets rejected by

Codex's collaboration layer. Dispatch these agents without full history

inheritance (e.g. `fork_turns: none`) instead.

- [codex-cli] The root session relays whatever the subagent's final message

claims (counts, exit codes) without independently checking raw output.

Ask explicitly for the subagent's raw output when the claim matters,

rather than trusting the root session's summary of it.

## Claude Code Compatibility

`CLAUDE.md` is a symbolic link pointing to `AGENTS.md`. Edit `AGENTS.md`

directly.