From ddf23a786101cecd1ec54464ebf45093f8aa2cc5 Mon Sep 17 00:00:00 2001
From: mesh-tools <mesh-tools@noreply.localhost>
Date: Thu, 15 Oct 2026 12:33:00 +0000
Subject: [PATCH] Put the ready note and the brief a fixing agent follows into
 playbook 07

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>
---
 00-META/process/07-feature-branches.md | 62 ++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md
index c6ae80df..0eab18d5 100644
--- a/00-META/process/07-feature-branches.md
+++ b/00-META/process/07-feature-branches.md
@@ -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