metis

Wave 18 — Agent Dispatch Prompts

Status: Drafted 2026-05-22 alongside token-reduction-strategy.md §5.1.1.7. Purpose: Five drop-in agent prompts for parallel execution of Wave 18. Phase structure: 3 agents in Phase 1, 2 agents in Phase 2 (see §5.1.1.7 of the umbrella).

How to use this file. Each ## Agent X section below is a verbatim prompt. Copy it whole, paste into a fresh Claude Code session (or pass to the Agent tool with isolation: "worktree"), and wait for the agent to halt at PR. Do not merge until you have reviewed.


Common preamble (applies to all agents)

Every agent prompt below assumes the agent will:

  1. Branch off origin/main, not local HEAD:
    git fetch origin main
    git checkout -b <branch> origin/main
    
  2. Run the full test suite + ruff before opening the PR:
    uv run pytest
    uv run ruff check packages scripts
    uv run ruff format packages scripts
    
  3. Halt at PR — do NOT auto-merge, do NOT start any other sub-item, do NOT modify files outside the assigned partition.
  4. Test count target: each item has a target delta in §5.1.1.3 of the umbrella; aim within ±25% of target.
  5. PR body should reference the umbrella anchor and the assigned sub-item id.

Phase 1 (parallel — no inter-dependencies)

Agent A — Wave 18a-1: Anthropic batch adapter

Branch: wave-18a-1 Size: L (~3–5 sittings of focused work) Phase: 1 Dependencies: none Unblocks: Phase 2 (Agents D, E)

Read first

  1. docs/specs/provider-adapter-contract.md §4.6 — the contract you are implementing. §4.6.1 through §4.6.7 inclusive.
  2. docs/specs/provider-adapter-contract.md §4.5 — the OpenRouter prompt-caching section is the closest existing analog for §4.6 work; mimic its style.
  3. docs/design/token-reduction-strategy.md §5.1.1.2 → 18a-1 — acceptance criteria.
  4. Skim packages/metis/src/metis/core/adapters/anthropic.py (current sync adapter — your batch additions live alongside it, NOT as a new file).

Touches

Modify:

Create:

Acceptance criteria

Implementation gotchas

Completion

uv run pytest                                                # full suite passes
uv run ruff check packages scripts                      # lint clean
uv run ruff format packages scripts                     # auto-format
git add -A
git commit -m "feat(adapters): Anthropic batch submission (Wave 18a-1)

Implements docs/specs/provider-adapter-contract.md §4.6 for the
Anthropic adapter. New canonical types (BatchHandle, BatchStatus,
BatchResult, BatchError) + Usage.pricing_mode + ModelPricing.batch_rates
+ three new ProviderAdapter Protocol methods (default
NotImplementedError) + Anthropic implementation against
/v1/messages/batches. Unblocks Wave 18a-2 / 18a-3.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin wave-18a-1
gh pr create --title "feat(adapters): Anthropic batch submission (Wave 18a-1)" \
             --base main \
             --body "Implements [provider-adapter-contract.md §4.6](docs/specs/provider-adapter-contract.md) per the Wave-18 dispatch plan in [token-reduction-strategy.md §5.1.1.2](docs/design/token-reduction-strategy.md). Unblocks Wave 18a-2 / 18a-3.

