From afe83b9124c4b55f6fefcda451dcbd7ed97b8062 Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 19 Oct 2026 13:27:55 +0200 Subject: [PATCH 1/2] Keep the drawn overview of the playbooks in hq, for a later docs site --- 00-META/README.md | 2 +- 00-META/process/00-overview.md | 3 + 00-META/process/playbooks.html | 517 +++++++++++++++++++++++++++++++++ AGENTS.md | 4 +- README.md | 2 +- 5 files changed, 525 insertions(+), 3 deletions(-) create mode 100644 00-META/process/playbooks.html diff --git a/00-META/README.md b/00-META/README.md index 386cb6b7..ce2a6d81 100644 --- a/00-META/README.md +++ b/00-META/README.md @@ -15,7 +15,7 @@ works — plus the engineering practice that holds across everything Novox build ## Rules -- Markdown only. +- Markdown only, but for the checks and one drawn overview of the playbooks (`process/playbooks.html`). - **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration. The one exception is `how-we-build.md`, which changes whenever a rule is earned — and only through its amendment process. diff --git a/00-META/process/00-overview.md b/00-META/process/00-overview.md index 96b95b0a..aa1e2c9f 100644 --- a/00-META/process/00-overview.md +++ b/00-META/process/00-overview.md @@ -48,6 +48,9 @@ the expensive half. ## The playbooks +A drawn overview of them, the cycle, a feature's steps, the review loop and an issue's life, is +[`playbooks.html`](playbooks.html): a picture of these playbooks, never their authority. + | # | Playbook | Trigger | |---|---|---| | [01](01-research.md) | Research | An idea from the operator, or one worth investigating before committing to design: setup questions, findings, a direction the operator confirms | diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html new file mode 100644 index 00000000..23a4a67f --- /dev/null +++ b/00-META/process/playbooks.html @@ -0,0 +1,517 @@ + + + + + +Novox Playbooks + + + +
+ +

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.

+
+
+ +
Drawn from hq main f269e83 on 2026-10-19 and kept in hq beside the playbooks. The playbooks are the authority; this page is a picture of them, and a change to a playbook's steps updates it in the same pull request.
+
+ + + + diff --git a/AGENTS.md b/AGENTS.md index ac34ff50..a6fe9ddb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,7 +55,9 @@ in running prose; a quotation keeps its words. ## Ground rules - **Markdown only** — but for the checks in `00-META/checks/` and `merge-check.sh` at the root, which - runs them on every pull request as its `mesh/repo-check` (ADR 0238). + runs them on every pull request as its `mesh/repo-check` (ADR 0238), and + `00-META/process/playbooks.html`, a drawn overview of the playbooks kept for a later docs site (the operator, + 2026-10-19); a change to a playbook's steps updates it in the same pull request. No new top-level folders without explicit confirmation. - **Status lives in YAML frontmatter** — on design docs (`layer`, `status`, `code`, `updated`, and `decisions` as "ADR NNNN"). A decision record's and a research effort's status live in the knowledge diff --git a/README.md b/README.md index 2279074b..8b968070 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Implementation lives in the code repositories — see ## Rules -- Markdown only. +- Markdown only, but for the checks and one drawn overview of the playbooks (`00-META/process/playbooks.html`). - No new top-level folders without explicit confirmation. - Knowledge flows `GENESIS → RESEARCH → DESIGN`. Research graduates into design only after analysis against GENESIS confirms alignment, and only through a recorded decision. From 5816ca669f2057547a5c38161bddfa4dfc9cff4e Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 19 Oct 2026 13:29:22 +0200 Subject: [PATCH 2/2] Say the page's freshness is not yet checked (issue 1222), and fix 08's leftover 'reviewed after its push' (review round 1) --- 00-META/process/08-small-fixes.md | 2 +- 00-META/process/playbooks.html | 4 ++-- AGENTS.md | 3 ++- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 35022704..a301281e 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -99,7 +99,7 @@ reading itself and uses one subagent only for the review. ## How it is checked - A small fix has one pull request with one or few commits naming its issue, opened after its review: a pull - request with many heads is a fix reviewed after its push. + request with many heads is a fix reviewed after its pull request was opened. - Its issue moves to `resolved` within the hour its delivery plan ends. - A pull request with no review record at its head (the Approve's ask says so first), a fix to a module's running pushed with no integration test of the module whole, or a review report diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index 23a4a67f..c2c8494a 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -409,7 +409,7 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
-
Drawn from hq main f269e83 on 2026-10-19 and kept in hq beside the playbooks. The playbooks are the authority; this page is a picture of them, and a change to a playbook's steps updates it in the same pull request.
+
Drawn from hq main f269e83 on 2026-10-19 and kept in hq beside the playbooks. The playbooks are the authority; this page is a picture of them, and a change to a playbook's steps updates it in the same pull request (not yet checked: issue 1222).