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>
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user