🤖 Generated with [Claude Code](https://claude.com/claude-code)"

HALT — do not start any other sub-item.


Agent B — Wave 18a-4: CompactionCache SQLite store (schema only)

Branch: wave-18a-4 Size: S (~1–2 sittings) Phase: 1 Dependencies: none Unblocks: Wave 19 §19a-2

Read first

  1. docs/specs/session-compaction.md §5 — full storage section (§5.1 / §5.2 / §5.3 / §5.4) is the spec for this sub-item.
  2. docs/specs/pattern-store.md §17 — concurrency pattern (threading.RLock()) you are reusing.
  3. Skim packages/metis/src/metis/core/sessions/sqlite_store.py — closest analog for the SQLite-store-in-sessions pattern.

Touches

Create:

Acceptance criteria

Implementation gotchas

Completion

uv run pytest packages/metis/tests/core/sessions/ -x
uv run pytest                                                # full suite
uv run ruff check packages scripts
uv run ruff format packages scripts
git add -A
git commit -m "feat(sessions): CompactionCache SQLite store (Wave 18a-4)

Schema-only SQLite store for the rolling-summary cache per
session-compaction.md §5. threading.RLock concurrency; LRU eviction;
1000-row default cap. No caller wiring — Wave 19 §19a-2 lights it up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin wave-18a-4
gh pr create --title "feat(sessions): CompactionCache SQLite store (Wave 18a-4)" \
             --base main \
             --body "Implements [session-compaction.md §5](docs/specs/session-compaction.md) per the Wave-18 dispatch plan in [token-reduction-strategy.md §5.1.1.2](docs/design/token-reduction-strategy.md). Schema only; no caller wiring (Wave 19 §19a-2 will wire SessionManager).

🤖 Generated with [Claude Code](https://claude.com/claude-code)"

HALT — do not start any other sub-item.


Agent C — Wave 18a-5: session.compaction_* events in catalog

Branch: wave-18a-5 Size: XS (~1 sitting) Phase: 1 Dependencies: none Unblocks: Wave 19 §19a-2

Read first

  1. docs/specs/session-compaction.md §6 — the payload schemas you are registering.
  2. docs/specs/event-bus-and-trace-catalog.md §6 — where the new rows land. Look at the session.* family entries for shape.
  3. packages/metis/src/metis/core/events/payloads.py — the PAYLOAD_REGISTRY (last ~80 lines) and existing session.* payload structs for style.

Touches

Modify:

Acceptance criteria

Implementation gotchas

Completion

uv run pytest packages/metis/tests/core/events/ -x
uv run pytest                                                # full suite
uv run ruff check packages scripts
uv run ruff format packages scripts
git add -A
git commit -m "feat(events): session.compaction_* in catalog (Wave 18a-5)

Three new PSEUDONYMOUS event payloads + PAYLOAD_REGISTRY entries per
session-compaction.md §6. Spec docs/specs/event-bus-and-trace-catalog.md
§6 carries the new rows. No emitter wiring — Wave 19 §19a-2 wires
SessionManager.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin wave-18a-5
gh pr create --title "feat(events): session.compaction_* in catalog (Wave 18a-5)" \
             --base main \
             --body "Implements [session-compaction.md §6](docs/specs/session-compaction.md) per the Wave-18 dispatch plan in [token-reduction-strategy.md §5.1.1.2](docs/design/token-reduction-strategy.md). Catalog wiring only; emitter lands Wave 19 §19a-2.

🤖 Generated with [Claude Code](https://claude.com/claude-code)"

HALT — do not start any other sub-item.


Phase 2 (parallel — both depend on 18a-1’s merge to main)

Prerequisite check before spawning Phase 2: verify wave-18a-1 has merged to origin/main. If not, spawning these agents is wasted work — they will fail at the test step.

git fetch origin main
git log origin/main --oneline -5    # expect to see the 18a-1 PR merge commit

Agent D — Wave 18a-2: metis evaluate --batch-mode

Branch: wave-18a-2 Size: M (~2 sittings) Phase: 2 Dependencies: 18a-1 merged

Read first

  1. docs/specs/provider-adapter-contract.md §4.6 — the adapter contract 18a-1 implemented.
  2. docs/specs/evaluator.md — the existing evaluator surface, especially §6.2 (the metis evaluate CLI).
  3. docs/design/token-reduction-strategy.md §5.1.1.2 → 18a-2.
  4. packages/metis/src/metis/core/eval/cli.py — the current evaluator CLI entry.
  5. packages/metis/src/metis/cli/main.py — where the evaluate subparser registers (around line 76).

Touches

Modify:

Create:

Touches the trace DB (additive):

Acceptance criteria

Implementation gotchas

Completion

uv run pytest                                                # full suite
uv run ruff check packages scripts
uv run ruff format packages scripts
git add -A
git commit -m "feat(eval): metis evaluate --batch-mode (Wave 18a-2)

Submits eval re-runs to the Anthropic Batches API at 50% discount;
persists handles in a new evaluator_batch_handles table;
--collect-batches polls + ingests. Verdicts match sync mode
byte-for-byte (only pricing_mode differs).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin wave-18a-2
gh pr create --title "feat(eval): metis evaluate --batch-mode (Wave 18a-2)" \
             --base main \
             --body "Captures the 50% Anthropic Batches API discount on evaluator backfills per [token-reduction-strategy.md §4 Tier 2](docs/design/token-reduction-strategy.md) and [provider-adapter-contract.md §4.6](docs/specs/provider-adapter-contract.md). Depends on Wave 18a-1.

🤖 Generated with [Claude Code](https://claude.com/claude-code)"

HALT — do not start any other sub-item.


Agent E — Wave 18a-3: scripts/benchmark.py --batch-mode

Branch: wave-18a-3 Size: M (~2 sittings) Phase: 2 Dependencies: 18a-1 merged

Read first

  1. docs/specs/provider-adapter-contract.md §4.6 — the adapter contract 18a-1 implemented.
  2. docs/specs/benchmark.md — the existing benchmark spec; identify where batch fits.
  3. docs/design/token-reduction-strategy.md §5.1.1.2 → 18a-3.
  4. scripts/benchmark.py — the current harness.
  5. benchmarks/RESULTS.md — the format for the new entry you’ll add.

Touches

Modify:

Persistence (new artifact directory pattern — no code-level new files):

Acceptance criteria

Implementation gotchas

Completion

uv run pytest                                                # full suite
uv run ruff check packages scripts
uv run ruff format packages scripts
# Live API spend on a small workload to populate RESULTS.md:
uv run python scripts/benchmark.py --batch-mode --workload fix-a-bug-small
# wait, then:
uv run python scripts/benchmark.py --collect-batch <run_id>
# document results in benchmarks/RESULTS.md
git add -A
git commit -m "feat(benchmark): scripts/benchmark.py --batch-mode (Wave 18a-3)

Submits benchmark runs to the Anthropic Batches API at 50% discount;
persists handles per-run; --collect-batch finalizes. RESULTS.md §Wave-18
documents cost-per-quality on fix-a-bug-small.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin wave-18a-3
gh pr create --title "feat(benchmark): scripts/benchmark.py --batch-mode (Wave 18a-3)" \
             --base main \
             --body "Captures the 50% Anthropic Batches API discount on benchmark re-runs per [token-reduction-strategy.md §4 Tier 2](docs/design/token-reduction-strategy.md) and [provider-adapter-contract.md §4.6](docs/specs/provider-adapter-contract.md). Depends on Wave 18a-1.

🤖 Generated with [Claude Code](https://claude.com/claude-code)"

HALT — Wave 18 closes once this and 18a-2 are merged.


Wave 18 close (operator checklist)

Once all five PRs (wave-18a-1 through wave-18a-5) are merged to origin/main, run the §5.1.1.4 doc-sync checklist from token-reduction-strategy.md:

[ ] AGENTS.md status sentence: "Wave 18 reaches the
    batch-API + compaction-substrate milestone."
[ ] AGENTS.md "What works" — one entry for async batch (18a-1/2/3),
    one for compaction substrate (18a-4/5).
[ ] README.md — test count bumped 1865 → ~1909.
[ ] docs/specs/CHANGES.md — two `pending review` entries
    (`session-compaction.md` + `provider-adapter-contract.md §4.6`)
    move to `verified`.
[ ] docs/specs/event-bus-and-trace-catalog.md §6 — three new
    `session.compaction_*` rows landed via 18a-5.
[ ] docs/specs/evaluator.md — `--batch-mode` documented via 18a-2.
[ ] docs/specs/benchmark.md — `--batch-mode` documented via 18a-3.
[ ] benchmarks/RESULTS.md — §Wave-18 batch-mode measurement landed
    via 18a-3.

Then Wave 19 planning starts; see token-reduction-strategy.md §5.2.