Propose changes to a client's CLAUDE.md and AGENTS.md to its team, and ask the principles for files in folders before banners and for a findable entry point
CI / tests (pull_request) Successful in 2m17s

This commit is contained in:
2026-11-14 00:29:40 +01:00
parent 9508838439
commit 9b6303f561
5 changed files with 16 additions and 27 deletions
+2
View File
@@ -2,6 +2,8 @@
## Unreleased
- The technical principles ask for code in files and folders before `// --- name ---` banner comments, and for an entry point a newcomer finds at once, with only the README and the files a tool reads from the root beside it.
- In a client repo, the loop reads its team's own `CLAUDE.md` and `AGENTS.md`, proposes each change that aligns them with this setup in a pull request of its own, and records each conflict that stays as a decision in the project's decision record, following the team's rule unless that breaks a project goal.
- The new `project-record open <record>` prints the file in which an agent reads and edits one of a project's five records (`decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`), and `project-record save <record>` stores the edit. Every tool now reads and writes a record the same one way, so that a later release can keep a record outside files. No config needs a change.
- `loop-inbox` is gone. loop-claude now asks its questions only on its own terminal. A line typed there answers a question, and `/talk` opens the worker's session. The Mattermost DM still tells you a loop waits. To upgrade, quit any `loop-inbox` still open and remove your `~/.local/bin/loop-inbox` link. Once every loop started before the upgrade has reloaded or ended, remove the folder `~/.local/state/loop-claude/`, which nothing reads any more.
- rule-hook refuses a Read or a Grep of `~/.claude/.env` or of the `env-file` any project's config names, and a Bash command that names either or searches a folder holding either with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so that a worker doesn't put a credential in its transcript in passing. A command that hides the path, such as behind a glob or a variable, still goes through.
+1
View File
@@ -80,6 +80,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
When one fires, hand the hard part, edits included, to a subagent on the rung loop-claude's prompt names, one above yours. Open the subagent's prompt with the marker loop-claude's prompt gives, then the trigger's evidence. Each later subagent on that task runs on that rung or higher, and each further escalation trigger moves the task one rung higher, up to the highest rung loop-claude's prompt names. Ask the human before going higher. Where loop-claude's prompt names no escalation, as on the ladder's top rung or off it, keep the task in your own thread.
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. A reviewer under `~/.claude/agents/` writes only its report, under `~/.local/state/larv-review/`, and rule-hook refuses it every other Write, every Edit and every MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to a folder it makes under the chunk's review folder (`~/.claude/bin/larv-review review-folder` prints it), and removes no image or file it did not create.
- A client repo's own `CLAUDE.md` and `AGENTS.md` belong to its team. Read both before the first chunk. Propose each change that aligns them with this setup to the team as a pull request of its own, never inside a chunk's. A conflict the team leaves stands: follow the team's rule, unless that breaks one of the project's goals, and record which rule you follow and why as a decision in the project's decision record, so nobody is asked twice.
- Check `README.md` first for build, test, install, and codegen commands, and fix one that misbehaves in the same change. Refresh `README.md` whenever you change what it describes, keeping it true, not longer.
- Where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, a Kubernetes manifest or a `docker run` line, pin a container image to its full patch version and a GitHub Action to a semver tag.
+9
View File
@@ -1964,3 +1964,12 @@ Read most (opens and searches):
- `bin/repo_checks/test_import_order.py` 1
- `bin/rule_hook/rules.py` 1
- `docs/decisions.md` 1
## Reading cost, chunk f9ab213f23c1, finished 2026-11-13T23:28:47Z
86144 new input tokens before the first commit.
Read most (opens and searches):
- `todo.md` 2
- `CLAUDE.md` 1
+4
View File
@@ -79,7 +79,11 @@
- Things a reader finds by name may run far past seven: 100 files named by locale, the cases of an enum, a reference list. A predictable name and a sorted order serve them better than a group would.
- Each added level makes a reader open one more folder, file or function to find a thing, so a split must save more than it costs. Keep eight, nine or ten things in one level when splitting them would add more names, files or jumps than it removes. Say why where the level is declared: a comment, the folder's README.
- Group by what a reader would name: a feature, a step, what changes together. BANNED: `misc/`, `part2()` or a parameter object that exists only to bring a count down. GOOD: `invoices/`, `payments/`, `reports/`, each holding what changes together; `locales/` holding `de.json` to `zh.json`, flat.
- Group code into files, and files into folders. A banner comment (`// --- name ---`) that groups a file's sections is the last resort, kept only where the language or the build cannot split the file, and the file says which limit holds it.
- Crossing a limit asks for one of two answers, never a split at any cost: group the things, or record why they stay. Keep a limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
* Make the entry point the first thing a newcomer finds.
- The root holds the entry point, the README and the files a tool reads only from there, such as the manifest, the lockfile and the licence. Source, tests and tooling live in folders named by what they hold.
- The entry point carries the name its ecosystem expects, such as `index.ts` in an npm package, with no other source file beside it.
* Keep It Simple, Stupid (KISS): keep solutions simple, so a reader new to the project understands each part on one read.
* Don't Repeat Yourself (DRY) is a guide, not an absolute rule. It aims at one authoritative home per piece of knowledge, one obvious way per need. Before applying it, ask whether the code would be easier to understand, easier to reason about, or easier to maintain if DRY were broken; if so, break it, so long as the spellings cannot disagree (below). A surface people write — a template, data, an API — may accept a second spelling where that makes it easier to use.
- A value, rule, definition or concept lives in one place, and everywhere else derives it from there or points at it. A copy that can drift is a second spelling: derive it from its owner, or, for config a human writes, reject it where it is read and name the owner.
-27
View File
@@ -12,8 +12,6 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 364 | 0.11.0 | | | **Read a client repo's own `CLAUDE.md` and `AGENTS.md`, propose to its team each change that aligns them with this setup, and record each conflict left as a decision in the project's records.** | 2 | 2 | 2 | 4 | 2 | 1.6 by 4, 1.2 by 2 | 2.2 |
| 376 | 0.11.0 | | owner | **Make `principles/technical-principles.md` ask for files in folders before comment banners, and for an entry point a newcomer finds at once.** | 1 | 2 | 2 | 3 | 2 | 1.1 by 4 | 1.6 |
| 360 | 0.11.0 | | | **Make `chunk-pr merge` wait for the human approvals a project's config requires, as part of the gate, before it merges.** | 2 | 2 | 3 | 5 | 3 | 1.6 by 5 | 1.6 |
| 357 | 0.11.0 | | | **Write prose in the language a project's config names, and title its commits, pull requests and branches by the templates it names.** | 3 | 2 | 3 | 6 | 4 | 1.6 by 5 | 1.4 |
| 350 | 0.11.0 | | | **Route every read and write of the plan, by tools and by agents, through one plan-store interface and `todo-item`, with the markdown file as one backend.** | 4 | 2 | 3 | 7 | 7 | 1.6 by 4, code health by 2 | 1.1 |
@@ -89,31 +87,6 @@
## Details
### 364. Read a client repo's own `CLAUDE.md` and `AGENTS.md`, propose to its team each change that aligns them with this setup, and record each conflict left as a decision in the project's records.
lilleman's call, 2026-11-12: the loop may change every file in a client repo, but in agreement with the team, so a change to their instruction files goes to them as a proposal in a pull request. Where a conflict stays, the loop records which rule it follows and why as a decision in the project's decision record, so it is never asked twice. This is a working rule in `CLAUDE.md`.
### 376. Make `principles/technical-principles.md` ask for files in folders before comment banners, and for an entry point a newcomer finds at once.
On 2026-11-13 the maintainer asked for both, after `@larvit/log` grew one 2,462-line `index.ts`
of 16 `// --- name ---` sections that no review asked to split until its 2.5.0 release review.
"About seven things per level" counts a file's sections but lets banners serve as the grouping.
Draft wording, under "About seven things per level":
- Group code into files, and files into folders. A banner comment grouping a file's sections is
the last resort, kept only where the language or the build cannot split the file, and the file
says which limit holds it.
Draft wording, as a principle of its own:
* Make the entry point the first thing a newcomer finds.
- The root holds the entry point, the README and the files a tool reads only from there, such as
the manifest, the lockfile and the licence. Source, tests and tooling live in folders named by
what they hold.
- The entry point carries the name its ecosystem expects, such as `index.ts` in an npm package,
with no other source file beside it.
### 360. Make `chunk-pr merge` wait for the human approvals a project's config requires, as part of the gate, before it merges.
lilleman's call, 2026-11-12: this client requires another human's approval on every pull request, so the gate covers it, and the loop still merges once the gate passes. Until this ships, lilleman merges such pull requests by hand and restarts the loop. On GitHub, read the approvals the branch protection asks for; this client's forge is GitHub.