Novox Playbooks

How work is done on the mesh, from an idea or a symptom to a delivered change. Drawn from hq's 00-META/process/ at main f269e83, 2026-10-19, including playbook change hq #433 (try before the review).

The development cycle

Work enters as an idea or a symptom. An idea becomes a decision, a design and then milestones; a symptom becomes an issue. Both end as code delivered to the machines, and the as-is design is updated. No design without a decision; no development without a design or an issue that sends it.

Idea Symptom 01 Research questions, findings, direction confirmed 02 Graduation decisions in the knowledge base · to-be 04 Breakdown milestones by release, issues per repository 07 Feature one milestone = one release 03 Issues opened in the tracker, diagnosed, located 08 Small fix one issue, one repository, about an hour Delivered Approve, merge, delivery plan As-is updated 02 "when it ships": to-be → implemented 05 Constitution sync how-we-build → derived page 06 Writing a module what runs today → a module 09 Cleanup branches, worktrees, on the word a fix of about an hour a design gap: decision first larger than an hour: a feature
from an idea from a symptom decisions and designs code changes the mesh delivers alongside

A feature, step by step (playbook 07)

One milestone is one release: one branch name in every repository it touches, one worktree per repository, one fixing agent per repository kept for the whole milestone, one reviewer, and one pull request per repository, opened once. Since hq #433 the branches are tried before the review, so the reviewer reads real integration results.

0 · Prepare 15 min 1 · Develop + try 30 min per issue · one try 2 · Review ≤ 3 rounds · 15 min 3 · Check ≤ 1 more try · 1 check 4 · Deliver its delivery plan Leadlarger model Fixing agentssmaller model Reviewerlarger model The meshtry, checks, plan OperatorTelegram Survey · criteria context file per repo Up to trunk · push each branch Push reviewed heads open the PRs together Follow to done resolve the issues Build each issue, commit unit suite before every commit Fix findings the same agents Read all repos + tries · every criterion try integration tests run Forge checks gate · repo · group Merge · delivery plan backups first, tier by tier Approve once, for the group results round n+1 approved

Step 0 · what the lead writes before any agent starts

  • Every open question settled: on the issue, in the knowledge base, or by the operator.
  • Into each issue: every file and test it touches (file:line), how it is checked and delivered, a group's merge order.
  • newEvery other reader and writer of each value the change touches, each with a criterion.
  • Acceptance criteria: given / when / then, each naming its test level.
  • Release orders hidden in the milestone, said to the operator, never built around.
  • Fixtures copied from what the other side really writes, never from memory.
  • An issue sized over an hour is split before work starts.

Step 1 · the fixing agent's brief

  • One commit per issue, naming it; tests cite their criterion (// 1217/AC3).
  • newA test fails first on what the code does. A compile error is no failure: take out the change's effect and see an assertion fail.
  • The whole unit suite before every commit; each test well under a second.
  • Integration tests are compiled only: never run on the machine.
  • Never push, open or merge; never move an issue; never ssh.
  • Code that differs from the context file: stop and report, file:line.

When tests run

Two levels. Unit tests run all the time on the machine; integration tests (a bus, a store or a process started) never run there: mesh-controller.try runs them on the pushed branch, and the forge's merge check runs them again as the gate.

developend of step 1reviewstep 3merge Uniton the machine whole suite before every commiteach test under a second Integrationnever on the machine compiled only: go vet -tags integration try try again if changed merge check

The review loop

Round n of ≤ 3code + tries + criteria Wrong? ApproveReviewed-by line Same fixing agents fixanswer per finding issue-tracker.openanything beyond the issue After round 3: the operatorwhat is left, with a recommendation no yes n+1 hardening,a nicer form

What a round may ask

Only what makes the change wrong against its issues, their acceptance criteria and its decisions. Anything more (hardening, a further case, a nicer form) becomes a new issue, and the round does not wait for it.

What every round reads

  • Every criterion against its test: a test at its level that would fail without the change.
  • Every new integration test traced through the code, and its try's result.
  • That each integration test enters by the path the live trigger takes.
Why reviews took more than one round (R3b, 2026-10-19): a test that "failed" only by not compiling, a reader of the changed record the survey missed, and bus tests judged by reasoning before they ran. hq #433 changes all three.

An issue's life (playbook 03)

The issue tracker (seat issue-tracker) holds every issue's number, status, owner, fix and links. Its move refuses a wrong move at the write.

open diagnosing located fixing resolved wontfix by located-in by fixed-by, delivered,proven · core: replay straight to fixing, with by reason stopping: back to open, with a note of branch, last commit and what is left
A worker idle for a day may be taken over without a reason; otherwise take-over with a reason. An issue about a condition is linked to it, so the alert names the issue.

Where things live

WhatLives inWritten withNever
Decisions (ADRs) and research effortsthe knowledge base (seat knowledge-base)reserve, then propose the record wholea file in hq
Issues: status, owner, fix, linksthe issue trackeropen, move, note, linka status key in a report
An issue's narrative (design or governance only)hq 04-ISSUES/NNN-…/a pull requestits status
Designs, as-is and to-behq 03-DESIGN/, status in frontmattera pull requestthe two layers mixed
Playbooks, glossary, how-we-buildhq 00-META/a pull requesta copy in a session's memory
The rules every session keepsinstruction sections (module claude-code)claude_code_instructions_propose, the operator's Approvea hand-edited file

All playbooks

Open a card for its steps, what it produces and how it is checked.