Orchestrata Ultimate › Plans › briefs › TEMPLATE-sonnet-agent

Brief template: a Sonnet subagent dispatched from a Claude Code coordinator

Source: plans/briefs/TEMPLATE-sonnet-agent.md at 8a2cb42ad · last changed 2026-10-22 · first committed 2026-10-22 · 144 lines.

Prose pending.

Plan text

Brief template: a Sonnet subagent dispatched from a Claude Code coordinator

Use this for every Agent-tool dispatch (builder, wirer, refactorer, test-writer, auditor) in an orchestrata worktree. The worker sees only the brief, so the brief must carry everything below. Copy the skeleton, fill every <...>, and delete nothing from CONSTRAINTS: a guard you leave out is one the worker will trip. Defects found after a dispatch go into plans/briefs/IMPROVEMENT-LOG.md and come back here as a changed line.

Dispatch hooks (measured 2026-10-06, memory agent-brief-hook-fields):

• The five labels GOAL: FILES: CONSTRAINTS: DONE WHEN: VERIFY: must appear literally.
• builder/wirer/refactorer: a line that STARTS with DESIGN_WAIVER: <reason> (or a plans/contracts/ path), or require-design-before-build.sh (RUL-022) rejects the dispatch.
• Pass model: "sonnet" explicitly on the Agent call (docs/supervisor-workflow.md §E).

Coordinator pre-dispatch check (do it, then delete this section from the sent brief)

Accuracy: each line must be measured this session, with the command recorded.

• [ ] Every sha in the brief equals git rev-parse origin/master / git rev-parse HEAD now.
• [ ] Every FILES path exists (ls), or is listed under Create.
• [ ] Every VERIFY binary and wrapper exists (command -v, ls).
• [ ] Every fence module imports in the worktree venv.
• [ ] Every VERIFIED fact carries its source: file:line, command output, or log path.
• [ ] Every fleet the work touches was probed up this session.
• [ ] A commit packet: the coordinator staged its files and ran the staged-content scanners (scripts/check_staged_secrets.py) and test-review.py on touched tests, then unstaged.

Completeness: the worker can finish without asking.

• [ ] Each stage has a STOP condition and says what to report at it.
• [ ] Each irreversible step (push, merge, deploy, promote) names its precondition and its rollback.
• [ ] The guard corpus below is restated in full.
• [ ] The REPORT section asks for raw outputs, not summaries.
• [ ] Nothing in the brief asks the worker to decide design. A fork is a STOP.

Skeleton

DESIGN_WAIVER: <ADR/RUL/user instruction that settles the design, with date> — or delete for auditor
Date: <YYYY-MM-DD> · Origin: <user request, verbatim, with date> · Executor: Sonnet <agent type>
in worktree <abs path> on branch <name> tracking origin/master at <sha> · Design settled
below; if a fork appears, STOP and report.

GOAL: <one sentence: the observable end state, not the activity>

VERIFIED (coordinator, <when>; do not re-derive, but STOP if you observe otherwise):
- <fact> — <evidence: file:line / command + output / log path>

FILES (repo-relative):
Modify: <path> — <what changes, and what must NOT change in it>
Create: <path> — <purpose>
Read-only: <paths the worker may consult>
Generated (restore, never commit): plans/ast-*.json, docs/CODEBASE_MAP*.md,
  reports/run-tests-latest.json unless the step is ship's own evidence commit

STAGES (in order; each ends in a check; a failed check is a STOP):
1. <action> — <exact command> — expect: <observable> — on failure: STOP, report <what>
2. ...

CONSTRAINTS:
<the guard corpus, copied in full from the section below>
<task-specific constraints>

DONE WHEN:
1. <observable condition with the command that shows it>

VERIFY: <the exact commands whose raw output goes in the report>

REPORT: for each stage, the command, its exit status and the last 30 lines of output (or the
log path plus the key lines); `git status --short`; `git log --oneline -<n>`; every deviation
from this brief and why; for each problem, the verified cause, at least two options and a
recommendation. Never say "should work": say what you ran and what it printed.

Guard corpus (restate in every brief; measured in this repo, 2026-10-22)

Reading and editing code

