subagent-delegation

name	subagent-delegation
description	Repo-specific conventions for briefing implementation subagents and gating their PRs before ready-for-review. Use when fanning work out across parallel subagents/worktrees. Triggers: "delegate this", "spin up agents", "brief a subagent", "gate this PR".

subagent-delegation: repo conventions for briefs and gates

Only what's specific to this repo — general delegation practice is assumed. Source: the 2026-07-02 cycle (PRs #723–#732, six first-try gate passes).

Before dispatching to a new execution agent

An agent that cannot run this repo's verification loop cannot ship here, regardless of model quality — every merge gate is verification (swift build/swift test, lint, evidence, smoke lanes). Proven 2026-07-08: a pi-vs-codex race on the same brief produced a plausible ~1,000-line implementation from pi that died unverifiable (its sandbox blocked swift), while codex shipped a reviewed PR in under an hour. So on an agent's first dispatch:

• Confirm its sandbox/harness can execute swift build (or mise run web:check for web work) before handing it a slice.
• Spot-check context absorption with a short quiz (issue tracker? evidence gate? PR label vocabulary?) — agents differ in how strongly they weight AGENTS.md; a wrong answer means the brief must carry that context explicitly.
• Fresh worktrees need Frameworks/GhosttyKit.xcframework rsynced from the main checkout before swift build works at all.

The brief must include

• Bootstrap: git fetch origin main && git checkout -B claude/<slug> origin/main. Name the branch in the brief; base on fresh main, never the orchestrator's branch.
• Grounded file:line facts marked re-verify, don't trust — if reality differs, stop and report instead of guessing. (Caught a wrong import-graph claim in #725 before it became a wrong deletion.)
• Environment caveats pointer: docs/development/remote-sessions.md (evidence token, mise, Playwright browser).
• For test-adding work: a mutation check — re-break the covered bug, prove the new test fails, revert, report which mutation ran.
• Evidence rules: never fabricate; blocked evidence is an explicit PR state with the reason; a green CI run link is the remote hosted-evidence convention.
• Ship protocol: draft PR only (the gate flips it ready); Closes #N in the body; on agent+task issues do not touch claim labels — sync-execution-state.py owns that lane (backlog/CLAUDE.md).
• PR-body Mergeability fields need real prose — the readiness check (scripts/pr-readiness.py) fails on empty/default/n/a answers; when a field doesn't apply, write why it doesn't. Read that script before the session's first PR body — it is the body contract.
• Author the Evidence section with a placeholder slot for the hosted CI link so the gate edits the PR body exactly once, at ready-flip (every body update resends the full text).

The gate, before a PR leaves draft

Calibrate depth to risk — default tiers until #733 lands: docs/test-only → diff read + CI + a directed review pass suffice; behavior → add an independent suite re-run (don't trust reported counts); security/UI → add the adversarial/visual passes below.

• Always: read the full diff; cite the green CI run in the Evidence section; check Closes #N.
• Security-touching: adversarial pass — bypass paths, every failure path no worse than pre-change behavior, signer/verifier secret parity.
• UI-touching: view the screenshots yourself; run the Playwright full project yourself (web-ci.yml runs fast only); when hosted upload is blocked, deliver screenshots to the owner through the session.
• Merge mechanics: pre-check with git merge-tree --write-tree (the legacy three-arg form false-negatives real conflicts); after resolving, re-run the full suite on the merged tree, capturing output to a file before filtering.
• Record a gate note in the PR body (what re-ran, on which commit), then flip to ready.

Sequencing

Serialize PRs touching package.json/lockfile; everything else parallelizes in worktrees. web/tests/LEDGER.md conflicts are expected and additive — keep both blocks. One watch owns merge-event follow-through (merge and CI-success events don't push to sessions) — scripts/pr-wait.sh <sha> is that watch.