1048 lines
87 KiB
HTML
1048 lines
87 KiB
HTML
<title>How loop-claude Works</title>
|
||
<meta name="claude:viewport-fit-sides" content="cover">
|
||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,600;12..96,800&family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400&family=JetBrains+Mono:wght@400;600&display=swap">
|
||
<style>
|
||
/* Layout: an A4 booklet. Part 1 is one picture per page with a headline; part 2 holds the detail. Each role keeps one colour on every page. */
|
||
:root {
|
||
--bg: #f6f7f9;
|
||
--paper: #ffffff;
|
||
--ink: #17202c;
|
||
--muted: #5b6676;
|
||
--line: #d3d9e2;
|
||
--you: #b86e00; --you-bg: #fff3df;
|
||
--worker: #2453d6; --worker-bg: #e8eeff;
|
||
--judge: #7b3fc4; --judge-bg: #f2eafc;
|
||
--review: #0b7d70; --review-bg: #e1f5f1;
|
||
--red: #cf3434; --yellow: #c99400; --green: #2a8f52; --grey: #7a8494;
|
||
--code-bg: #1c2430; --code-fg: #e7ecf3;
|
||
--display: "Bricolage Grotesque", "Segoe UI", system-ui, sans-serif;
|
||
--body: "Atkinson Hyperlegible", "Segoe UI", system-ui, sans-serif;
|
||
--mono: "JetBrains Mono", ui-monospace, Menlo, Consolas, monospace;
|
||
}
|
||
@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {
|
||
--bg: #11161d; --paper: #18202a; --ink: #e9edf3; --muted: #a2adbd; --line: #2f3a48;
|
||
--you: #f0a940; --you-bg: #33270f;
|
||
--worker: #7c9dff; --worker-bg: #1b2648;
|
||
--judge: #b88cf0; --judge-bg: #2a1f3d;
|
||
--review: #4fc9b6; --review-bg: #12322e;
|
||
--red: #f06a6a; --yellow: #e8c04a; --green: #5cc486; --grey: #9aa4b4;
|
||
--code-bg: #0b0f14; --code-fg: #e7ecf3; color-scheme: dark; } }
|
||
:root[data-theme="dark"] {
|
||
--bg: #11161d; --paper: #18202a; --ink: #e9edf3; --muted: #a2adbd; --line: #2f3a48;
|
||
--you: #f0a940; --you-bg: #33270f;
|
||
--worker: #7c9dff; --worker-bg: #1b2648;
|
||
--judge: #b88cf0; --judge-bg: #2a1f3d;
|
||
--review: #4fc9b6; --review-bg: #12322e;
|
||
--red: #f06a6a; --yellow: #e8c04a; --green: #5cc486; --grey: #9aa4b4;
|
||
--code-bg: #0b0f14; --code-fg: #e7ecf3; color-scheme: dark; }
|
||
|
||
* { box-sizing: border-box; }
|
||
body { background: var(--bg); color: var(--ink); font: 16px/1.5 var(--body);
|
||
padding-left: max(16px, env(safe-area-inset-left, 0px)); padding-right: max(16px, env(safe-area-inset-right, 0px)); padding-block: 24px; }
|
||
main { max-width: 960px; margin: 0 auto; display: grid; gap: 28px; }
|
||
section.page { background: var(--paper); border: 1px solid var(--line); border-radius: 6px; padding: 40px 44px; display: grid; gap: 18px; align-content: start; min-width: 0; }
|
||
h1, h2, h3 { font-family: var(--display); text-wrap: balance; margin: 0; line-height: 1.12; }
|
||
h1 { font-size: 3.4rem; font-weight: 800; letter-spacing: -0.02em; }
|
||
h2 { font-size: 2rem; font-weight: 800; letter-spacing: -0.01em; }
|
||
h3 { font-size: 1.15rem; font-weight: 600; }
|
||
p { margin: 0; max-width: 65ch; }
|
||
.lead { font-size: 1.25rem; color: var(--muted); max-width: 52ch; }
|
||
.eyebrow { font: 700 0.75rem/1 var(--body); letter-spacing: 0.12em; text-transform: uppercase; color: var(--muted); }
|
||
code, .mono { font-family: var(--mono); font-size: 0.88em; }
|
||
code { background: var(--bg); border: 1px solid var(--line); border-radius: 3px; padding: 0 4px; }
|
||
.diagram { overflow-x: auto; }
|
||
.diagram svg { display: block; width: 100%; min-width: 640px; height: auto; }
|
||
.note { font-size: 0.92rem; color: var(--muted); }
|
||
|
||
/* SVG parts */
|
||
svg text { font-family: var(--body); fill: var(--ink); }
|
||
svg .t { font: 700 17px var(--display); fill: var(--ink); }
|
||
svg .s { font-size: 13.5px; fill: var(--muted); }
|
||
svg .lbl { font-size: 13px; fill: var(--muted); }
|
||
svg .num { font: 800 13px var(--display); fill: var(--paper); }
|
||
svg .edge { stroke: var(--muted); stroke-width: 2; fill: none; }
|
||
svg .dash { stroke-dasharray: 6 5; }
|
||
svg .head { fill: var(--muted); }
|
||
svg .box { fill: var(--paper); stroke: var(--line); stroke-width: 1.5; }
|
||
svg .you { fill: var(--you-bg); stroke: var(--you); stroke-width: 2; }
|
||
svg .worker { fill: var(--worker-bg); stroke: var(--worker); stroke-width: 2; }
|
||
svg .judge { fill: var(--judge-bg); stroke: var(--judge); stroke-width: 2; }
|
||
svg .review { fill: var(--review-bg); stroke: var(--review); stroke-width: 2; }
|
||
svg .f-you { fill: var(--you); } svg .f-worker { fill: var(--worker); } svg .f-judge { fill: var(--judge); } svg .f-review { fill: var(--review); }
|
||
svg .f-green { fill: var(--green); } svg .f-red { fill: var(--red); } svg .f-yellow { fill: var(--yellow); } svg .f-grey { fill: var(--grey); }
|
||
svg .s-green { stroke: var(--green); } svg .s-you { stroke: var(--you); } svg .s-judge { stroke: var(--judge); }
|
||
svg .grid { stroke: var(--line); stroke-width: 1; }
|
||
svg .sect { fill: var(--bg); stroke: var(--line); stroke-width: 1.5; stroke-dasharray: 6 4; }
|
||
svg .sl { font: 700 14px var(--body); fill: var(--ink); letter-spacing: 0.02em; }
|
||
svg .sbr { fill: none; stroke: var(--ink); stroke-width: 1.5; }
|
||
svg .bar { fill: var(--worker); }
|
||
svg .floor { stroke: var(--red); stroke-width: 2; stroke-dasharray: 5 4; }
|
||
|
||
/* Role cards */
|
||
.roles { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 14px; }
|
||
.role { border-radius: 6px; padding: 16px; display: grid; gap: 6px; align-content: start; border-top: 5px solid; background: var(--bg); }
|
||
.role b { font: 700 1.1rem var(--display); }
|
||
.role p { font-size: 0.93rem; }
|
||
.role.you { border-color: var(--you); } .role.you b { color: var(--you); }
|
||
.role.worker { border-color: var(--worker); } .role.worker b { color: var(--worker); }
|
||
.role.judge { border-color: var(--judge); } .role.judge b { color: var(--judge); }
|
||
.role.review { border-color: var(--review); } .role.review b { color: var(--review); }
|
||
|
||
.steps4 { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 14px; }
|
||
.steps4 .role b { color: var(--ink); }
|
||
.kind { display:inline-block; font-size:0.68rem; font-weight:700; letter-spacing:0.04em; text-transform:uppercase; padding:0 6px; border-radius:8px; margin-right:4px; }
|
||
.kind.r { background: var(--worker-bg); color: var(--worker); } .kind.b { background: var(--review-bg); color: var(--review); }
|
||
.kind.m { background: var(--judge-bg); color: var(--judge); } .kind.x { background: var(--you-bg); color: var(--you); }
|
||
table.src-t td:first-child { font-weight: 700; color: var(--muted); }
|
||
table.src-t td:nth-child(2) { white-space: normal; }
|
||
.why { font-size: 0.85rem; color: var(--muted); } .why a { color: var(--worker); font-weight: 700; text-decoration: none; }
|
||
.zoom3 { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }
|
||
.zoom3 .role b { color: var(--ink); }
|
||
.role p b { font: inherit; font-weight: 700; }
|
||
.zoom3 .role p + p { margin-top: 4px; }
|
||
.where { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; align-items: start; }
|
||
.where .col { border-radius: 6px; padding: 14px 16px; background: var(--bg); border-top: 5px solid var(--line); display: grid; gap: 8px; }
|
||
.where .col h3 { font-size: 1.05rem; }
|
||
.where .col > p { font-size: 0.85rem; color: var(--muted); }
|
||
.where ul { list-style: none; margin: 0; padding: 0; display: grid; gap: 6px; font-size: 0.88rem; }
|
||
.where li code { font-weight: 600; }
|
||
.where li span { color: var(--muted); }
|
||
h3.group { color: var(--worker); margin-top: 4px; }
|
||
.intro3 { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 18px; }
|
||
.intro3 .col { display: grid; gap: 8px; align-content: start; border-top: 4px solid var(--line); padding-top: 10px; }
|
||
.intro3 .col:nth-child(1) { border-color: var(--red); } .intro3 .col:nth-child(2) { border-color: var(--worker); } .intro3 .col:nth-child(3) { border-color: var(--review); }
|
||
.intro3 ul { margin: 0; padding-left: 1.1em; display: grid; gap: 8px; }
|
||
.intro-foot { display: grid; grid-template-columns: minmax(0, 1.3fr) minmax(0, 1fr); gap: 18px; align-items: center; border-top: 1px solid var(--line); padding-top: 14px; }
|
||
.tiles { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 10px; }
|
||
.tiles div { display: grid; gap: 2px; }
|
||
.tiles b { font: 800 1.8rem/1 var(--display); color: var(--worker); font-variant-numeric: tabular-nums; }
|
||
.tiles span { font-size: 0.82rem; color: var(--muted); }
|
||
.facts { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 14px; }
|
||
.fact.key { border-left-color: var(--worker); }
|
||
.fact.key b { color: var(--worker); }
|
||
.fact { border-left: 3px solid var(--line); padding: 4px 0 4px 14px; }
|
||
.fact b { display: block; font: 700 1.1rem var(--display); }
|
||
.fact span { color: var(--muted); font-size: 0.93rem; }
|
||
|
||
/* Tables */
|
||
.tablewrap { overflow-x: auto; }
|
||
table { border-collapse: collapse; width: 100%; font-size: 0.92rem; }
|
||
th, td { text-align: left; vertical-align: top; padding: 8px 10px; border-bottom: 1px solid var(--line); }
|
||
th { font-size: 0.75rem; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }
|
||
td:first-child { font-weight: 700; white-space: nowrap; }
|
||
.tag { display: inline-block; font-size: 0.75rem; font-weight: 700; padding: 1px 8px; border-radius: 10px; background: var(--review-bg); color: var(--review); white-space: nowrap; }
|
||
.tag.rare { background: var(--judge-bg); color: var(--judge); }
|
||
|
||
/* Severity */
|
||
.sev { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 12px; }
|
||
.sev div { display: grid; grid-template-columns: auto 1fr; gap: 2px 10px; align-items: center; }
|
||
.dot { width: 18px; height: 18px; border-radius: 50%; grid-row: span 2; }
|
||
.sev b { font-family: var(--display); }
|
||
.sev span { font-size: 0.88rem; color: var(--muted); }
|
||
|
||
/* Terminal */
|
||
pre.term { background: var(--code-bg); color: var(--code-fg); font: 13.5px/1.55 var(--mono); padding: 18px 20px; border-radius: 6px; overflow-x: auto; margin: 0; white-space: pre; }
|
||
pre.term .p { color: #8fb0ff; } pre.term .q { color: #f0b85a; } pre.term .d { color: #8a96a8; } pre.term .g { color: #6fd49a; }
|
||
|
||
.two { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 24px; align-items: start; }
|
||
ul.tight { margin: 0; padding-left: 1.2em; display: grid; gap: 6px; max-width: 70ch; }
|
||
dl.gloss { display: grid; grid-template-columns: max-content 1fr; gap: 8px 20px; margin: 0; }
|
||
dl.gloss dt { font-weight: 700; } dl.gloss dd { margin: 0; color: var(--muted); }
|
||
.part { font: 800 0.9rem var(--display); letter-spacing: 0.1em; text-transform: uppercase; color: var(--worker); }
|
||
|
||
@media (max-width: 720px) {
|
||
section.page { padding: 24px 18px; }
|
||
h1 { font-size: 2.4rem; } h2 { font-size: 1.6rem; }
|
||
.roles, .sev, .steps4 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
|
||
.zoom3, .where, .intro3, .intro-foot { grid-template-columns: 1fr; }
|
||
.facts { grid-template-columns: repeat(2, minmax(0, 1fr)); }
|
||
.two { grid-template-columns: 1fr; }
|
||
dl.gloss { grid-template-columns: 1fr; } dl.gloss dd { margin-bottom: 6px; }
|
||
}
|
||
|
||
@page { size: A4 landscape; margin: 11mm 14mm; }
|
||
@media print {
|
||
body { background: var(--paper); padding: 0; font-size: 14px; }
|
||
main { max-width: none; gap: 0; }
|
||
section.page { border: 0; border-radius: 0; padding: 0; break-after: page; }
|
||
section.page:last-child { break-after: auto; }
|
||
.diagram { overflow: visible; } .diagram svg { min-width: 0; max-height: 100mm; }
|
||
h1 { font-size: 2.6rem; } .lead { font-size: 1.15rem; }
|
||
#overview .diagram svg, #full .diagram svg { max-height: 150mm; }
|
||
#overview h1 { font-size: 1.9rem; } #overview, #full { gap: 8px; }
|
||
#intro h1 { font-size: 2.3rem; } #intro { gap: 12px; }
|
||
#roles .diagram svg { max-height: 52mm; }
|
||
section.page { gap: 14px; }
|
||
tr, .role, .fact, pre.term { break-inside: avoid; }
|
||
table.src-t { font-size: 0.8rem; line-height: 1.35; } table.src-t td, table.src-t th { padding: 5px 8px; }
|
||
#reviewers .diagram svg { max-height: 36mm; }
|
||
#zoom-a, #zoom-c, #chunk, #where { gap: 10px; }
|
||
#zoom-a .role p, #zoom-c .role p, #chunk .role p, #zoom-a table, #zoom-c table, #zoom-a li, #zoom-c li, .where li { font-size: 0.8rem; line-height: 1.35; }
|
||
#zoom-a .role, #zoom-c .role, #chunk .role { padding: 9px 12px; }
|
||
#zoom-a td, #zoom-a th, #zoom-c td, #zoom-c th { padding: 3px 8px; }
|
||
#chunk .diagram svg { max-height: 40mm; }
|
||
#zoom-a ul.tight, #zoom-c ul.tight { gap: 2px; }
|
||
table.rev { font-size: 0.8rem; line-height: 1.35; } table.rev td, table.rev th { padding: 4px 8px; }
|
||
#reviewers { gap: 10px; }
|
||
}
|
||
</style>
|
||
|
||
<main>
|
||
|
||
<!-- ============ PART 1 ============ -->
|
||
|
||
<section class="page" id="intro">
|
||
<div class="eyebrow">loop-claude</div>
|
||
<h1>A software factory that asks you only what is yours to decide</h1>
|
||
<p class="lead">You write down what you want and who it is for. An AI plans the work, writes the code, gets it reviewed and merges it, one pull request at a time, for as long as the plan holds work.</p>
|
||
<div class="intro3">
|
||
<div class="col">
|
||
<h3>The problem</h3>
|
||
<ul>
|
||
<li><b>You babysit the agent.</b> Every few minutes it asks something, or waits for a yes.</li>
|
||
<li><b>It forgets.</b> Long sessions drift, and you explain the same context again.</li>
|
||
<li><b>It guesses.</b> It decides what it should ask, and asks what it could decide.</li>
|
||
<li><b>AI review is noise.</b> It nitpicks forever and still misses what matters. So you review it all again, and nobody can read the code six months later.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="col">
|
||
<h3>What loop-claude does</h3>
|
||
<ul>
|
||
<li><b>It runs unattended.</b> A judge reads every run, and interrupts you only for a choice that is yours.</li>
|
||
<li><b>It starts fresh every chunk.</b> The repo is the memory: goals, plan and decisions are written down.</li>
|
||
<li><b>It decides by your goals.</b> An answer you give is recorded once, and never asked again.</li>
|
||
<li><b>Review, refined by measurement.</b> Narrow specialist reviewers report only real defects, and stop after two rounds: 110 later rounds found no red finding. Tests are checked by breaking the code on purpose. The review is tuned by replaying past rounds.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="col">
|
||
<h3>What it aims for</h3>
|
||
<ul>
|
||
<li><b>Maintainable for years.</b> Code that stays easy to read, change and debug, tomorrow and after seven years.</li>
|
||
<li>The highest quality, with the fewest interruptions.</li>
|
||
<li>Ask only when unsure, and never the same thing twice.</li>
|
||
<li>Keep lowering cost, unless that would cut quality.</li>
|
||
<li>The same rules in every project, and fast delivery.</li>
|
||
</ul>
|
||
<p class="note">Each aim has a signal it is measured by, and a counter-signal that catches it being gamed.</p>
|
||
</div>
|
||
</div>
|
||
<div class="intro-foot">
|
||
<p><b>For</b> developers and teams who build with AI agents and want a software factory: work that keeps flowing without someone watching it, at a quality they would sign off on.</p>
|
||
<div class="tiles">
|
||
<div><b>466</b><span>chunks finished since 2026-10-03, one PR each</span></div>
|
||
<div><b>12</b><span>projects that finished a chunk</span></div>
|
||
<div><b>2,538</b><span>commits in the setup's own repo</span></div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="page" id="overview">
|
||
<div class="eyebrow">The flow, simply</div>
|
||
<h1>An AI that works through your plan, one pull request at a time</h1>
|
||
<p class="lead">Three sections. A picks the work, B does it, C checks the result. The next page opens up every box, in the same places.</p>
|
||
<div class="diagram" role="img" aria-label="Simple flow. The human writes goals and audience. A, Start, deterministic: pick the next work. B, Work, the worker: build, review and merge one pull request. C, Check, the judge: finished goes back to A with a fresh context; keep going and the human's call go back to B. When the release is done, the human cuts it.">
|
||
<svg viewBox="0 0 1200 640">
|
||
<defs><marker id="ahs" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
<rect class="you" x="10" y="6" width="290" height="50" rx="7"/>
|
||
<text class="t" x="24" y="27" style="font-size:15px">Human: goals + audience</text><text class="s" x="24" y="46">in README</text>
|
||
<path class="edge" d="M155,56 L155,67" marker-end="url(#ahs)"/>
|
||
|
||
<rect class="sect" x="10" y="70" width="290" height="410" rx="10"/>
|
||
<text class="sl" x="24" y="92">A · Start <tspan class="s">(deterministic, no AI)</tspan></text>
|
||
<rect class="box" x="24" y="108" width="262" height="336" rx="8" style="stroke-width:2"/>
|
||
<text class="t" x="40" y="146" style="font-size:22px">Pick the next work</text>
|
||
<text class="s" x="40" y="182">the top ready item in the plan,</text>
|
||
<text class="s" x="40" y="202">and the model to do it</text>
|
||
<text class="lbl" x="40" y="376" style="font-weight:700">opens up into</text>
|
||
<text class="lbl" x="40" y="396">Rank the plan · Prepare</text>
|
||
<text class="lbl" x="40" y="414">Pick the work · Pick model</text>
|
||
<path class="edge" d="M24,420 L18,420 L18,527 L36,527" marker-end="url(#ahs)"/>
|
||
<text class="lbl" x="28" y="495" style="font-weight:700">release done</text>
|
||
<rect class="you" x="40" y="500" width="260" height="54" rx="7"/>
|
||
<text class="t" x="52" y="522" style="font-size:15px">Human cuts the release</text><text class="s" x="52" y="543">the loop stops and waits</text>
|
||
|
||
<rect class="sect" x="350" y="10" width="840" height="370" rx="10"/>
|
||
<text class="sl" x="362" y="32">B · Work <tspan class="s">(the worker AI) · one pull request</tspan></text>
|
||
<rect class="worker" x="362" y="48" width="816" height="150" rx="8"/>
|
||
<text class="t" x="380" y="88" style="font-size:22px">Build, review and merge one pull request</text>
|
||
<text class="s" x="380" y="118">AI reviewers check every change. Problems go back to the worker to fix.</text>
|
||
<text class="lbl" x="380" y="160" style="font-weight:700">opens up into</text>
|
||
<text class="lbl" x="380" y="180">Build · Review · Gate · Goals check · Readability · Merge</text>
|
||
<rect class="review" x="500" y="220" width="540" height="56" rx="7"/>
|
||
<text class="t" x="514" y="246" style="font-size:15px">+ Release review</text><text class="s" x="514" y="266">once per release, over the whole project</text>
|
||
<rect class="box" x="500" y="292" width="590" height="56" rx="7" style="stroke-dasharray:5 4"/>
|
||
<text class="t" x="514" y="318" style="font-size:15px">→ New items into the plan</text><text class="s" x="514" y="338">problems found outside the chunk become new work</text>
|
||
|
||
<rect class="sect" x="350" y="400" width="840" height="234" rx="10"/>
|
||
<text class="sl" x="362" y="422">C · Check <tspan class="s">(the judge AI) · its verdict</tspan></text>
|
||
<rect class="judge" x="1040" y="452" width="144" height="80" rx="7"/>
|
||
<text class="t" x="1052" y="476" style="font-size:15px">Judge reads</text><text class="s" x="1052" y="498">done? stuck?</text><text class="s" x="1052" y="516">a question?</text>
|
||
<rect class="box" x="362" y="452" width="200" height="80" rx="7" style="stroke: var(--green); stroke-width:2"/>
|
||
<circle class="f-green" cx="378" cy="471" r="6"/><text class="t" x="390" y="476" style="font-size:15px">Finished</text>
|
||
<text class="s" x="372" y="498">next chunk, with a</text><text class="s" x="372" y="516" style="fill:var(--worker);font-weight:700">fresh context</text>
|
||
<rect class="box" x="578" y="452" width="200" height="80" rx="7"/>
|
||
<circle class="f-grey" cx="594" cy="471" r="6"/><text class="t" x="606" y="476" style="font-size:15px">Keep going</text>
|
||
<text class="s" x="588" y="498">unfinished, or the</text><text class="s" x="588" y="516">records answer it</text>
|
||
<rect class="you" x="794" y="452" width="224" height="80" rx="7"/>
|
||
<circle class="f-you" cx="810" cy="471" r="6"/><text class="t" x="822" y="476" style="font-size:15px">Human's call</text>
|
||
<text class="s" x="804" y="498">only a human can</text><text class="s" x="804" y="516">decide; they answer</text>
|
||
<path class="edge" d="M1112,532 L1112,552 L462,552 L462,538" marker-end="url(#ahs)"/>
|
||
<path class="edge" d="M678,552 L678,538" marker-end="url(#ahs)"/>
|
||
<path class="edge" d="M906,552 L906,538" marker-end="url(#ahs)"/>
|
||
|
||
<path class="edge" d="M1115,198 L1115,448" marker-end="url(#ahs)"/>
|
||
<path class="edge" d="M678,452 L678,436 L906,436 L906,452"/>
|
||
<path class="edge" d="M792,436 L792,386" marker-end="url(#ahs)"/>
|
||
<text class="lbl" x="802" y="404" style="font-weight:700">back to B · same session, with the answer</text>
|
||
<path class="edge" d="M362,492 L318,492 L318,388 A8,8 0 0 0 318,372 L318,221 L292,221" marker-end="url(#ahs)"/>
|
||
<path class="edge" d="M286,380 L332,380 L332,123 L358,123" marker-end="url(#ahs)"/>
|
||
</svg>
|
||
</div>
|
||
<p class="why">Why: sources <a href="#src-1">1</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="full">
|
||
<div class="eyebrow">The flow, every piece</div>
|
||
<h2>The same three sections, opened up</h2>
|
||
<p class="lead">Same layout as the last page. Each big box there is the group of steps in the same place here.</p>
|
||
<div class="diagram" role="img" aria-label="The full flow. The human writes goals and audience in the README; the plan in todo.md feeds A. A, Start, deterministic: prepare, pick the work, pick a model. When the release is done, the loop stops and the human cuts the release. B, Work, the worker: build, review, gate, goals check, readability panel, merge; findings and failed checks go back to build; a stuck worker moves to a stronger model; a planning chunk is drafted by the worker and approved by the human; the release review adds architecture and principles over the whole project and a before-and-after readability ruling; new items go into the plan. C, Check, the judge: finished goes back to A with a fresh context; unfinished, already settled and human's call go back to B in the same session; every 20 cycles routing figures go to the human.">
|
||
<svg viewBox="0 0 1200 640">
|
||
<defs><marker id="ah" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
|
||
<!-- Human, above A -->
|
||
<rect class="you" x="10" y="6" width="290" height="50" rx="7"/>
|
||
<text class="t" x="24" y="27" style="font-size:15px">Human: goals + audience</text><text class="s" x="24" y="46">in README</text>
|
||
<path class="edge" d="M155,56 L155,67" marker-end="url(#ah)"/>
|
||
|
||
|
||
<!-- A -->
|
||
<rect class="sect" x="10" y="70" width="290" height="410" rx="10"/>
|
||
<text class="sl" x="24" y="92">A · Start <tspan class="s">(deterministic, no AI)</tspan></text>
|
||
<path class="box" d="M24,104 L268,104 L286,122 L286,166 L24,166 Z"/>
|
||
<path class="edge" d="M268,104 L268,122 L286,122" style="stroke:var(--line);stroke-width:1.5"/>
|
||
<text class="t" x="36" y="125" style="font-size:15px">Rank the plan · todo.md</text><text class="s" x="36" y="143">scores every item and sorts it:</text><text class="s" x="36" y="159">best value for its size first</text>
|
||
<rect class="box" x="24" y="194" width="262" height="54" rx="7"/>
|
||
<text class="t" x="36" y="216" style="font-size:15px">Prepare</text><text class="s" x="36" y="237">fetch, fresh worktree, facts</text>
|
||
<path class="edge" d="M160,248 L160,264" marker-end="url(#ah)"/>
|
||
<polygon class="box" points="160,268 285,304 160,340 35,304"/>
|
||
<text class="t" x="160" y="301" text-anchor="middle" style="font-size:15px">Pick the work</text>
|
||
<text class="s" x="160" y="320" text-anchor="middle" style="font-size:12.5px">top item that is ready</text>
|
||
<path class="edge" d="M160,340 L160,368" marker-end="url(#ah)"/>
|
||
<rect class="box" x="24" y="372" width="262" height="72" rx="7"/>
|
||
<text class="t" x="36" y="394" style="font-size:15px">Pick model</text>
|
||
<text class="s" x="36" y="414">for an item, the release review</text><text class="s" x="36" y="432">or planning the next release</text>
|
||
<path class="edge" d="M35,304 L20,304 L20,527 L36,527" marker-end="url(#ah)"/>
|
||
<text class="lbl" x="28" y="495" style="font-weight:700">release done</text>
|
||
<rect class="you" x="40" y="500" width="260" height="54" rx="7"/>
|
||
<text class="t" x="52" y="522" style="font-size:15px">Human cuts the release</text><text class="s" x="52" y="543">the loop stops and waits</text>
|
||
|
||
<!-- B -->
|
||
<rect class="sect" x="350" y="10" width="840" height="370" rx="10"/>
|
||
<text class="sl" x="362" y="32">B · Work <tspan class="s">(the worker AI) · one pull request</tspan></text>
|
||
<rect class="worker" x="362" y="48" width="126" height="100" rx="7"/>
|
||
<text class="t" x="372" y="72" style="font-size:15px">Build</text><text class="s" x="372" y="94">test first,</text><text class="s" x="372" y="112">then code,</text><text class="s" x="372" y="130">draft PR</text>
|
||
<rect class="review" x="500" y="48" width="126" height="100" rx="7"/>
|
||
<text class="t" x="510" y="72" style="font-size:15px">Review</text><text class="s" x="510" y="94">reviewer waves,</text><text class="s" x="510" y="112">max 2 rounds</text><text class="s" x="510" y="130">each</text>
|
||
<rect class="box" x="638" y="48" width="126" height="100" rx="7"/>
|
||
<text class="t" x="648" y="72" style="font-size:15px">Gate</text><text class="s" x="648" y="94">tests + CI,</text><text class="s" x="648" y="112">review bot</text>
|
||
<rect class="box" x="776" y="48" width="126" height="100" rx="7"/>
|
||
<text class="t" x="786" y="72" style="font-size:15px">Goals check</text><text class="s" x="786" y="94">against a goal?</text><text class="s" x="786" y="112">→ ask human</text>
|
||
<rect class="review" x="914" y="48" width="126" height="100" rx="7"/>
|
||
<text class="t" x="924" y="72" style="font-size:15px">Readability</text><text class="s" x="924" y="94">reader panel,</text><text class="s" x="924" y="112">when due</text>
|
||
<rect class="box" x="1052" y="48" width="126" height="100" rx="7" style="stroke: var(--green); stroke-width: 2"/>
|
||
<text class="t" x="1062" y="72" style="font-size:15px">Merge</text><text class="s" x="1062" y="94">items leave</text><text class="s" x="1062" y="112">the plan</text>
|
||
<path class="edge" d="M488,98 L496,98" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M626,98 L634,98" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M764,98 L772,98" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M902,98 L910,98" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M1040,98 L1048,98" marker-end="url(#ah)"/>
|
||
<path class="edge dash" d="M540,148 L540,162 L440,162 L440,154" marker-end="url(#ah)"/>
|
||
<text class="lbl" x="548" y="167">findings → fix</text>
|
||
<path class="edge dash" d="M680,148 L680,180 L410,180 L410,154" marker-end="url(#ah)"/>
|
||
<text class="lbl" x="688" y="185">failed check → fix</text>
|
||
<text class="lbl" x="362" y="206" style="fill:var(--worker);font-weight:700">stuck twice?</text>
|
||
<text class="lbl" x="362" y="222" style="fill:var(--worker);font-weight:700">→ stronger model</text>
|
||
<text class="lbl" x="362" y="248" style="font-weight:700">planning chunk?</text>
|
||
<text class="lbl" x="362" y="264">the worker drafts,</text>
|
||
<text class="lbl" x="362" y="280">the human approves</text>
|
||
|
||
<path class="edge dash" d="M600,148 L600,206"/>
|
||
<path class="edge dash" d="M977,148 L977,206"/>
|
||
<rect class="review" x="500" y="206" width="540" height="70" rx="7" style="stroke-width:2.5"/>
|
||
<text class="t" x="514" y="230" style="font-size:15px">+ Release review <tspan class="s">(the release's last chunk, on top of all the above)</tspan></text>
|
||
<text class="s" x="514" y="252">Architecture + Principles read the whole project, up to 5 rounds each.</text>
|
||
<text class="s" x="514" y="268">Readability: the panel rules before vs. after.</text>
|
||
|
||
<rect class="box" x="500" y="292" width="590" height="72" rx="7" style="stroke-dasharray:5 4"/>
|
||
<text class="t" x="514" y="314" style="font-size:15px">→ New items into the plan (todo.md)</text>
|
||
<text class="s" x="514" y="336">a finding outside this chunk · readability under 7.0 → a refactor item</text>
|
||
<text class="s" x="514" y="354">reading cost rising (what a chunk reads before it writes) → an item to lower it</text>
|
||
|
||
<!-- C -->
|
||
<rect class="sect" x="350" y="400" width="840" height="234" rx="10"/>
|
||
<text class="sl" x="362" y="422">C · Check <tspan class="s">(the judge AI) · its verdict</tspan></text>
|
||
<rect class="judge" x="1040" y="452" width="144" height="80" rx="7"/>
|
||
<text class="t" x="1052" y="476" style="font-size:15px">Judge reads</text><text class="s" x="1052" y="498">the run, goals</text><text class="s" x="1052" y="516">and decisions</text>
|
||
<rect class="box" x="362" y="452" width="152" height="80" rx="7" style="stroke: var(--green); stroke-width:2"/>
|
||
<circle class="f-green" cx="378" cy="471" r="6"/><text class="t" x="390" y="476" style="font-size:15px">Finished</text>
|
||
<text class="s" x="372" y="498">PR merged. To A,</text><text class="s" x="372" y="516" style="fill:var(--worker);font-weight:700">fresh context</text>
|
||
<rect class="box" x="530" y="452" width="152" height="80" rx="7"/>
|
||
<circle class="f-grey" cx="546" cy="471" r="6"/><text class="t" x="558" y="476" style="font-size:15px">Unfinished</text>
|
||
<text class="s" x="540" y="498">work is left;</text><text class="s" x="540" y="516">6 in a row → human</text>
|
||
<rect class="judge" x="698" y="452" width="152" height="80" rx="7"/>
|
||
<circle class="f-judge" cx="714" cy="471" r="6"/><text class="t" x="726" y="476" style="font-size:15px">Already settled</text>
|
||
<text class="s" x="708" y="498">the records</text><text class="s" x="708" y="516">answer it</text>
|
||
<rect class="you" x="866" y="452" width="152" height="80" rx="7"/>
|
||
<circle class="f-you" cx="882" cy="471" r="6"/><text class="t" x="894" y="476" style="font-size:15px">Human's call</text>
|
||
<text class="s" x="876" y="498">terminal, inbox</text><text class="s" x="876" y="516">or /talk</text>
|
||
<path class="edge" d="M1112,532 L1112,552 L438,552 L438,538" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M606,552 L606,538" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M774,552 L774,538" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M942,552 L942,538" marker-end="url(#ah)"/>
|
||
<rect class="you" x="866" y="572" width="318" height="50" rx="7"/>
|
||
<text class="t" x="878" y="593" style="font-size:15px">Every 20 cycles</text><text class="s" x="878" y="612">routing figures → human decides model changes</text>
|
||
|
||
<!-- drawn last, so the section backgrounds never cover them -->
|
||
<path class="edge" d="M155,166 L155,190" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M1115,148 L1115,448" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M606,452 L606,436 L942,436 L942,452"/>
|
||
<path class="edge" d="M774,452 L774,436"/>
|
||
<path class="edge" d="M720,436 L720,386" marker-end="url(#ah)"/>
|
||
<text class="lbl" x="730" y="404" style="font-weight:700">back to B · same session, with the answer</text>
|
||
<path class="edge" d="M362,492 L318,492 L318,416 A8,8 0 0 0 318,400 L318,221 L292,221" marker-end="url(#ah)"/>
|
||
<path class="edge" d="M286,408 L332,408 L332,98 L358,98" marker-end="url(#ah)"/>
|
||
</svg>
|
||
</div>
|
||
|
||
<p class="why">Why: sources <a href="#src-1">1</a>, <a href="#src-2">2</a>, <a href="#src-3">3</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="roles">
|
||
<div class="eyebrow">Who is who</div>
|
||
<h2>Four roles</h2>
|
||
<p class="lead">One human. Three kinds of AI, each with one job.</p>
|
||
<div class="roles">
|
||
<div class="role you"><b>Human</b><p>Write the goals and the audience in the README. Approve the plan. Answer questions. Cut releases.</p></div>
|
||
<div class="role worker"><b>Worker</b><p>A Claude Code session with no human at the keyboard. It writes tests and code, opens the PR and runs the review.</p></div>
|
||
<div class="role judge"><b>Judge</b><p>A second, short AI run after each worker run. It reads the log and decides: finished, keep going, or ask you.</p></div>
|
||
<div class="role review"><b>Reviewers</b><p>Specialist AIs. Each looks at the change from one angle and reports problems. They never edit code.</p></div>
|
||
</div>
|
||
|
||
<div class="facts">
|
||
<div class="fact key"><b>A fresh start every chunk</b><span>Each chunk gets a new AI session with an empty context. Nothing piles up, so it can run for long stretches, as far as the plan reaches.</span></div>
|
||
<div class="fact"><b>One chunk = one PR</b><span>Each turn of the loop ships one small, reviewed pull request.</span></div>
|
||
<div class="fact"><b>Many AI reviewers</b><span>Security, stability, product, prose. Every change is checked before merge.</span></div>
|
||
<div class="fact"><b>You stay in charge</b><span>Goals, open questions and releases are yours. Nothing ships a release without you.</span></div>
|
||
</div>
|
||
<p class="why">Why: sources <a href="#src-3">3</a>, <a href="#src-4">4</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="where">
|
||
<div class="eyebrow">Where things live</div>
|
||
<h2>Three places</h2>
|
||
<p class="lead">Your project's repo holds its own goals, plan and decisions. The setup holds the rules, reviewers and tools that every project shares.</p>
|
||
<div class="where">
|
||
<div class="col" style="border-top-color:var(--you)">
|
||
<h3>Your project's repo</h3>
|
||
<p>One per project. Everything the next chunk needs.</p>
|
||
<ul>
|
||
<li><code>README.md</code> <span>goals and audience</span></li>
|
||
<li><code>todo.md</code> <span>the plan: one scored table</span></li>
|
||
<li><code>AGENTS.md</code> <span>working rules, and every decision's title</span></li>
|
||
<li><code>docs/decisions.md</code> <span>answers given once, with the reason</span></li>
|
||
<li><code>docs/comprehension-history.md</code> <span>every readability score</span></li>
|
||
<li><code>docs/reading-cost.md</code> <span>what each chunk read</span></li>
|
||
<li><code>CHANGELOG.md</code> <span>what users get, if it publishes</span></li>
|
||
<li>the code and its tests</li>
|
||
</ul>
|
||
</div>
|
||
<div class="col" style="border-top-color:var(--worker)">
|
||
<h3>The setup: <code>~/.claude</code></h3>
|
||
<p>The <code>claude-config</code> repo, at a tagged release. Shared by every project.</p>
|
||
<ul>
|
||
<li><code>CLAUDE.md</code> <span>rules every session follows</span></li>
|
||
<li><code>rules/</code> <span>topic rules, loaded when a matching file is touched</span></li>
|
||
<li><code>agents/</code> <span>the reviewers</span></li>
|
||
<li><code>skills/larv-review/</code> <span>the review recipe and its standards</span></li>
|
||
<li><code>skills/comprehension-panel/</code> <span>the simulated readers</span></li>
|
||
<li><code>principles/</code> <span>technical principles reviewers hold code to</span></li>
|
||
<li><code>bin/</code> <span>the tools: <code>loop-claude</code>, <code>loop-inbox</code>, <code>chunk-preflight</code>, <code>chunk-pr</code>, <code>rule-hook</code>, <code>rank_todo.py</code>, <code>run-heavy</code> and more</span></li>
|
||
<li><code>settings.json</code> <span>runs <code>rule-hook</code> before each Agent, Bash, Edit, Read, Skill and Write call</span></li>
|
||
</ul>
|
||
</div>
|
||
<div class="col" style="border-top-color:var(--judge)">
|
||
<h3>The machine and the forge</h3>
|
||
<p>Not tracked by either repo. The archive and the models file sit inside <code>~/.claude</code>, but git ignores them.</p>
|
||
<ul>
|
||
<li><code>~/code/<repo>-item-<ID></code> <span>a worktree per chunk; its branch <code>item-<ID></code> becomes the PR</span></li>
|
||
<li><code>~/.claude/loop-claude-transcripts/</code> <span>every run's full log</span></li>
|
||
<li><code>~/.local/state/larv-review/</code> <span>every review report</span></li>
|
||
<li><code>~/.local/state/loop-claude/</code> <span>open questions, for <code>loop-inbox</code></span></li>
|
||
<li><code>~/.claude/loop-claude-models.json</code> <span>each project's model</span></li>
|
||
<li>the forge (GitHub or Gitea) <span>the pull request and CI</span></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<p class="note">The worker never commits to <code>main</code>. The setup itself is developed in <code>~/code/claude-config</code>, by the same loop; <code>~/.claude</code> only ever holds a release.</p>
|
||
<p class="why">Why: sources <a href="#src-5">5</a>, <a href="#src-6">6</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="zoom-a">
|
||
<div class="eyebrow">Zoom in: A · Start</div>
|
||
<h2>A · Start, in detail</h2>
|
||
<p class="lead">Plain code, no AI. It decides what the next chunk is, and which model does it.</p>
|
||
<div class="zoom3">
|
||
<div class="role" style="border-color:var(--line)"><b>Before anything</b>
|
||
<p>The README must hold <code>## Goals</code> and <code>## Audience</code>. Without them the loop refuses to start.</p>
|
||
<p>Each worker waits until a quarter of the machine's memory is free.</p></div>
|
||
<div class="role" style="border-color:var(--line)"><b>Prepare</b>
|
||
<p><code>chunk-preflight</code> fetches the repo and reads <code>todo.md</code> as <code>main</code> holds it.</p>
|
||
<p>It makes a worktree beside your checkout, on its own branch. There it runs four checks: the plan's ranking, whether a readability score is due, the reading cost, and the hardest places to read.</p></div>
|
||
<div class="role" style="border-color:var(--line)"><b>The first prompt</b>
|
||
<p>The task, the README's goals and audience, and every fact Prepare found: the last release, unreleased changes, the item, the items that may join it, the files it names, open PRs.</p>
|
||
<p>It also names the models to review on.</p></div>
|
||
</div>
|
||
<div class="two">
|
||
<div style="display:grid;gap:6px">
|
||
<h3>Rank the plan, then pick the work</h3>
|
||
<ul class="tight">
|
||
<li><b>Rank:</b> <code>rank_todo.py</code> scores every item from its L, E, I, size and the goals it moves, and sorts the plan. A commit that changes <code>todo.md</code> waits until it is ranked.</li>
|
||
<li>An item <b>waits</b> while it is a question for the human, or while an item that blocks it is still in the plan.</li>
|
||
<li>The chunk takes the first item that doesn't wait, plus every item of the same release that needs the same reviewers.</li>
|
||
<li>An item with risk R above 5 ships alone. Up to ten tiny items can share a chunk.</li>
|
||
</ul>
|
||
<h3>Pick model</h3>
|
||
<ul class="tight">
|
||
<li><b>Worker:</b> by the item's L. L 1–2 one rung down, L 3 the project's model, L 4 one up.</li>
|
||
<li><b>Reviewers:</b> the highest of the worker's model, the project's, and a step up for a high E + I. Readers and security: the project's model. The judge: never below it.</li>
|
||
<li>The worker steps up after every second unfinished verdict, or when stuck. At most two rungs without asking.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="tablewrap">
|
||
<table>
|
||
<thead><tr><th>When the next release…</th><th>The chunk is</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>has a ready item</td><td>a normal chunk</td></tr>
|
||
<tr><td>has no items left, but unreleased work</td><td>the release review</td></tr>
|
||
<tr><td>has had its release review</td><td>none: the loop stops, and the human cuts the release</td></tr>
|
||
<tr><td>has no items and no work yet</td><td>planning: the worker moves the best items in, and the human approves them</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<p class="why">Why: sources <a href="#src-2">2</a>, <a href="#src-25">25</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="chunk">
|
||
<div class="eyebrow">Zoom in: B · Work</div>
|
||
<h2>B · Work, in detail</h2>
|
||
<p class="lead">The worker follows a fixed recipe, called <b>larv-review</b>. The same six steps as page 1.</p>
|
||
<div class="diagram" role="img" aria-label="Build: a test that fails first, the simplest code, a draft PR. Then review, gate, goals check, readability and merge.">
|
||
<svg viewBox="0 0 1090 150">
|
||
<g>
|
||
<path class="sbr" d="M12,34 L12,26 L416,26 L416,34"/><text class="sl" x="214" y="16" text-anchor="middle">Build</text>
|
||
<path class="sbr" d="M414,34 L414,26 L550,26 L550,34"/><text class="sl" x="482" y="16" text-anchor="middle">Review</text>
|
||
<path class="sbr" d="M548,34 L548,26 L684,26 L684,34"/><text class="sl" x="616" y="16" text-anchor="middle">Gate</text>
|
||
<path class="sbr" d="M682,34 L682,26 L818,26 L818,34"/><text class="sl" x="750" y="16" text-anchor="middle">Goals check</text>
|
||
<path class="sbr" d="M816,34 L816,26 L952,26 L952,34"/><text class="sl" x="884" y="16" text-anchor="middle">Readability</text>
|
||
<path class="sbr" d="M950,34 L950,26 L1086,26 L1086,34"/><text class="sl" x="1018" y="16" text-anchor="middle">Merge</text>
|
||
</g>
|
||
<g>
|
||
<path class="worker" d="M10,40 L130,40 L150,90 L130,140 L10,140 L28,90 Z"/>
|
||
<text class="t" x="34" y="84">Test</text><text class="s" x="34" y="106">fails first</text>
|
||
<path class="worker" d="M144,40 L264,40 L284,90 L264,140 L144,140 L164,90 Z"/>
|
||
<text class="t" x="172" y="84">Code</text><text class="s" x="172" y="106">simplest fix</text>
|
||
<path class="worker" d="M278,40 L398,40 L418,90 L398,140 L278,140 L298,90 Z"/>
|
||
<text class="t" x="306" y="84">Draft PR</text><text class="s" x="306" y="106">CI starts</text>
|
||
<path class="review" d="M412,40 L532,40 L552,90 L532,140 L412,140 L432,90 Z"/>
|
||
<text class="t" x="440" y="84">Review</text><text class="s" x="440" y="106">in waves</text>
|
||
<path class="box" d="M546,40 L666,40 L686,90 L666,140 L546,140 L566,90 Z"/>
|
||
<text class="t" x="574" y="84">Gate</text><text class="s" x="574" y="106">tests, CI</text>
|
||
<path class="box" d="M680,40 L800,40 L820,90 L800,140 L680,140 L700,90 Z"/>
|
||
<text class="t" x="708" y="84">Goals?</text><text class="s" x="708" y="106">still aligned</text>
|
||
<path class="review" d="M814,40 L934,40 L954,90 L934,140 L814,140 L834,90 Z"/>
|
||
<text class="t" x="842" y="84">Readers</text><text class="s" x="842" y="106">when due</text>
|
||
<path class="box" d="M948,40 L1068,40 L1088,90 L1068,140 L948,140 L968,90 Z" style="stroke: var(--green); stroke-width:2"/>
|
||
<text class="t" x="976" y="84">Merge</text><text class="s" x="976" y="106">PR done</text>
|
||
</g>
|
||
</svg>
|
||
</div>
|
||
<div class="zoom3">
|
||
<div class="role worker"><b>Build</b>
|
||
<p>A test comes first, and the worker sees it fail. Its expected values come from the item, never from the code.</p>
|
||
<p>Then the simplest change that makes it pass. A draft PR opens, so CI runs while review goes on.</p>
|
||
<p><b>Stuck?</b> The same test fails after two fixes, or a round 2 still reports a red finding: the hard part goes to a stronger model.</p></div>
|
||
<div class="role review"><b>Review</b>
|
||
<p>Specialist reviewers, in waves. At most two rounds each per chunk. Only the fix for a red finding runs a reviewer again.</p>
|
||
<p>The release review adds the architect and the principles auditor on top: the whole project, up to five rounds each.</p></div>
|
||
<div class="role" style="border-color:var(--grey)"><b>Gate</b>
|
||
<p>Merge the latest <code>main</code> in. Check the plan's format. Run the tests. Wait for every CI check.</p>
|
||
<p>Mark the PR ready. Then wait up to ten minutes for the repo's own review bot, if it has one.</p></div>
|
||
<div class="role" style="border-color:var(--grey)"><b>Goals check</b>
|
||
<p>Does the PR break a goal the project must keep? Then it does not merge. The change is redesigned, or its item dropped.</p>
|
||
<p>Does it work against a goal the project aims for? Then the human is asked.</p></div>
|
||
<div class="role review"><b>Readability</b>
|
||
<p>When due, simulated readers score the project, or compare it before and after. It never blocks the merge. A low score adds a refactor item to the plan.</p></div>
|
||
<div class="role" style="border-color:var(--green)"><b>Merge</b>
|
||
<p>Merge the PR. Remove its items from <code>todo.md</code>, and move them to <code>CHANGELOG.md</code> if the repo publishes something.</p>
|
||
<p>The session ends. The next chunk starts fresh.</p></div>
|
||
</div>
|
||
<p class="note">A planning chunk follows the same steps. Its change is plan rows, and the human approves them before any code is written. <span class="why">Why: sources <a href="#src-7">7</a>, <a href="#src-8">8</a>, <a href="#src-19">19</a>, <a href="#src-20">20</a>, <a href="#src-21">21</a></span></p>
|
||
</section>
|
||
|
||
<section class="page" id="reviewers">
|
||
<div class="eyebrow">Zoom in: B · Work → Review</div>
|
||
<h2>The reviewers</h2>
|
||
<p class="lead">Each reviewer has one narrow job: a merged reviewer loses one pass's findings. They run in waves, each once the one before is done. Wave 1 runs only in the release review.</p>
|
||
<div class="diagram" role="img" aria-label="Wave 1: architecture. Wave 2: principles, security, overrides. Wave 3: stability, product owner, prose. Each wave starts when the one before it is done. Wave 1 runs only in the release review.">
|
||
<svg viewBox="0 0 960 150">
|
||
<defs><marker id="ah4" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
<text class="sl" x="20" y="18">Wave 1 · the big picture</text>
|
||
<rect class="review" x="20" y="30" width="260" height="34" rx="6"/><text class="t" x="34" y="53" style="font-size:15px">Architecture</text>
|
||
<path class="edge" d="M286,47 L330,47" marker-end="url(#ah4)"/>
|
||
<text class="sl" x="340" y="18">Wave 2 · rules and risk</text>
|
||
<rect class="review" x="340" y="30" width="260" height="34" rx="6"/><text class="t" x="354" y="53" style="font-size:15px">Principles</text>
|
||
<rect class="review" x="340" y="72" width="260" height="34" rx="6"/><text class="t" x="354" y="95" style="font-size:15px">Security</text>
|
||
<rect class="review" x="340" y="114" width="260" height="34" rx="6"/><text class="t" x="354" y="137" style="font-size:15px">Overrides</text>
|
||
<path class="edge" d="M606,89 L650,89" marker-end="url(#ah4)"/>
|
||
<text class="sl" x="660" y="18">Wave 3 · the details</text>
|
||
<rect class="review" x="660" y="30" width="280" height="34" rx="6"/><text class="t" x="674" y="53" style="font-size:15px">Stability</text>
|
||
<rect class="review" x="660" y="72" width="280" height="34" rx="6"/><text class="t" x="674" y="95" style="font-size:15px">Product owner</text>
|
||
<rect class="review" x="660" y="114" width="280" height="34" rx="6"/><text class="t" x="674" y="137" style="font-size:15px">Prose</text>
|
||
</svg>
|
||
</div>
|
||
<div class="tablewrap">
|
||
<table class="rev"><colgroup><col style="width:13%"><col style="width:37%"><col style="width:50%"></colgroup>
|
||
<thead><tr><th>Reviewer</th><th>Runs when</th><th>Why it is its own reviewer</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>Architecture</td><td>Only in the release review, the last chunk of a release.</td><td>Structure drifts slowly over many small PRs; only a read of the whole project shows it. Each finding names a future change the code makes harder.</td></tr>
|
||
<tr><td>Principles</td><td>Only in the release review.</td><td>Holds the whole project to the goals and the written technical principles: a checklist read, not a design read.</td></tr>
|
||
<tr><td>Security</td><td>Code or config changed. A deeper multi-agent scan instead when it touches login, permissions, secrets, crypto, untrusted input or a new outside surface.</td><td>Finding holes takes an attacker's mindset. A correctness reviewer looks for what breaks, not for what can be abused.</td></tr>
|
||
<tr><td>Overrides</td><td>The worker bypassed a rule that a program enforces, with a written reason.</td><td>The worker cannot judge its own exception. A second opinion keeps the rule, or accepts the reason.</td></tr>
|
||
<tr><td>Stability</td><td>Code, config or tests changed.</td><td>Bugs, edge cases, error handling, line by line. It breaks the changed lines on purpose (mutation testing) to see whether the tests notice.</td></tr>
|
||
<tr><td>Product owner</td><td>Something users see changed: an API, CLI flags or exit codes, a file format, UI, error text, docs.</td><td>Reads the change as a user would. Ease of use and upgrade paths are invisible from inside the code.</td></tr>
|
||
<tr><td>Prose</td><td>Text changed: docs, comments, help, error messages. One round.</td><td>Writing has its own rules: short, clear, most important first. A docs-only change runs just this light pass, plus product owner for docs outside readers see.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<p class="note">Reviewers only report; a program refuses every edit they try. The repo's own review bot, if it has one, runs at the Gate. <span class="why">Why: sources <a href="#src-14">14</a>, <a href="#src-16">16</a>, <a href="#src-17">17</a>, <a href="#src-18">18</a>, <a href="#src-26">26</a></span></p>
|
||
</section>
|
||
|
||
<section class="page" id="findings">
|
||
<div class="eyebrow">What reviewers report</div>
|
||
<h2>Findings and rounds</h2>
|
||
<p class="lead">Every finding gets a colour. The colour decides what must happen.</p>
|
||
<div class="sev">
|
||
<div><i class="dot" style="background:var(--red)"></i><b>Red</b><span>Must fix. Never declined.</span></div>
|
||
<div><i class="dot" style="background:var(--yellow)"></i><b>Yellow</b><span>Fix, or decline with a written reason.</span></div>
|
||
<div><i class="dot" style="background:var(--green)"></i><b>Green</b><span>A nit. Fix, answer, decline with a reason, or file.</span></div>
|
||
<div><i class="dot" style="background:var(--grey)"></i><b>Question</b><span>Answered from the repo, or asked.</span></div>
|
||
</div>
|
||
|
||
<div class="diagram" role="img" aria-label="Round 1 reviews the whole change. Fixes. Round 2 reviews only the fixes. Fixes after round 2 merge once the gate passes. At most two rounds per reviewer.">
|
||
<svg viewBox="0 0 960 200">
|
||
<defs><marker id="ah5" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
<rect class="review" x="20" y="40" width="210" height="96" rx="8"/>
|
||
<text class="t" x="38" y="72">Round 1</text>
|
||
<text class="s" x="38" y="98">reviews the whole</text>
|
||
<text class="s" x="38" y="118">change</text>
|
||
<path class="edge" d="M230,88 L266,88" marker-end="url(#ah5)"/>
|
||
<rect class="worker" x="270" y="40" width="190" height="96" rx="8"/>
|
||
<text class="t" x="288" y="72">Fix</text>
|
||
<text class="s" x="288" y="98">one commit</text>
|
||
<text class="s" x="288" y="118">per round</text>
|
||
<path class="edge" d="M460,88 L496,88" marker-end="url(#ah5)"/>
|
||
<rect class="review" x="500" y="40" width="210" height="96" rx="8"/>
|
||
<text class="t" x="518" y="72">Round 2</text>
|
||
<text class="s" x="518" y="98">looks only at</text>
|
||
<text class="s" x="518" y="118">the fixes</text>
|
||
<path class="edge" d="M710,88 L746,88" marker-end="url(#ah5)"/>
|
||
<rect class="box" x="750" y="40" width="190" height="96" rx="8" style="stroke: var(--green); stroke-width:2"/>
|
||
<text class="t" x="768" y="72">Done</text>
|
||
<text class="s" x="768" y="98">last fixes merge</text>
|
||
<text class="s" x="768" y="118">once gate is green</text>
|
||
<rect x="20" y="160" width="920" height="30" rx="15" style="fill: var(--bg)"/>
|
||
<text class="lbl" x="480" y="180" text-anchor="middle" style="font-weight:700">At most 2 rounds per reviewer per chunk. A program blocks a third.</text>
|
||
</svg>
|
||
</div>
|
||
<ul class="tight">
|
||
<li><b>Outside this change?</b> The finding becomes a new item in <code>todo.md</code>, not a fix here.</li>
|
||
<li><b>Only red fixes re-run reviewers.</b> A fix for yellow, green or a question re-runs nothing.</li>
|
||
<li><b>A decline is written down</b>, in a code comment or in <code>docs/decisions.md</code>, so the next review does not raise it again.</li>
|
||
</ul>
|
||
<p class="why">Why: sources <a href="#src-15">15</a>, <a href="#src-16">16</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="readability">
|
||
<div class="eyebrow">Zoom in: B · Work → Readability</div>
|
||
<h2>The comprehension panel</h2>
|
||
<p class="lead">Simulated readers, from junior to architect, read the whole project and score it from 1 to 10.</p>
|
||
|
||
<div class="two">
|
||
<div class="diagram" role="img" aria-label="Bar chart of the four seats' overall scores in this setup's own latest scoring run: Junior 6, Mid-level 6.5, Senior 5.5, Architect 6. The target is 7.">
|
||
<svg viewBox="0 0 440 290" style="min-width:0">
|
||
<text class="lbl" x="0" y="16" style="font-weight:700">OVERALL SCORE PER READER</text>
|
||
<!-- x scale: 0..10 => 120..420 (30px per point) -->
|
||
<line class="grid" x1="120" y1="30" x2="120" y2="250"/>
|
||
<line class="grid" x1="270" y1="30" x2="270" y2="250"/>
|
||
<line class="grid" x1="420" y1="30" x2="420" y2="250"/>
|
||
<text class="lbl" x="120" y="270" text-anchor="middle">0</text>
|
||
<text class="lbl" x="270" y="270" text-anchor="middle">5</text>
|
||
<text class="lbl" x="420" y="270" text-anchor="middle">10</text>
|
||
<g><title>Junior: 6.0</title><text x="0" y="62">Junior</text><path class="bar" d="M120,46 L296,46 Q300,46 300,50 L300,68 Q300,72 296,72 L120,72 Z"/><text class="lbl" x="292" y="64" text-anchor="end" style="fill:var(--paper);font-weight:700">6.0</text></g>
|
||
<g><title>Mid-level: 6.5</title><text x="0" y="112">Mid-level</text><path class="bar" d="M120,96 L311,96 Q315,96 315,100 L315,118 Q315,122 311,122 L120,122 Z"/><text class="lbl" x="307" y="114" text-anchor="end" style="fill:var(--paper);font-weight:700">6.5</text></g>
|
||
<g><title>Senior: 5.5</title><text x="0" y="162">Senior</text><path class="bar" d="M120,146 L281,146 Q285,146 285,150 L285,168 Q285,172 281,172 L120,172 Z"/><text class="lbl" x="277" y="164" text-anchor="end" style="fill:var(--paper);font-weight:700">5.5</text></g>
|
||
<g><title>Architect: 6.0</title><text x="0" y="212">Architect</text><path class="bar" d="M120,196 L296,196 Q300,196 300,200 L300,218 Q300,222 296,222 L120,222 Z"/><text class="lbl" x="292" y="214" text-anchor="end" style="fill:var(--paper);font-weight:700">6.0</text></g>
|
||
<line class="floor" x1="330" y1="30" x2="330" y2="250"/>
|
||
<text x="336" y="44" style="font-size:13px;font-weight:700;fill:var(--red)">target 7.0</text>
|
||
</svg>
|
||
</div>
|
||
<div style="display:grid;gap:12px">
|
||
<h3>They score four things</h3>
|
||
<dl class="gloss">
|
||
<dt>Navigation</dt><dd>Can I find where things are?</dd>
|
||
<dt>Locality</dt><dd>Can I change one piece without holding the rest in my head?</dd>
|
||
<dt>Shape</dt><dd>Does each level have few parts, with names that tell the truth?</dd>
|
||
<dt>Self-sufficiency</dt><dd>Does the code explain itself?</dd>
|
||
</dl>
|
||
<p class="note">Real numbers: this setup's own latest scoring run (PR #397). Under 7.0, a refactor item is filed and ranked high.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Two ways to ask</h3>
|
||
<div class="roles" style="grid-template-columns:repeat(2,minmax(0,1fr))">
|
||
<div class="role review"><b>Scoring run</b><p>Four readers give a 1–10 score. Runs when a release's items run out, or when an item aims at the 7.0 target.</p></div>
|
||
<div class="role judge"><b>Paired ruling</b><p>Two readers compare before and after: better, same or worse? Runs in each release review.</p></div>
|
||
</div>
|
||
<p class="note">Readability blocks no merge. It steers the plan: code health ranks first among every project's goals.</p>
|
||
<p class="why">Why: sources <a href="#src-22">22</a>, <a href="#src-23">23</a>, <a href="#src-24">24</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="zoom-c">
|
||
<div class="eyebrow">Zoom in: C · Check</div>
|
||
<h2>C · Check, in detail</h2>
|
||
<p class="lead">A short AI run after every worker run. It decides what happens next, and when to ask the human.</p>
|
||
<div class="zoom3">
|
||
<div class="role judge"><b>What it reads</b>
|
||
<p>The end of the worker's log. The README's goals and audience. The project's <code>AGENTS.md</code> and <code>docs/decisions.md</code>. The setup's <code>CLAUDE.md</code>, <code>rules/</code> and review standards.</p></div>
|
||
<div class="role judge"><b>What it may answer</b>
|
||
<p>A question those files already answer. It quotes the answer word for word, and the worker goes on.</p>
|
||
<p>A quote not found word for word goes to the human instead.</p></div>
|
||
<div class="role judge"><b>Checks on its reply</b>
|
||
<p>A reply in the wrong shape, or with a made-up quote, counts as a failure and is retried. Three failures in a row stop the loop.</p></div>
|
||
</div>
|
||
<div class="tablewrap">
|
||
<table>
|
||
<thead><tr><th>Verdict</th><th>When</th><th>What happens next</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><span class="dot" style="display:inline-block;width:10px;height:10px;background:var(--green)"></span> Finished</td><td>The PR is merged, and every answer the human gave is written down.</td><td>Back to A. A new session, with a fresh, clean context.</td></tr>
|
||
<tr><td><span class="dot" style="display:inline-block;width:10px;height:10px;background:var(--grey)"></span> Unfinished</td><td>Work is left.</td><td>Back to B. The same session goes on, told what is left.</td></tr>
|
||
<tr><td><span class="dot" style="display:inline-block;width:10px;height:10px;background:var(--judge)"></span> Already settled</td><td>The worker asked something the records answer.</td><td>Back to B, with the quote.</td></tr>
|
||
<tr><td><span class="dot" style="display:inline-block;width:10px;height:10px;background:var(--you)"></span> Human's call</td><td>Only the human can decide.</td><td>The human types an answer, or opens <code>/talk</code>. Back to B with it.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<h3>Rules it follows</h3>
|
||
<ul class="tight">
|
||
<li><b>Answers are written down.</b> A chunk isn't finished until every answer the human typed is in the README, <code>AGENTS.md</code>, <code>docs/decisions.md</code>, <code>todo.md</code> or a code comment. The session is deleted at the end, so an unwritten answer would be lost.</li>
|
||
<li><b>The worker makes its own small choices.</b> A choice no rule reserves for the human, the worker makes and records. The judge doesn't interrupt for it.</li>
|
||
<li><b>No loops.</b> A question asked again after its answer goes to the human. So does the fourth answered question in one cycle, and the sixth unfinished verdict in a row.</li>
|
||
</ul>
|
||
<p class="why">Why: sources <a href="#src-3">3</a>, <a href="#src-4">4</a>, <a href="#src-26">26</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="plan">
|
||
<div class="eyebrow">What to do next</div>
|
||
<h2>The plan is one scored table</h2>
|
||
<p class="lead">Every item gets numbers. A program sorts them. The top item is next.</p>
|
||
<div class="tablewrap">
|
||
<table>
|
||
<thead><tr><th>ID</th><th>Release</th><th>Item</th><th>L</th><th>E</th><th>I</th><th>R</th><th>S</th><th>Moves</th><th>Score</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>281</td><td>0.7.0</td><td><b>Remove a merged chunk's worktree and branch and fast-forward the main checkout with one command.</b></td><td>3</td><td>2</td><td>3</td><td>6</td><td>3</td><td>1.4 by 2, 1.5 by 2</td><td>1.6</td></tr>
|
||
<tr><td>286</td><td>0.7.0</td><td><b>Lower the reading cost of the files a chunk reads most before its first commit.</b></td><td>3</td><td>2</td><td>2</td><td>5</td><td>5</td><td>1.4 by 4</td><td>1.0</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<p class="note">Two real rows from this setup's own <code>todo.md</code>.</p>
|
||
|
||
<div class="diagram" role="img" aria-label="L, E and I add up to risk R. L picks the worker's model, E + I the reviewers'. Moves and size S give the score, which picks the order.">
|
||
<svg viewBox="0 0 960 250">
|
||
<defs><marker id="ah6" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
<rect class="box" x="20" y="20" width="250" height="56" rx="6"/><text class="t" x="36" y="44">L · likelihood</text><text class="s" x="36" y="64">chance of a bug (1–4)</text>
|
||
<rect class="box" x="20" y="90" width="250" height="56" rx="6"/><text class="t" x="36" y="114">E · escape</text><text class="s" x="36" y="134">chance nobody catches it (1–3)</text>
|
||
<rect class="box" x="20" y="160" width="250" height="56" rx="6"/><text class="t" x="36" y="184">I · impact</text><text class="s" x="36" y="204">damage if it ships (1–5)</text>
|
||
<path class="edge" d="M270,48 L330,110" marker-end="url(#ah6)"/><path class="edge" d="M270,118 L326,118" marker-end="url(#ah6)"/><path class="edge" d="M270,188 L330,126" marker-end="url(#ah6)"/>
|
||
<rect class="judge" x="334" y="84" width="200" height="68" rx="6"/><text class="t" x="350" y="112">R · risk</text><text class="s" x="350" y="134">L + E + I − 2</text><text class="lbl" x="334" y="172">at least 5 if I is 4, 7 if I is 5</text>
|
||
<path class="edge" d="M534,118 L590,118" marker-end="url(#ah6)"/>
|
||
<rect class="worker" x="594" y="20" width="346" height="96" rx="6"/>
|
||
<text class="t" x="610" y="48">L and E + I pick the models</text>
|
||
<text class="s" x="610" y="72">L picks the worker's model.</text>
|
||
<text class="s" x="610" y="92">E + I pick the reviewers'. R above 5 ships alone.</text>
|
||
<rect class="you" x="594" y="136" width="346" height="96" rx="6"/>
|
||
<text class="t" x="610" y="164">Value picks the order</text>
|
||
<text class="s" x="610" y="188">Moves: which goals it helps, how much.</text>
|
||
<text class="s" x="610" y="208">Score = value ÷ (size + a fixed cost). Too low: deleted.</text>
|
||
</svg>
|
||
</div>
|
||
<ul class="tight">
|
||
<li><b>Chunk = next item + every item that can share its review.</b> Same release, same reviewers needed, nothing blocking.</li>
|
||
<li><b>Security findings rank first in their release.</b> Only open questions to the human rank above them.</li>
|
||
</ul>
|
||
<p class="why">Why: sources <a href="#src-9">9</a>, <a href="#src-10">10</a>, <a href="#src-11">11</a>, <a href="#src-12">12</a>, <a href="#src-13">13</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="models">
|
||
<div class="eyebrow">Right model for the job</div>
|
||
<h2>The model ladder</h2>
|
||
<p class="lead">Easy work runs on a cheaper model. Risky work gets a stronger one, and stronger reviewers.</p>
|
||
<div class="diagram" role="img" aria-label="Six rungs from cheapest to strongest: Sonnet 5.5 high, Opus 5.5 medium, high, xhigh, max, Fable 5.1 max.">
|
||
<svg viewBox="0 0 960 300">
|
||
<defs><marker id="ah7" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
<g>
|
||
<rect class="box" x="20" y="230" width="140" height="50" rx="5"/><text class="t" x="34" y="252" style="font-size:15px">Sonnet 5.5</text><text class="s" x="34" y="270">high</text>
|
||
<rect class="worker" x="174" y="192" width="140" height="88" rx="5"/><text class="t" x="188" y="214" style="font-size:15px">Opus 5.5</text><text class="s" x="188" y="232">medium</text>
|
||
<rect class="box" x="328" y="154" width="140" height="126" rx="5"/><text class="t" x="342" y="176" style="font-size:15px">Opus 5.5</text><text class="s" x="342" y="194">high</text>
|
||
<rect class="box" x="482" y="116" width="140" height="164" rx="5"/><text class="t" x="496" y="138" style="font-size:15px">Opus 5.5</text><text class="s" x="496" y="156">xhigh</text>
|
||
<rect class="box" x="636" y="78" width="140" height="202" rx="5"/><text class="t" x="650" y="100" style="font-size:15px">Opus 5.5</text><text class="s" x="650" y="118">max</text>
|
||
<rect class="box" x="790" y="40" width="150" height="240" rx="5"/><text class="t" x="804" y="62" style="font-size:15px">Fable 5.1</text><text class="s" x="804" y="80">max</text>
|
||
</g>
|
||
<text class="lbl" x="188" y="266" style="font-weight:700;fill:var(--worker)">project's rung</text>
|
||
<text class="lbl" x="20" y="24" style="font-weight:700">CHEAPER</text>
|
||
<text class="lbl" x="940" y="24" text-anchor="end" style="font-weight:700">STRONGER</text>
|
||
<path class="edge" d="M100,24 L860,24" marker-end="url(#ah7)"/>
|
||
</svg>
|
||
</div>
|
||
<div class="two">
|
||
<div>
|
||
<h3>How a rung is picked</h3>
|
||
<ul class="tight">
|
||
<li><b>Worker:</b> L 1–2 one rung down, L 3 the project's rung, L 4 one up.</li>
|
||
<li><b>Reviewers:</b> never below the project's rung or the worker's. E + I of 5 or more steps them up, one rung per point.</li>
|
||
<li><b>Readers and security:</b> always the project's rung. <b>The judge:</b> never below it.</li>
|
||
</ul>
|
||
</div>
|
||
<div>
|
||
<h3>When the worker climbs</h3>
|
||
<ul class="tight">
|
||
<li>The same test fails after two fixes.</li>
|
||
<li>A reviewer still finds a red problem in round 2.</li>
|
||
<li>A review rules the work below standard.</li>
|
||
</ul>
|
||
<p class="note">At most two rungs above the start without asking you. The ladder shown is for a project on Opus 5.5.</p>
|
||
</div>
|
||
</div>
|
||
<p class="why">Why: sources <a href="#src-25">25</a>, <a href="#src-26">26</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="release">
|
||
<div class="eyebrow">From chunks to a version</div>
|
||
<h2>A release</h2>
|
||
<p class="lead">Chunks fill a release. A final review cleans up. You cut it.</p>
|
||
<div class="diagram" role="img" aria-label="Plan the release with your approval, ship chunks one by one, run the release review, then you bump the version and publish.">
|
||
<svg viewBox="0 0 960 220">
|
||
<defs><marker id="ah8" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="head" d="M0,0 L10,5 L0,10 z"/></marker></defs>
|
||
<line x1="20" y1="110" x2="930" y2="110" class="edge" marker-end="url(#ah8)"/>
|
||
<circle cx="80" cy="110" r="14" class="f-you"/>
|
||
<text class="t" x="80" y="70" text-anchor="middle">Plan</text>
|
||
<text class="s" x="80" y="150" text-anchor="middle">you approve</text>
|
||
<text class="s" x="80" y="168" text-anchor="middle">the items</text>
|
||
<g>
|
||
<rect x="190" y="96" width="50" height="28" rx="5" class="worker"/>
|
||
<rect x="252" y="96" width="50" height="28" rx="5" class="worker"/>
|
||
<rect x="314" y="96" width="50" height="28" rx="5" class="worker"/>
|
||
<rect x="376" y="96" width="50" height="28" rx="5" class="worker"/>
|
||
<rect x="438" y="96" width="50" height="28" rx="5" class="worker"/>
|
||
</g>
|
||
<text class="t" x="339" y="70" text-anchor="middle">Chunks</text>
|
||
<text class="s" x="339" y="150" text-anchor="middle">one PR each, merged</text>
|
||
<rect x="550" y="90" width="150" height="40" rx="6" class="review"/>
|
||
<text class="t" x="625" y="70" text-anchor="middle">Release review</text>
|
||
<text class="s" x="625" y="150" text-anchor="middle">whole project,</text>
|
||
<text class="s" x="625" y="168" text-anchor="middle">fixes drift</text>
|
||
<circle cx="840" cy="110" r="18" class="f-you"/>
|
||
<text class="num" x="840" y="115" text-anchor="middle">v</text>
|
||
<text class="t" x="840" y="70" text-anchor="middle">You cut it</text>
|
||
<text class="s" x="840" y="150" text-anchor="middle">you bump the version</text>
|
||
<text class="s" x="840" y="168" text-anchor="middle">and publish</text>
|
||
</svg>
|
||
</div>
|
||
<div class="two">
|
||
<ul class="tight">
|
||
<li><b>Release review:</b> the architect and the principles auditor read the whole project, up to five rounds each, and fix what they find.</li>
|
||
<li>Then the readers compare before and after.</li>
|
||
</ul>
|
||
<ul class="tight">
|
||
<li><b>When the release is ready, the loop stops</b> and opens a session for you. It never starts the next release on its own.</li>
|
||
<li>Version number and publishing are always yours.</li>
|
||
</ul>
|
||
</div>
|
||
<p class="why">Why: sources <a href="#src-17">17</a></p>
|
||
</section>
|
||
|
||
<!-- ============ PART 2 ============ -->
|
||
|
||
<section class="page" id="talk">
|
||
<div class="part">Part 2 · In depth</div>
|
||
<h2>Talking to the loop</h2>
|
||
<p class="lead">You start it with one command. It interrupts you in its terminal and in a shared inbox.</p>
|
||
<pre class="term"><span class="d"># inside a project checkout whose README has ## Goals and ## Audience</span>
|
||
<span class="p">$</span> loop-claude "Do the next chunk."
|
||
<span class="d">… worker running: item 12 on claude-opus-5-5 at medium effort</span>
|
||
<span class="d">… judge: unfinished; resuming the same session</span>
|
||
<span class="d">… worker running</span>
|
||
<span class="q">? The worker asks: goal 2 says the CLI stays stable, but item 12 renames a flag.
|
||
Keep the old name, or change goal 2?</span>
|
||
<span class="p">answer ›</span> Keep the old name. Record it in docs/decisions.md.
|
||
<span class="d">… worker resumes with your answer</span>
|
||
<span class="g">✓ judge: finished · PR merged · next chunk starts in a fresh session</span></pre>
|
||
<p class="note">An example. Only a choice reserved for the human interrupts: a goal, a release's items and its cut, or the model ladder. <span class="why">Why: sources <a href="#src-4">4</a>, <a href="#src-28">28</a></span></p>
|
||
|
||
<div class="tablewrap">
|
||
<table>
|
||
<thead><tr><th>You type</th><th>What happens</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>a line of text</td><td>The worker resumes headless with your answer. It must record it before the chunk can finish.</td></tr>
|
||
<tr><td><code>/talk</code></td><td>Opens the worker's session for you (<code>claude --resume</code>). Read the diff, discuss, then exit.</td></tr>
|
||
<tr><td>Enter alone</td><td>Stops the loop. Rerunning resumes where it was.</td></tr>
|
||
<tr><td><code>loop-inbox</code></td><td>One screen for every loop on the machine: waiting questions, oldest first, and what each loop works on. Answer there or in the loop's own terminal; the first answer counts.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
<section class="page" id="stops">
|
||
<h2>When the loop stops by itself</h2>
|
||
<p class="lead">It stops only when it needs you, or something is broken.</p>
|
||
<div class="tablewrap">
|
||
<table>
|
||
<thead><tr><th>Reason</th><th>What to do</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>Release ready to cut</td><td>It opens a session for you. Cut the release.</td></tr>
|
||
<tr><td>6 unfinished verdicts in a row</td><td>Look at what is stuck; rerun to give it 6 more.</td></tr>
|
||
<tr><td>Worker or judge failed 3 times</td><td>Read the reason it prints. A usage limit is not a failure; it waits instead.</td></tr>
|
||
<tr><td>No goals in the README</td><td>Write <code>## Goals</code> and <code>## Audience</code> first. Nothing else runs until they exist.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="page" id="rails">
|
||
<h2>Guard rails</h2>
|
||
<p class="lead">Rules a program can check are enforced by a program, not by trust.</p>
|
||
<div class="tablewrap">
|
||
<table>
|
||
<thead><tr><th>Rail</th><th>What it does</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>Sandbox</td><td>Runs only on a dedicated machine, such as a VM, with no access to production. Claude Code skips permission prompts there.</td></tr>
|
||
<tr><td><code>rule-hook</code></td><td>Runs before each Agent, Bash, Edit, Read, Skill and Write call. Blocks e.g. multi-line commit messages, unpinned images, containers without memory limits, a third review round. Some rules allow a written override; the Overrides reviewer judges each one.</td></tr>
|
||
<tr><td><code>run-heavy</code></td><td>Heavy commands (builds, mutation tests, full test runs) wait for a shared slot: one per 4 CPUs on the machine.</td></tr>
|
||
<tr><td>Memory</td><td>Every container gets a memory limit. A new worker starts only while a quarter of the machine's memory is free.</td></tr>
|
||
<tr><td>Context</td><td>Each worker session, the <code>/talk</code> session and their subagents compact their context at about 170k tokens, keeping what the chunk still needs.</td></tr>
|
||
<tr><td>Archive</td><td>Every run's full log is saved. Every 20 cycles, figures from it may ask the human to change which model does what.</td></tr>
|
||
<tr><td>Main branch</td><td>Nothing is pushed to <code>main</code>. Every change merges through a PR whose gate passed.</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<h3>Measured, so it can improve</h3>
|
||
<ul class="tight">
|
||
<li><b>Interrupts per chunk:</b> should fall. Fewer questions to you.</li>
|
||
<li><b>Red and yellow findings per chunk:</b> should fall. Better first drafts.</li>
|
||
<li><b>Later fixes to merged code:</b> should not rise. Review is not missing things.</li>
|
||
<li><b>Tokens per chunk:</b> should fall, without more review rounds or unfinished verdicts.</li>
|
||
<li><b>Hours per chunk:</b> should fall, without more red findings.</li>
|
||
</ul>
|
||
<p class="why">Why: sources <a href="#src-5">5</a>, <a href="#src-27">27</a></p>
|
||
</section>
|
||
|
||
<section class="page" id="sources">
|
||
<h2>Why it works this way</h2>
|
||
<p class="lead">Each choice rests on research, a book, our own measurements, or trial and error. The numbers match the "Why" line at the bottom of each page.</p>
|
||
<h3 class="group">The loop</h3>
|
||
<div class="tablewrap"><table class="src-t"><colgroup><col style="width:4%"><col style="width:24%"><col style="width:72%"></colgroup><tbody>
|
||
<tr id="src-1"><td>1</td><td><b>A fresh, clean context every chunk</b></td><td><span class="kind x">Reasoning</span> Every turn re-sends the whole context, and compaction loses detail. The repo holds the memory between chunks, so a new chunk loses little.<br><span class="kind m">Own measurement</span> Simulated on 90 archived chunks, compacting at about 170k tokens would save about $78, 21% of the workers' spend. 36 full rewrites of a context after a cache gap cost $61, up to 785k tokens each. Within a chunk the session goes on: a fresh context for review would save $39, which compaction already saves as part of its $78.<br><span class="kind r">Research</span> Models use facts in the middle of a long context worst: Liu et al., "Lost in the Middle", TACL 2024. Answers degrade as input grows: Hong et al., "Context Rot", Chroma Research, 2025.</td></tr>
|
||
<tr id="src-2"><td>2</td><td><b>Several items per chunk; risky items alone</b></td><td><span class="kind m">Own measurement</span> Over 165 chunks, one item cost a median 1.30M tokens and two items 1.33M. Review costs about the same per chunk, so sharing it is cheap. At risk R 6 the median rose to 2.7M, and one in ten passed 8.8M, so R above 5 ships alone.</td></tr>
|
||
<tr id="src-3"><td>3</td><td><b>The worker makes its own small choices</b></td><td><span class="kind m">Own measurement</span> 92 of 255 interrupts already held the worker's recommendation. A chunk with an interrupt took a median 7.1 hours, against 0.44 hours without one. So the worker takes its recommendation on any choice no rule reserves for the human, and records it.</td></tr>
|
||
<tr id="src-4"><td>4</td><td><b>Every answer is written down</b></td><td><span class="kind x">Reasoning</span> A finished chunk's session is deleted. An answer kept nowhere else would be asked again in a later chunk. One goal of the setup is to never ask the same thing twice.</td></tr>
|
||
<tr id="src-5"><td>5</td><td><b>A program enforces every rule it can check</b></td><td><span class="kind r">Vendor docs</span> Anthropic's best-practices page calls <code>CLAUDE.md</code> advisory and hooks deterministic. So <code>rule-hook</code> blocks a rule-breaking tool call before it lands, in every project.<br><span class="kind m">Own measurement</span> The override marker's spelling was picked by a panel of three fresh readers, two to one.</td></tr>
|
||
<tr id="src-6"><td>6</td><td><b>Rules load by topic, not all at once</b></td><td><span class="kind r">Research</span> Anthropic's memory docs say a longer <code>CLAUDE.md</code> reduces adherence. IFScale (arXiv:2507.11538) measures adherence falling as the number of instructions grows. So each topic's rules load only when a matching file is touched.</td></tr>
|
||
<tr id="src-7"><td>7</td><td><b>The worker delegates only searches</b></td><td><span class="kind m">Own measurement</span> A subagent's report cost a median 8% of the worker's peak context. Search output (<code>sed</code>, <code>grep</code>) was 41% of its shell results. So searches go to subagents; edits stay with the worker, which would re-read a delegated diff anyway.</td></tr>
|
||
<tr id="src-8"><td>8</td><td><b>A limit on how much the worker reads at once</b></td><td><span class="kind m">Own measurement</span> Under "no more than 80 lines of a file, or 3,000 characters of output, at once", three test tasks read 45–60% less, at the same or lower cost, every task done as well.</td></tr>
|
||
</tbody></table></div>
|
||
</section>
|
||
|
||
<section class="page" id="sources-2">
|
||
<h3 class="group">The plan</h3>
|
||
<div class="tablewrap"><table class="src-t"><colgroup><col style="width:4%"><col style="width:24%"><col style="width:72%"></colgroup><tbody>
|
||
<tr id="src-9"><td>9</td><td><b>Goals with a signal and a counter-signal; achieve vs. maintain</b></td><td><span class="kind r">Research</span> Specific, hard goals beat vague ones: Locke & Latham 2002. A narrow goal makes people neglect the rest: Ordóñez et al. 2009, "Goals gone wild". A measure made a target gets gamed: Manheim & Garrabrant 2018 (arXiv:1803.04585). Goals that keep a state differ from goals that reach one: van Lamsweerde 2001 (KAOS).<br><span class="kind r">Research</span> Instruction files alone did not raise agents' success (arXiv:2602.11988). So each goal names a signal that shows it still decides cases.</td></tr>
|
||
<tr id="src-10"><td>10</td><td><b>Risk = L + E + I, each level about ×10</b></td><td><span class="kind r">Research</span> Multiplying 1–10 labels misleads: Stevens 1946; Cox 2008, <i>Risk Analysis</i>. Adding levels on a ×10 scale multiplies the real chance and cost: Kaplan & Garrick 1981. Impact is the worst case, not a sum: NIST; CVSS v4.</td></tr>
|
||
<tr id="src-11"><td>11</td><td><b>What makes L high: size, spread, something new, live config</b></td><td><span class="kind r">Research</span> Size predicts a defect best: Zeng et al. 2021, ISSTA. So does spread across files: Kamei et al. 2013. About 70% of Google's outages come from changes to a live system: Google SRE book. Complexity metrics add little once size is known: El Emam et al. 2001.</td></tr>
|
||
<tr id="src-12"><td>12</td><td><b>Order the plan by value over size</b></td><td><span class="kind b">Book</span> Doing the highest value per unit of work first minimises total waiting: Smith's rule, 1956; Reinertsen, <i>The Principles of Product Development Flow</i>, 2009 (WSJF).</td></tr>
|
||
<tr id="src-13"><td>13</td><td><b>Check every score against finished chunks</b></td><td><span class="kind r">Research</span> Compare guesses with outcomes: Brier 1950. Correct estimates against similar past cases: Flyvbjerg 2006. Anchor each level to real examples: Smith & Kendall 1963. People are overconfident: Hubbard, <i>How to Measure Anything</i>.<br><span class="kind m">Own measurement</span> <code>score-outcomes</code> shows each finished item's guessed scores beside what its chunk measured.</td></tr>
|
||
</tbody></table></div>
|
||
</section>
|
||
|
||
<section class="page" id="sources-3">
|
||
<h3 class="group">Review</h3>
|
||
<div class="tablewrap"><table class="src-t"><colgroup><col style="width:4%"><col style="width:24%"><col style="width:72%"></colgroup><tbody>
|
||
<tr id="src-14"><td>14</td><td><b>Narrow, separate reviewers</b></td><td><span class="kind x">Experience</span> Early on, a reviewer with too broad a responsibility found fewer issues.<br><span class="kind m">Own measurement</span> On 2026-11-09, merged reviewers were replayed on archived rounds. Stability, product owner and prose as one reviewer cost half as much, but found 15 of 34 prose findings again, against 22–23 for the prose reviewer. Architect and principles auditor as one found 5 of 17 principles findings, against 10, and lost both red ones. Even stability and product owner alone, as one, found 4–5 of 16 product-owner findings, against 7–10. In every merge, one absorbed pass lost findings, at a third to half the cost. Method and figures: <code>reviewer-merge-trials/</code> in the setup's repo. Merging reviewers that check the same kind of thing did hold up: one principles auditor found as much as several.</td></tr>
|
||
<tr id="src-15"><td>15</td><td><b>At most two rounds per reviewer</b></td><td><span class="kind m">Own measurement</span> Since 2026-10-21, across all projects: round 1 ran 357 times and found 59 red findings. Round 2 ran about 200 times and found 12, mostly in round 1's fixes. Rounds 3 and later ran about 110 times and found none, for about $125. Asks for more rounds were 24 of 59 interrupts.</td></tr>
|
||
<tr id="src-16"><td>16</td><td><b>Reviewers report only real problems</b></td><td><span class="kind r">Vendor docs</span> Anthropic's Claude Code best practices: "A reviewer prompted to find gaps will usually report some, even when the work is sound."<br><span class="kind m">Own measurement</span> 320 of the setup repo's first 876 commits, by 2026-10-13, answered a review round. So stability and product owner report only defects, broken requirements or broken principles.</td></tr>
|
||
<tr id="src-17"><td>17</td><td><b>Architect and principles only in the release review</b></td><td><span class="kind m">Own measurement</span> The principles audit was the costliest reviewer after the worker, and filed findings unrelated to the chunk. Once a release, over the whole project, catches the same drift.</td></tr>
|
||
<tr id="src-18"><td>18</td><td><b>Security: <code>/security-review</code>, not a hand-written reviewer</b></td><td><span class="kind x">Reasoning</span> Its tuned exclusion list and confidence floor would be reproduced worse by hand.<br><span class="kind m">Own measurement</span> Run beside the deep scan, it returned a near-identical report, so the deep scan replaces it when both would run.</td></tr>
|
||
<tr id="src-19"><td>19</td><td><b>Mutation testing instead of coverage</b></td><td><span class="kind r">Research</span> Coverage barely predicts fault detection: Inozemtseva & Holmes, ICSE 2014. Surviving mutants do predict real faults: Just et al., FSE 2014. Google runs mutation testing in code review: Petrović et al., arXiv:2102.11378.</td></tr>
|
||
<tr id="src-20"><td>20</td><td><b>Test first, with expected values from the item</b></td><td><span class="kind r">Research</span> Tests that copy the code's current output pass on a bug: Charoosaei et al., arXiv:2610.11835 (preprint); Mathews & Nagappan, arXiv:2412.14137. Agents add mocks more often than people: Hora & Robbes, MSR 2026.<br><span class="kind b">Book</span> <i>Software Engineering at Google</i>, ch. 11, 12, 14; Beck, "Test Desiderata"; Khorikov, <i>Unit Testing</i>, ch. 4.</td></tr>
|
||
<tr id="src-21"><td>21</td><td><b>The worker reads a principle only when a finding names it</b></td><td><span class="kind m">Own measurement</span> Over five chunks on each side of the change, review rounds per reviewer fell from 2.26 to 1.52.</td></tr>
|
||
</tbody></table></div>
|
||
</section>
|
||
|
||
<section class="page" id="sources-4">
|
||
<h3 class="group">Readability</h3>
|
||
<div class="tablewrap"><table class="src-t"><colgroup><col style="width:4%"><col style="width:24%"><col style="width:72%"></colgroup><tbody>
|
||
<tr id="src-22"><td>22</td><td><b>Code that fits in your head: about seven things per level</b></td><td><span class="kind b">Book</span> Seemann, <i>Code That Fits in Your Head</i>, 2021. Ousterhout, <i>A Philosophy of Software Design</i> (deep modules).<br><span class="kind r">Research</span> Working memory holds about four chunks: Cowan 2001. A list found by name is no memory limit: Nielsen Norman Group. No study supports a fixed limit on function length: Jones 2023.</td></tr>
|
||
<tr id="src-23"><td>23</td><td><b>Reader panel: before-and-after rulings, never blocking</b></td><td><span class="kind m">Own measurement</span> Two independent four-reader runs moved up to 0.4 on near-identical code (PR #224). Readers comparing before and after should cancel that noise. A check of that is still pending: it needs 10 commits each scored twice.<br><span class="kind r">Research</span> No published study validates simulated reader panels yet. So the panel steers the plan and blocks no merge.</td></tr>
|
||
<tr id="src-24"><td>24</td><td><b>Reading cost: the median of five chunks</b></td><td><span class="kind m">Own measurement</span> One chunk read 2.99M tokens before its first commit, against a typical 80k–370k. An average let that one chunk decide the trend alone, so a rise is the last five chunks' median above the five before.</td></tr>
|
||
</tbody></table></div>
|
||
<h3 class="group">Models</h3>
|
||
<div class="tablewrap"><table class="src-t"><colgroup><col style="width:4%"><col style="width:24%"><col style="width:72%"></colgroup><tbody>
|
||
<tr id="src-25"><td>25</td><td><b>The model ladder, and no Haiku</b></td><td><span class="kind r">Benchmark</span> The rungs follow the Artificial Analysis Intelligence Index, except Fable 5.1 at max: the index scores it below Opus 5.5 at high, and the human put it on top for the hardest tasks.<br><span class="kind m">Own measurement</span> A chunk on Haiku 5.5 ran 2 h 17 min and wrote 3.1M tokens. The chunk before it, on Sonnet 5.5, took 29 min and 111k. Chunks on Haiku took 7.8 extra review rounds, against 2.8 on Sonnet. So Haiku left the ladder.</td></tr>
|
||
<tr id="src-26"><td>26</td><td><b>Judge and reviewers never run below the project's model</b></td><td><span class="kind m">Own measurement</span> A replay of 39 judge verdicts, 31 of which the reference judge reproduced: on those 31, Opus 5.5 at medium missed none, and Sonnet 5.5 mislabelled 3 interrupts. A replay of review rounds: Sonnet 5.5 missed 44–55% of what the project's model found.</td></tr>
|
||
</tbody></table></div>
|
||
<h3 class="group">The machine</h3>
|
||
<div class="tablewrap"><table class="src-t"><colgroup><col style="width:4%"><col style="width:24%"><col style="width:72%"></colgroup><tbody>
|
||
<tr id="src-27"><td>27</td><td><b>Shared heavy slots and memory limits</b></td><td><span class="kind x">Experience</span> On 2026-10-22 an 8-CPU, 16 GiB machine thrashed for hours: four to six loops ran mutation tests, builds and e2e tests at once. The next day, with 7.6 GiB, it hung until a hard reset, from containers with no memory limit. So heavy commands wait for a slot, one per 4 CPUs, and every container gets a limit.</td></tr>
|
||
<tr id="src-28"><td>28</td><td><b>Names and syntax picked by the people who use them</b></td><td><span class="kind m">Own measurement</span> A panel of three readers, seated as the users, picks each new name or spelling. It picked <code>loop-inbox</code> 3–0.</td></tr>
|
||
</tbody></table></div>
|
||
<p class="note">Most measurements come from loop-claude's archive of every run, across all projects; others from git history, review replays, the readability history and two machine incidents. The setup's own <code>docs/decisions.md</code> and <code>docs/scoring-and-goals-research.md</code> hold the full reasoning.</p>
|
||
</section>
|
||
|
||
<section class="page" id="words">
|
||
<h2>Words used here</h2>
|
||
<dl class="gloss">
|
||
<dt>Chunk</dt><dd>One unit of work, shipped as one pull request. One or more plan items.</dd>
|
||
<dt>Cycle</dt><dd>One worker run plus the judge's verdict on it.</dd>
|
||
<dt>Item</dt><dd>One row of <code>todo.md</code>, with a bold one-sentence goal and its scores.</dd>
|
||
<dt>Worker</dt><dd>The headless Claude Code session that does the chunk.</dd>
|
||
<dt>Judge</dt><dd>The short AI run that reads each worker run and gives a verdict.</dd>
|
||
<dt>Interrupt</dt><dd>A question only you can answer. Shown in the terminal and in <code>loop-inbox</code>.</dd>
|
||
<dt>Pass</dt><dd>One kind of review, such as Stability. It runs in rounds.</dd>
|
||
<dt>Round</dt><dd>One review by one reviewer. At most two per pass per chunk.</dd>
|
||
<dt>Gate</dt><dd>The checks a PR must pass to merge: tests, CI, plan format.</dd>
|
||
<dt>Rung</dt><dd>A model at an effort level, such as "Opus 5.5 at high".</dd>
|
||
<dt>Premises</dt><dd>The README's <code>## Goals</code> and <code>## Audience</code>. Nothing runs without them.</dd>
|
||
<dt>Release review</dt><dd>A release's last chunk: whole-project review before you cut it.</dd>
|
||
<dt>Seat</dt><dd>One simulated reader on the comprehension panel.</dd>
|
||
<dt>Worktree</dt><dd>A separate git checkout per chunk, so your main checkout stays untouched.</dd>
|
||
</dl>
|
||
|
||
<h3>The two commands you use</h3>
|
||
<pre class="term"><span class="p">$</span> loop-claude "Do the next chunk." <span class="d"># start the loop in a project</span>
|
||
<span class="p">$</span> loop-inbox <span class="d"># answer every loop's questions</span></pre>
|
||
</section>
|
||
|
||
</main>
|