Orchestrata Ultimate / Briefs / Templates

Brief templates

Four templates exist. Two are worker briefs for different dispatch routes, one is the five-line skeleton the hook prints when it rejects a brief, and one is a commit-message template. The text of each follows, quoted in full, with an explanation of every field. Quotes are in four-backtick fences because the templates contain three-backtick fences.

1. Sonnet agent brief

The current text is the working copy from the 2026-10-22 session; the committed file in plans/briefs/ is one revision behind. The quote below is the working copy, the difference follows it. One line of the guard corpus that named a retired service was reworded in this quote.

# 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).
- `FILES:` is literal (no qualifier between the word and the colon) and must name at least one
  `.py` path, even for read-only or ops work; a hook attaches those files' AST to the dispatch.
- A prod deploy is never delegated: Claude Code's auto-mode classifier denies it to a subagent.
  The brief ends before it; the coordinator runs it after the user approves in their own words.
- Any deploy brief: read the dry run in full and diff the lock between the deployed and the
  new commit. A removed package that runtime code imports is a STOP until rehearsed.

---

## 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.
- [ ] Nothing a VERIFIED number depends on changed between measuring it and dispatching,
      generated files included (`plans/ast-ultimate.json` feeds every `--affected` run).
      Re-measure after any cleanup.
- [ ] 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). This is Mohamed's mandate
  (zero hand-reading of Python, 2026-08-02), not just a hook: hold it even where Read or grep
  happens to work. 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 a live-data refresher; 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. Expected extras: the pre-commit
   hook stages `reports/precommit-walls.ndjson` into every commit, and ship commits
   `reports/run-tests-latest.json` and `reports/.ship-verified`.
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.

Difference from the committed file, as a unified diff (committed to working copy):

--- committed (d9bcbb7cc)
+++ working copy
@@ -13,2 +13,8 @@
 - Pass `model: "sonnet"` explicitly on the Agent call (`docs/supervisor-workflow.md` §E).
+- `FILES:` is literal (no qualifier between the word and the colon) and must name at least one
+  `.py` path, even for read-only or ops work; a hook attaches those files' AST to the dispatch.
+- A prod deploy is never delegated: Claude Code's auto-mode classifier denies it to a subagent.
+  The brief ends before it; the coordinator runs it after the user approves in their own words.
+- Any deploy brief: read the dry run in full and diff the lock between the deployed and the
+  new commit. A removed package that runtime code imports is a STOP until rehearsed.
 
@@ -25,2 +31,5 @@
 - [ ] Every fleet the work touches was probed up this session.
+- [ ] Nothing a VERIFIED number depends on changed between measuring it and dispatching,
+      generated files included (`plans/ast-ultimate.json` feeds every `--affected` run).
+      Re-measure after any cleanup.
 - [ ] A commit packet: the coordinator staged its files and ran the staged-content scanners
