Put the ready note and the brief a fixing agent follows into playbook 07
mesh/merge-gate head ddf23a786101 merged into trunk f3bbfd4bf628 — pass: the change touches no module of the mesh's graph
mesh/repo-check head ddf23a786101 merged into trunk f3bbfd4bf628 — pass: its merge-check.sh passed
mesh/delivery delivered

They lived in a file on one machine that only one session's agents read. They are how every feature's
agents work, so they belong with the method; a feature keeps only its local facts (paths, branch, locks).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-15 12:33:00 +00:00
co-authored by Claude Opus 5.5
parent f3bbfd4bf6
commit ddf23a7861
+62
View File
@@ -136,6 +136,68 @@ reviews and delivers at the end. The agents never push.
session's share). Times are local and absolute.
- **When this playbook meets a problem,** the lesson is added here, so the next feature avoids it.
## The ready note
The form of what "The lead decides, a fixing agent builds" (above) asks the issue to say: a note on the issue
headed exactly "Ready to build". If any line cannot be filled in, the issue is not ready.
```
Ready to build (<lead>, <time>).
Repository: <one repository; split the issue if it needs more, or name the landing order>.
Files: <path:function or path, each>.
Decisions it builds with: <quoted, one line each, with where each was decided>.
First test: <name and what it asserts; it fails today because …>.
Done when: <one sentence>.
Do not touch: <files, behaviour, other issues' areas>; landing beside it: <issues>.
Stop if: <the assumption the note rests on>.
```
When the reading is large, a read-only agent on the smaller model reads the code and answers the lead's
exact questions with file:line; the lead writes the note from its answers. The agent's prompt is then one
paragraph: "Fix issue N of feature <name>. Follow playbook 07's agent brief; build exactly what the
issue's ready note says." plus the feature's few local facts (below).
## The brief a fixing agent follows
**Name your issue everywhere.** Begin every step, to-do item and message with the issue: "issue 805:
landing in mesh-catalog", never "landing". The operator follows several agents at once.
**Stop rule, the most important** ("The lead decides, a fixing agent builds", above): a decision the note
does not give includes a new field, a new rule or a choice between two ways. Stop before writing code and
report what and where (file:line). A stop costs minutes; building the wrong thing costs a review and a
rebuild.
**Read the issue first,** its ready note first of all; read other notes, a design or a decision record only
where the note points to them.
**Hard rules.** Reach the mesh only through the mesh MCP server; never ssh, never run `nox`. Never push,
never open, merge or close a pull request: the lead does. Never write to a store's database by hand; a schema change
is a numbered migration and the consolidated schema. Go only, unless the note says otherwise. Never move another issue; never edit files
the mesh manages on a machine. Use the glossary's words; the unit of work is an issue.
**Steps.**
1. Move the issue to `fixing` with `by` `<feature>-<issue>@<node>`. If it is refused, stop and report.
2. Make your own worktree on a local branch `<feature>-<issue>` from the feature branch's head.
3. Write the note's first test and see it fail. Make the change and see it pass; keep every other test
passing.
4. Commit: concise, imperative, about why, naming the issue.
5. Merge the feature branch's head into yours. In a conflict keep both sides' behaviour and every test,
then build again.
6. Run the repository's checks in your worktree (`gofmt -l`, `go vet ./...`, `go test ./...`,
`merge-check.sh`; where a test needs the store, a throwaway database server under the feature's
scratchpad, stopped when done). Read the result. If anything is red, do not land.
After every merge of the feature head, check again before landing.
7. In a separate step, land by fast-forward under the feature worktree's lock. If it is not a
fast-forward, go back to step 5.
8. Note the issue: the commits and how its done-when is proven. Leave it in `fixing`.
**Report back,** in under 150 words: commits per repository, the tests added and that they failed first, the check
results, and anything you stopped on or found that a later issue must know.
**The feature's local facts** (the lead gives them in the prompt or a short local file): the scratchpad and
its worktrees, the feature branch's name, the lock files, and anything particular to the feature's
repositories (a check that needs a gate built from another worktree, a test that is red at certain times).
## What this is not
- **Not a licence to batch unbounded work.** A feature is a *bounded* unit; if it sprawls for