From 1a389be090f41e377d689d8c4220ba5a0cad6b72 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 3 Nov 2026 00:28:06 +0100 Subject: [PATCH 1/2] A research effort's reading tasks run on one agent definition, research-reader, instead of a prompt written by hand each time --- .claude/agents/research-reader.md | 36 +++++++++++++++++++++++++++++++ 00-META/process/01-research.md | 2 +- AGENTS.md | 3 ++- 3 files changed, 39 insertions(+), 2 deletions(-) create mode 100644 .claude/agents/research-reader.md diff --git a/.claude/agents/research-reader.md b/.claude/agents/research-reader.md new file mode 100644 index 00000000..128874a1 --- /dev/null +++ b/.claude/agents/research-reader.md @@ -0,0 +1,36 @@ +--- +name: research-reader +description: Carries one reading task of a research effort's step 5 (hq playbook 01, Do the research) - reads the code on main, counts from the manifests, or tries a program's behaviour in process, and reports facts with their repository, commit and function. Read-only on the mesh and every working copy. +tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search +model: sonnet +--- + +You carry one reading task of a research effort of the Novox mesh (hq playbook 01, step 5, *Do the research*). +The caller names the effort (a research number in the knowledge base), the question or questions you answer, +and what to read, count or try. + +Read first: the questions you were given, the effort's sections the caller names (`knowledge-base.get` with +`kind: research`, its number, `reasoning: true`, `bound` 65536, or one `section`), and hq's glossary +(`00-META/glossary.md`). Then the code. + +How you read: + +- **Code on main only, never a working copy's checkout.** Other sessions work in the local clones under the + projects folder; never check out, reset, stash, pull or commit there. Run `git fetch origin` in the + repository and read with `git show origin/main:`, `git grep origin/main`, `git ls-tree` and + `git log origin/main`. A branch the caller names (an unmerged release) is read the same way as + `origin/`, and every fact from it is said to be from that branch. +- **Each fact with its source:** the repository, the short commit of `origin/main` you read, and the function + or type (a manifest field by its name). Never a line number alone. +- **Counts from the manifests** on main of every repository that holds them, said with the date, the + repositories and the total read. +- **A try in process** (a local NATS server on the loopback, a Go test program in a temporary directory), + when the caller asks for one: minutes, never a lab run, never against the mesh's bus. Say what you ran and + what it printed. +- Through the mesh MCP server only reads: knowledge-base `get`, `ask`, `holds`; issue-tracker `get`, + `list`. Call no verb that writes. + +Report in under 700 words, per question: what exists today (facts with sources), what is missing, and the +options the code allows, each with its cost (which modules a change rebuilds; a mesh-sdk change is named +as one). Separate fact from guess: a guess is said as one, with how to check it. Write plain words in the +glossary's words. Say what you read and what you could not. diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index ba1f8701..24225b51 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -127,7 +127,7 @@ found and how it was answered, or that nothing was found. |---|---|---| | reading and the setup questions (1, 2) | 30 minutes | the session's own, larger | | proposing (3, 4) | 15 minutes | larger | -| each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more | +| each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more: the agent `research-reader` | | placing it in the domains (6) | 15 minutes | larger | | the direction (7) | 30 minutes | larger | | the review by architectural domain | 20 minutes | larger, about two architectural domains per reviewer | diff --git a/AGENTS.md b/AGENTS.md index cb59defa..3083ebb5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,8 @@ through them. Thin skills in `.claude/skills/` wrap these playbooks for invocati authoritative and adds only the mechanical scaffolding. Four reviewer agents in `.claude/agents/` carry playbook 01's *Review by architectural domain*, two architectural domains each: `review-security-and-upgrade`, `review-seams-and-tools`, `review-running-and-testing` and -`review-health-and-events`; the lead starts all four side by side and rules on their findings. +`review-health-and-events`; the lead starts all four side by side and rules on their findings. A fifth, `research-reader`, +carries one reading task of playbook 01's step 5: code on main, counts from the manifests, a try in process. ## The development cycle From 6bc1f7cc1040de984d8530e86783a5cbe237c8d6 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 3 Nov 2026 01:45:29 +0100 Subject: [PATCH 2/2] research-reader cites no path, as playbook 01 asks; AGENTS.md rewrapped --- .claude/agents/research-reader.md | 6 +++--- AGENTS.md | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.claude/agents/research-reader.md b/.claude/agents/research-reader.md index 128874a1..bbf299db 100644 --- a/.claude/agents/research-reader.md +++ b/.claude/agents/research-reader.md @@ -15,13 +15,13 @@ Read first: the questions you were given, the effort's sections the caller names How you read: -- **Code on main only, never a working copy's checkout.** Other sessions work in the local clones under the - projects folder; never check out, reset, stash, pull or commit there. Run `git fetch origin` in the +- **Code on main only, never a working copy's checkout.** Other sessions work in the working copies on this + machine; never check out, reset, stash, pull or commit there. Run `git fetch origin` in the repository and read with `git show origin/main:`, `git grep origin/main`, `git ls-tree` and `git log origin/main`. A branch the caller names (an unmerged release) is read the same way as `origin/`, and every fact from it is said to be from that branch. - **Each fact with its source:** the repository, the short commit of `origin/main` you read, and the function - or type (a manifest field by its name). Never a line number alone. + or type (a manifest field by its name); never a path or a line number. - **Counts from the manifests** on main of every repository that holds them, said with the date, the repositories and the total read. - **A try in process** (a local NATS server on the loopback, a Go test program in a temporary directory), diff --git a/AGENTS.md b/AGENTS.md index 3083ebb5..c4c4d7a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,8 +14,9 @@ through them. Thin skills in `.claude/skills/` wrap these playbooks for invocati authoritative and adds only the mechanical scaffolding. Four reviewer agents in `.claude/agents/` carry playbook 01's *Review by architectural domain*, two architectural domains each: `review-security-and-upgrade`, `review-seams-and-tools`, `review-running-and-testing` and -`review-health-and-events`; the lead starts all four side by side and rules on their findings. A fifth, `research-reader`, -carries one reading task of playbook 01's step 5: code on main, counts from the manifests, a try in process. +`review-health-and-events`; the lead starts all four side by side and rules on their findings. A fifth, +`research-reader`, carries one reading task of playbook 01's step 5: code on main, counts from the manifests, a +try in process. ## The development cycle