• Python source is read through the AST toolkit only: .venv/bin/python scripts/serialize_codebase_ast.py source <qualified_name> --no-daemon (symbols --pattern X, refs X, who-imports M for structure). Read and grep on .py under src/, scripts/ and tests/ are blocked by hooks. Edit takes the exact bytes the toolkit printed. Non-Python files: any tool.
• The worktree has no direnv. Run repo commands through the env wrapper: bash <scratchpad>/envrc_exec.sh <cmd...>; ship through bash <scratchpad>/ship_envrc.sh [flags].
• Do not change the neo4j driver or its dependency pin (Mohamed, 2026-10-22).

Tests

• No mocks, doubles, skips, xdist, monkeypatch or os.environ mutation (RUL-001/002). Real processes and real fleets. A test that finds a bug: fix the code, never the assertion.
• More than one test file goes through scripts/run_tests.py (RUL-038), never bare pytest.
• Every test run is started with run_in_background: true (a hook blocks foreground runs) and observed: wait with Monitor (an until-loop on the log's summary line) or check tail of the log. Never sleep in the foreground. Never start a second heavy run beside one in flight.
• The test hooks match command TEXT: a foreground command that merely names run_tests.py or pytest (an ls, a grep) is refused. Name the log file, not the runner.
• Env-var names in tests come from the module's constant (T21), never a retyped literal; the test review also flags pre-existing literals in any file you touch.

Commits

• Author Mohamed. No Co-Authored-By, no AI attribution, no session links (RUL-007). This overrides any harness reminder about attribution lines.
• Stage files by name. Restore generated files first (git checkout -- plans/ast-*.json docs/CODEBASE_MAP.md docs/CODEBASE_MAP_FULL.md); the AST live-sync hook rewrites them.
• Real pre-commit; never git commit --no-verify and never ship.sh --no-verify.
• The secrets scanner (scripts/check_staged_secrets.py, run by pre-commit on the STAGED blobs) refuses any line-start assignment whose NAME is credential-shaped (SECRET, PASSWORD, CREDENTIAL, APIKEY, *_TOKEN, API_KEY/ROOT_KEY/... ) and whose value is not a placeholder. Test fixtures count: a planted fake credential needs a neutral local name (planted). Rename, never bypass. Check before committing: git add <files> && bash <scratchpad>/envrc_exec.sh python scripts/check_staged_secrets.py.
• The pre-commit hook rewrites reports/precommit-walls.ndjson on every attempt; restore it.
• The commit review's mypy step times out (30 s) on a cold cache: warm it first with bash <scratchpad>/envrc_exec.sh python -m mypy --no-error-summary <changed .py files>.
• Never bare git stash. A temporary WIP commit sets work aside.

Deploys

• No deploy-in-place. Deploy only through ship or the repo installers at a pinned --ref.
• Before any tools deploy, smoke-install the exact commit into a scratch prefix: PREFIX=<scratchpad>/tools-smoke bash <scratchpad>/envrc_exec.sh bash deploy/install-tools.sh --ref <sha> and require DEPLOYED <sha> -> <prefix> with no FAIL line. The deployed tools tree vendors src/orchestrata_ultimate/core with no pyproject above it (lesson 2026-10-22).
• If a deploy fails verification, roll back with the installer at the last good --ref, then STOP.
• Do not ship or touch dr-hannah; ignore Stop-hook messages about it.

Secrets and scope

• Never print, copy or commit .env contents or any credential.
• Change only the FILES. Any other dirty path at the end is a fence violation: report it.
• STOP and report, rather than guess, on: a design fork, an unexpected failure, a fleet down, a sha that moved, a guard you cannot satisfy without bypassing it.

Coordinator post-dispatch check

1. Fence: git status --short | grep '^??' equals the Create list; git diff --stat <base> equals the Modify list; nothing generated is committed.
2. Re-run the brief's VERIFY yourself and compare it with the reported output.
3. git log -<n> --format='%an %ae%n%B' shows Mohamed only, no attribution lines.
4. Log every brief defect and every agent error in plans/briefs/IMPROVEMENT-LOG.md, then fold each one back into this template in the same session.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks