9.2 KiB
9.2 KiB
Working here
Project principles
Each project principle states one rule that the decisions in docs/decisions.md apply; the entries there hold the specifics and the evidence. The numbers name the principles, and don't rank them.
- Cut cost only where a measurement of archived chunks shows quality holds. Chunk bundling, the round cap, which fixes rerun a pass, a reviewer of its own for each pass, the review a branch changing only Markdown no agent follows gets, the passes kept for the release review, review opt-outs, the security pass, compaction and the routing ladder all apply it.
- A measurement files or ranks work, and never blocks a merge. The comprehension floor and check, and a reading-cost rise, apply it. A merge waits on a scoring run the plan calls for only until the run is recorded, whatever it scores.
- Each file has one writer.
~/.claude/loop-claude-models.jsonis loop-claude's,~/.claude.jsonis Claude Code's, and~/.claudemoves only throughdeploy-release. The exception is~/.claude/settings.json, which Claude Code writes from any session. Git's clean filterbin/settings_filter.pykeeps each machine's model and Claude Code's key order out of every commit, and the working rule on~/.claude/settings.jsonbelow carries its other changes into this repo. - A rule a program can check is enforced by a program, and reviewers rule on the rest. rule-hook and its overrides,
docker-run-memory, the refused writes of reviewers underagents/, and CI withmain's branch protection apply it. - A chunk can't vouch for itself. What a chunk writes is approved by a review pass, by the human, or by a precedent the repo held before the chunk began. So an unanswered ask leaves the PR unmerged, the human approves the premises chunk and runs
deploy-release --cut, and the judge holds a chunk open while an answer the human typed isn't recorded anywhere. - An unattended run never waits on a prompt, and a lasting failure stops it. Every claude loop-claude starts bypasses permissions inside its sandbox, each claude it or loop-inbox opens on a terminal has
CLAUDE_CODE_SANDBOXEDset, and interactive sessions run in auto mode with the dangerous-mode prompt skipped. A failed archive stops the loop, while aclaudethat cannot start, as during an update, is retried. - One word names one thing, and one rule has one home. In
bin/, an outcome is an entry of a.outcomes.mdfile in loop-claude's archive, a record is a document tools or people keep entries in, and a place is what a comprehension seat names.CLAUDE.mdholds only the rules no path can scope, and eachrules/file loads by itspaths:.
Decisions no project principle covers
- bin/: the tools run on the host's Python, with no container, and so do their tests outside CI
- bin/: the tools support only the latest stable Python, and the tests, written in plain unittest, run on it in four pytest-xdist workers
- loop-claude: one session per project, its id derived from the checkout's path relative to
~/code, or to/outside it - loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under
~/.local/state/loop-claude/, and takes the first answer, from its terminal or from loop-inbox, that names that question - machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
- principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
- review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
- 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 unless the fix changes only prose, and never for the judge
- review: a reviewer under
agents/marks a 🔴 or 🟡[misread]where the implementer misread code that had already shipped, each round title counts the marked findings, andscore-outcomeslists them per chunk - 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: 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: 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
- 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
- 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, and a maintain goal weighs 0.5 per point of the confidence an item's test, gate leg or probe adds to it; 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
- 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/ - workflow-bench/: the remote may show the bench cases' names and commit SHAs
Working rules
routing-calls-raised.mdsits at the root of loop-claude's archive ($LOOP_CLAUDE_TRANSCRIPTS, default~/.claude/loop-claude-transcripts). Each of its lines is a call or aReset, with a stamp. A call is new when it is stamped after the latestResetand after the latest stamp thattodo.mdordocs/decisions.md→routing:cites. When there are new calls, file onetodo.mditem to settle them, or refresh the item already filed. Its detail quotes those calls with their stamps, and the routed-chunks table ofrouting-figures.mdbeside 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 indocs/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> Resettorouting-calls-raised.md: the figures then count only chunks finished after it, and its calls may be raised again.- When
~/.claude/settings.jsonhas uncommitted changes, carry them into~/code/claude-configon a branch of their own and merge them through a PR: Claude Code writes that file from any session, anddeploy-releaserefuses to move~/.claudeuntil a release holds them. Read their diff first:git -C ~/.claude diff HEAD -- settings.json. An empty diff means only the model or the key order changed, whichdeploy-releasetakes as no change. When the diff holds a credential, such as a token inenvormcpServers, ask the human to move it out of the file, and commit only once it is gone. A token inenvmoves to the shell profile; a server inmcpServersmoves to~/.claude.jsonwithclaude 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 third time