@@ -83,5 +92,5 @@
   `.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.
+  (`symbols --pattern X`, `refs X`, `who-imports M` for structure). This is Mohamed's mandate
+  (zero hand-reading of Python, 2026-08-02), not just a hook: hold it even where Read or grep
+  happens to work. 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:
@@ -139,3 +148,5 @@
 1. Fence: `git status --short | grep '^??'` equals the Create list; `git diff --stat <base>`
-   equals the Modify list; nothing generated is committed.
+   equals the Modify list; nothing generated is committed. Expected extras: the pre-commit
+   hook stages `reports/precommit-walls.ndjson` into every commit, and ship commits
+   `reports/run-tests-latest.json` and `reports/.ship-verified`.
 2. Re-run the brief's VERIFY yourself and compare it with the reported output.

Fields explained

2. Dispatch brief

Used for file-based dispatch to a qwen, deepseek or sonnet run, where the orchestrator commits only the listed files and runs the listed checks itself. It uses ## headings rather than GOAL: labels, so the Agent-tool hook would deny it as written; it belongs to the dispatch pipeline, not to the Agent route.

# <TITLE> — brief for one <qwen|deepseek|sonnet> run (<ADR / step id>)

## Goal
<One sentence: the observable outcome, not the activity.>

## Ruling / context (only what the worker cannot derive)
<Architect decisions already made, and why. Routes that are CLOSED and must not be retried.>

## Inputs (exist; read nothing else)
- <absolute or repo-relative path> — <what it holds, which part matters>

## Code map (the orchestrator generates it; required when the work edits a large Python file)
Output of `python3.14t -I packages/design-scripts/dispatch/code_map.py <file> '<regex of the relevant names>'`:
`start-end kind name` lines for the functions and module variables the change touches. Read a span with
`code_map.py <file> --source <name>` (exact bytes via ast, under a second). Never run
`serialize_codebase_ast.py symbols --source` over `lift-poc`: about 2 minutes per call, measured 2026-10-17.

## Work
1. <Step, with the exact file to edit and the exact command to run>

## Verify (deterministic, no tests)
- <command> -> <expected exact output / exit code / count>
- <a negative check: a mutant or bad input that must still FAIL>

## Rules
- Edit only: <files>. Create only: <files>.
- No commit, no `git add` (the orchestrator commits). No tests. No subagents.
- <task-specific guard>

## Files
The orchestrator commits only the paths listed here (one repo-relative path or glob per line, fnmatch):

```files
packages/design-scripts/dispatch/dispatch.py
packages/design-scripts/dispatch/*.json
```

## Checks
The orchestrator runs each line as a machine check after the run reports DONE
(`<expect> :: <shell command>`, where `<expect>` is `rc=N`, `out~REGEX`, or `out=TEXT`):

```checks
rc=0 :: python -m py_compile packages/design-scripts/dispatch/dispatch.py
out~^\[\]$ :: cat packages/design-scripts/dispatch/queue.json
out=[] :: cat packages/design-scripts/dispatch/queue.json
```

## Environment
Compulsory (ADR-0148): the only source of the environment the worker and every check run under; a brief
without it is refused. Never strip variables in a check (`env -u`, `direnv exec` are refused):

```env
venv: .venv
files: env/test.env env/toolchain.env env/ast-roots.env
set: UV_NO_EDITABLE=1
secrets: none
import: orchestrata_ultimate
```

## Done
Reply with exactly: <the fields the orchestrator will re-verify>.

Fields explained

3. Hook skeleton

The five-line structure task_context_hook.py prints in its denial message when any of the labels is missing. The check is a case-insensitive substring test for each label, so a label with a qualifier between the word and the colon, such as FILES (read-only):, does not count.

GOAL: <one sentence: the outcome, not the activity>
FILES: <exact paths this task may touch — at least one .py for a coding task>
CONSTRAINTS: <what must NOT change; MVP scope; no mid-flight additions>
DONE WHEN: <the observable condition, with numbers where numbers exist>
VERIFY: <the exact command that proves it, e.g. `pytest-live tests/unit/test_x.py -q`>

4. Commit brief

A commit-message template. It is a brief in the sense that it states what the commit adds for a reviewer, not a prompt for a worker. Subject line names the directory and the change; the body says who ruled and what each file does.

plans/briefs: the Sonnet-agent brief template and its improvement log

Mohamed, 2026-10-22: execution goes to Sonnet agents, with the coordinator
checking each brief for accuracy and completeness, and with a brief
template and an improvement plan.

TEMPLATE-sonnet-agent.md: the dispatch hook requirements (the five labels,
the DESIGN_WAIVER line, an explicit model), a pre-dispatch accuracy and
completeness check, the skeleton, the guard corpus every brief restates
(AST toolkit only, the env wrappers, observed background test runs,
authorship, generated files, the secrets and mypy hooks, smoke install
before any tools deploy), and the post-dispatch fence check.

IMPROVEMENT-LOG.md: the loop (classify each defect, fold it back into the
template the same session, mechanize on the second sighting toward
brief_lint.py, M2), the measures, the dispatch ledger and a defect log
seeded with this session's eight coordinator mistakes and their fold-backs.

Also found, not quoted

• plans/briefs/IMPROVEMENT-LOG.md: the defect log and loop that feed changes back into template 1; a log, not a template.
• rtm/scripts/orchestrator/templates/*.j2 and audit_template.md: prompt templates of the older RTM orchestrator scripts; a different system, not measured further here.

Related

• Briefs
• Writing a brief
• task_context_hook
• Gates
• Workflow