Files
claude-config/AGENTS.md
T

10 KiB

Working here

Decisions live in docs/decisions.md:

  • larv-review: within a chunk lifting a project towards the comprehension floor, work on the project's lowest-scoring dimension comes first, and the floor doesn't block anything
  • loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ and larv-review's standards, and holds a chunk open while an answer the human typed in it is recorded nowhere; the worker's own account of which goal settles a choice decides nothing
  • loop-claude: one session per project, its id derived from the checkout's path relative to ~/code, or to / outside it
  • loop-claude: before it opens claude on the terminal, it marks the checkout and each of its worktrees trusted in ~/.claude.json
  • bin/: the tests rerun themselves on a uv-fetched Python at README Install's floor
  • bin/: the tools and their tests run on the host's Python, with no container
  • comprehension floor: every dimension and the overall at 7.0 or above is the target, and blocks no merge or release
  • loop-claude: each project's model lives in ~/.claude/loop-claude-models.json, which only loop-claude writes
  • review: a pass gets at most three rounds per chunk; instead of a fourth, the run asks the human
  • review: a reviewer or comprehension seat that rules the work below standard may ask to rerun once, one rung up, in the same round; the ruling that stands is an escalation trigger for the worker, never for the judge
  • review: a fix for a 🔴 or 🟡 reruns the pass that found it and each pass whose row in larv-review §3's re-entry table the fix meets; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟢, a ❓ or a prose finding reruns none
  • review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit where the architecture pass ran, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
  • review: a project decision may suspend the comprehension check for the plan items it names
  • review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
  • review: the principles audit runs on every chunk that changes code, config or tests, and on no other chunk
  • review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
  • loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
  • loop-claude: a claude that cannot start is a failed worker run, retried
  • review: an ask no user answers leaves the PR unmerged
  • loop-claude: every claude it starts bypasses permissions inside its sandbox
  • review: /security-review is the security pass of record, except where the full scan runs on the same change and replaces it
  • review: the premises chunk's whole review is the human's approval
  • workflow-bench/: the remote may show the bench cases' names and commit SHAs
  • settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
  • settings.json: each machine owns its model, and git's clean filter bin/settings_filter.py keeps it, and Claude Code's key order, out of every commit
  • the repo may name bender, bender-infra and ai-sandbox
  • todo.md: one table of items, scored by the formula it states, held to its bar and ranked by bin/rank_todo.py, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals; the table's order is the plan's only order
  • todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
  • reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to docs/reading-cost.md in the next chunk's PR
  • reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
  • reading cost and score-outcomes: each waits for 10 finished chunks before it shows a median
  • rule-hook: a PreToolUse hook enforces each rule a program can check, a # rule-override <rule>: <reason> marker overrides one, and larv-review's overrides pass rules on each override before merge
  • rules/: CLAUDE.md holds the worker's rules that no file path can scope, and each topic's rules for the worker live in a rules/ file that Claude Code loads by its paths: frontmatter
  • worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in skills/larv-review/standards/
  • tests: each test earns its keep as the technical principles' test bullet says, and the worker takes a test's expected values from its item, never from the code
  • review: each reviewer under agents/ writes its full report into the chunk's review folder under ~/.local/state/larv-review/ and returns the worker its verdict and one line per finding; rule-hook refuses its Edit and MultiEdit, and any Write outside ~/.local/state/larv-review/
  • review: stability and product-owner report only a defect, a broken requirement of the plan or the goals, a breach of a technical principle, or for stability a hard place the change touches; each architect finding names a later change the PR makes harder; prose runs only on a chunk that changes prose
  • review: the stability pass mutation-tests the lines a chunk changes, in place of measuring test coverage
  • routing: one ladder of (model, effort) rungs, ordered by the Artificial Analysis Intelligence Index with Fable 5.1 at max on top; a task's L picks its worker's rung and its E + I its reviewers', by fixed steps counted from the cheapest rung of the project's model
  • routing: a chunk's worker runs on the rung its item's L picks, below the project's rung too; its reviewers run on the highest of the worker's rung, the project's and the one picked by the highest E + I among the chunk's items, unless a replay lowered their pass; the seats and the security pass always on the project's
  • routing: the worker changes rung only as a chunk starts, after every second unfinished verdict, or when the judge reports a taken-in item that picks a higher rung or an escalation trigger the worker cites
  • routing: loop-claude measures review rounds and unfinished verdicts per rung every 20 cycles, and calls for a routing change when, of two rungs with 5 or more chunks each, the lower took more of either than the one above, or when 5 or more subagents of one type had reports longer than the tool results they read
  • routing: a worker delegates a task only where it needs just the task's conclusion, and each subagent runs on the rung its task's L picks from the project's rung, never below the project's rung when it files or scores todo.md items
  • routing: a worker hands a task one rung up on each escalation trigger, up to two rungs above the rung its item picks unless the human agrees, and opens the subagent's prompt with the trigger so the routing figures count it
  • routing: a worker whose run ends asking for a higher rung, citing an escalation trigger the judge finds in the transcript, steps one rung up as the judge interrupts or quotes an answer, or next cycle, up to two rungs above the rung its item picks
  • routing: on a model judge-replay covered, the judge runs on the rung a review would get from the highest E + I among its chunk's items, never below the project's rung
  • routing: a review pass runs below the project's rung only on a rung that a replay of its rounds shows finding every 🔴 and 🟡 the project's rung finds, and only where the E + I steps no review up and the worker runs no higher than the project's rung, then even below the worker's; no pass has such a rung

Working rules

  • routing-calls-raised.md sits at the root of loop-claude's archive ($LOOP_CLAUDE_TRANSCRIPTS, default ~/.claude/loop-claude-transcripts). Each of its lines is a call or a Reset, with a stamp. A call is new when it is stamped after the latest Reset and after the latest stamp that todo.md or docs/decisions.md → routing: cites. When there are new calls, file one todo.md item to settle them, or refresh the item already filed. Its detail quotes those calls with their stamps, and the routed-chunks table of routing-figures.md beside it, never the project names its other tables hold. A change to the ladder, its steps or the delegation rule is the human's. The chunk that settles the calls cites the latest stamp it settled in docs/decisions.md → routing:, whatever the human decided, so they are not filed again. Once a chunk that changes the ladder, its steps or the delegation rule has merged, append - <UTC time> Reset to routing-calls-raised.md: the figures then count only chunks finished after it, and its calls may be raised again.
  • When ~/.claude/settings.json has uncommitted changes, commit them on a branch of their own and merge them through a PR: Claude Code writes that file from any session. Read their diff first with git diff HEAD -- settings.json, which shows staged changes too: an empty one is a model pick, which git add settings.json clears. When it holds a credential, such as a token in env or mcpServers, ask the human to move it out of the file, and commit only once it is gone. A token in env moves to the shell profile; a server in mcpServers moves to ~/.claude.json with claude mcp add --scope user.

Scoring run

The project values for skills/comprehension-panel/seat-prompts.md:

  • {language}: Python
  • {kind}: a Claude Code configuration with an agent loop and review skills
  • {domain}: driving headless Claude Code sessions, agent review workflows
  • {domain docs}: the Claude Code documentation
  • {3am question}: a loop-claude run exits 1 overnight after the judge returned a verdict the loop rejected, or a larv-review run looped a reviewer a fourth time