architect-loop

architect-loop

A Claude Code skill for running a real engineering project on a fraction of the tokens: not by making prompts terser, but by changing who does the work. The lead model (ideally Opus) never touches the mechanical work at all: it writes specs, dispatches Sonnet subagents to build, Haiku subagents to verify, reviews the riskiest hunks of the diff, and merges. Everything expensive about a long agentic session (re-reading a growing conversation every turn, watching test suites scroll by, holding whole files in context "just in case") gets replaced with cold-context dispatches and a verification bar that treats a subagent's report as a claim, not a fact.

One loop iteration end to end: spec, build dispatch, independent verify, merge.

Real numbers

This isn't a benchmark harness; it's a loop that ran a real production codebase (a FastAPI + Next.js SaaS backend/frontend, anonymized here) for about three days of continuous operation. No cherry-picking: this is one continuous engagement, described honestly, including the parts that went wrong before this loop existed to catch them.

Metric	Value	Note
Features shipped	7 product features, a retrieval/groundedness eval harness, a security-hardened web-research provider (SSRF-safe fetch + extraction), a full UI functionality audit with fixes, and a complete CD pipeline (build → GHCR publish → SSH deploy → health-check probe)	one continuous ~3-day engagement
Live test suite	953 → 1285, all green at every merge point	the bar only ever moved up, never down
Bugs caught before merge	3: a cache-invalidation bug; a 3-way circular import that crashed every fresh worker process while local tests stayed green (the stale-worker blind spot, see references/anti-patterns.md); an RBAC gap that let one persona reach a view it shouldn't have	caught by the verification chain, not after
Usage-cap kills / clean resumes	5 / 5	every resume picked back up from committed work + worktree WIP, zero rework, using the RESUME-after-cap-kill pattern in references/dispatch-templates.md
Duration	~3 days of continuous operation	one engagement, not an average across several

Where the savings actually come from

The loop's pitch isn't "fewer tokens." It's "the same or more total tokens, spent by cheaper models in contexts that don't compound." Two effects stack to produce the actual saving.

a. The context-compounding effect

A lead session's conversation grows every turn, and the model re-reads the entire conversation on every turn, not just the new part. A cold-context dispatch, by contrast, pays a roughly-fixed few-KB prompt cost with nothing behind it to re-read.

Illustrative, not measured: say a unit of work takes 10 back-and-forth turns either way, and each turn adds roughly C tokens of new context (tool output, reasoning, edits). Working it inline, the model re-reads the accumulated conversation every turn, so total tokens processed ≈ C + 2C + 3C + … + 10C = 55C (a triangular sum, C·n(n+1)/2 for n=10). Dispatched, the same 10 turns run in a cold context the lead never re-reads; the lead only pays for the initial spec and the final report, roughly 2C regardless of how many turns the dispatch itself takes internally. That's a

25x gap from compounding alone, before the per-token price difference between models is even applied. The exact multiplier depends on turn count and growth rate (real iterations in this engagement ran fewer, larger turns rather than many small ones), but the shape of the effect (cost that doesn't compound vs. cost that does) is the mechanism, not the specific number.

b. The price-tier effect

Per-token prices differ sharply across the three tiers. Current published rates (Anthropic pricing page, cited below, as of July 2026):

Tier (role in the loop)	Model	Input $/MTok	Output $/MTok
Architect	Opus (current-gen, e.g. 4.5–4.8)	$5	$25
Builder	Sonnet 5 (introductory, through Aug 31, 2026)	$2	$10
Verifier	Haiku 4.5	$1	$5

Ratios at today's rates: a builder (Sonnet) token costs ~2.5× less than an architect (Opus) token, input or output; a verifier (Haiku) token costs ~5× less than an architect token, and ~2× less than a builder token. Worth flagging honestly: Sonnet 5's pricing is introductory and reverts to $3/$15 per MTok on September 1, 2026, which narrows the Opus:Sonnet ratio to ~1.67×. The Haiku:Opus ratio (~5×) is unaffected. Source: platform.claude.com/docs/en/about-claude/pricing (the current location of what redirects from docs.claude.com/.../pricing), checked July 2026. Verify against the live page before quoting these numbers later, since Anthropic revises pricing over time.

c. Anatomy of one loop iteration (observed)

These are observed ranges from the real engagement in "Real numbers" above, not a synthetic benchmark. They vary iteration to iteration, and the spread reflects that, not measurement error.

Role	Model	Tokens per iteration (observed)
Builder	Sonnet	~200K – 480K per build dispatch
Verifier	Haiku	~64K – 106K per independent verification pass
Architect	Opus	low tens of thousands: spec writing, reading dispatch reports, targeted diff review of the riskiest hunks, merge commands, and its own share of re-reading the growing lead conversation

Do the arithmetic on the ranges rather than a single made-up number: at the low end of dispatch volume (200K + 64K = 264K Sonnet+Haiku tokens), the architect's own tokens would need to stay under ~29K for dispatched tokens to exceed 90% of the iteration's total, squarely inside "low tens of thousands." At the high end (480K + 106K = 586K), the architect could spend up to ~65K tokens and dispatched tokens would still be >90% of the total. Under either end of the observed range, the majority of an iteration's tokens were never architect tokens at all.

The honest punchline: the loop does not reduce total tokens spent; running three contexts instead of one can mean more raw text processed for the same unit of work. What changes is where those tokens land: roughly 90%+ of the volume moves to Sonnet and Haiku, priced ~2–5× cheaper per token than Opus at today's rates (narrowing toward ~1.7× for Sonnet after its introductory window closes), and those tokens sit in cold contexts that never compound the way a growing lead conversation does. Two independent effects stacking (cheaper tokens, non-compounding tokens) is where the real bill shrinks, not a reduction in total volume.

d. The effort dial (and the trap that quietly disables it)

Model tier is not the only cost dial. Effort (low · medium · high · xhigh · max) governs how much reasoning a model spends per turn, and it is independent of which model you picked.

The trap: effort defaults to inheriting the session's level. An architect running Opus at high hands that same high to every Sonnet build dispatch. You get the cheaper model and the expensive effort: the price-tier saving in (b) lands, the effort saving silently does not.

Worse, it is not fixable from the dispatch call. The Agent tool accepts a per-invocation model parameter but has no effort parameter. Effort is settable only in agent frontmatter. That is why this package ships agents/ (three definitions that pin model and effort per role) rather than prompt templates alone. Installing them is what turns the effort column in SKILL.md section 2 from documentation into behavior.

The principle worth carrying beyond this repo: set effort by the cognitive demand of the task, not the price of the model. Executing a precise spec is medium work even on a strong model; a security sweep is high work even on a cheap one. Cheap-model-plus-high-effort is a legitimate and underused combination: this package's auditor agent is exactly that, Sonnet at high.

Unlike (a), (b), and (c), this section reports a mechanism, not a measurement. The engagement in "Real numbers" predates these agent definitions, so none of the figures above isolate an effort-tuning effect, and no claim here should be read as one.

Read your own receipts

The "Real numbers" table above is one engagement; scripts/cost-report.py prints yours. It reads the transcripts Claude Code already keeps on your machine and shows where your tokens actually went, split by role.

python scripts/cost-report.py [--projects-dir PATH] [--project SLUG] [--days N] [--by role|model|session] [--prices FILE] [--json]

Defaults: --projects-dir is ~/.claude/projects (expanded per-user, so it works on Windows too), --days 30, --by role. Roles are mapped from the model id string: anything containing "opus" or "fable" counts as architect, "sonnet" as builder, "haiku" as verifier, and everything else as other.

Cost estimates use built-in default prices per MTok: opus $5 input / $25 output, sonnet $3 / $15, haiku $1 / $5, with fable priced as opus. Cache-read input tokens are priced at 10 percent of that model's input rate, and cache-creation tokens at 125 percent of the input rate. Override any of this with --prices pointing at a JSON file shaped {"model-substring": {"input": x, "output": y}}.

The default output is an aligned plain-text table with one row per role (or per model or per session, depending on --by): the role, the models seen, input tokens, output tokens, cache-read tokens, and estimated cost in USD. Then a totals row, then a receipt block comparing the actual estimate against what the same tokens would have cost at architect rates. --json prints the same data as a JSON object instead.

Illustrative sample (made-up numbers; the shape and columns are accurate):

role       models seen        input      output   cache-read  est. cost
---------  -----------------  ---------  -------  ----------  ---------
architect  claude-opus-4-5      412,380   88,214   1,204,551      $4.87
builder    claude-sonnet-4-5  2,981,004  401,220   3,310,876     $15.95
verifier   claude-haiku-4-5     644,310   71,882     512,004      $1.05
other      -                     12,110    2,006           0      $0.11
---------  -----------------  ---------  -------  ----------  ---------
total                         4,049,804  563,322   5,027,431     $21.98

If every token above had run at architect rates: $36.85.
Actual estimate: $21.98. Difference: $14.87 (40 percent).

One honest caveat, and the script prints it too: these are estimates derived from your local transcripts, not billing data. Treat the shape as real and the cents as approximate.

How it works

sequenceDiagram
    participant O as Opus (architect)
    participant S as Sonnet (builder)
    participant H as Haiku (verifier)

    O->>O: Write spec: worktree, decisions,<br/>known facts, verify bar
    O->>S: Dispatch (build)
    S->>S: Build in worktree, commit as it goes
    S-->>O: Report: commits, gates, numbers
    O->>H: Dispatch (independent verify)
    H->>H: Run checklist vs. exact baselines
    H-->>O: Findings (claims, not facts)
    alt findings found
        O->>S: Dispatch (targeted fix)
        S-->>O: Fix report
        O->>H: Re-verify
        H-->>O: Clean report
    end
    O->>O: Review riskiest hunks only
    O->>O: Merge, push, watch CI (background),<br/>restart stateful services, update memory

The architect never runs the test suite inline, never reads a diff line by line, and never reads a subagent's transcript: it reads reports and spot-verifies one or two load-bearing claims with a cheap direct check. See SKILL.md for the full loop and references/ for the depth: dispatch templates you can copy-paste and fill in, the usage-cap parking runbook, the verification bar, a catalog of anti-patterns with counters, a project-facts template so dispatches carry facts instead of agents rediscovering them, and the standing orders, the judgement discipline (two-route number verification, certainty labeling, self-attack, a pre-send final gate) that governs the quality of what the lead itself produces.

Install

npx github:masood-ahmed-k/architect-loop

This installs two things into two different roots, because Claude Code loads them from two different places:

What	Where	Why it's needed
The skill	~/.claude/skills/architect-loop	The operating discipline, loaded by /architect-loop
3 agent definitions	~/.claude/agents/	The only place effort can be set; see (d) above

The skill root brings references/ and scripts/ along with it, including scripts/cost-report.py from "Read your own receipts" above.

Cross-platform (Windows, macOS, Linux), no npm-registry publish required, no dependencies (pure Node stdlib: fs, path, os), no network calls beyond fetching this repo, no telemetry. Re-running it updates both in place. The agent files are all named architect-loop-*.md, so a re-install overwrites only its own files, never an agent you wrote.

npx github:masood-ahmed-k/architect-loop --target ./skill/dir --agents-target ./agents/dir
npx github:masood-ahmed-k/architect-loop --no-agents   # skill only, not recommended

Version-pinned install

The bare github:... form installs whatever main currently is. To get a reproducible install of a tagged release instead, pin the tag (keep the quotes; # needs them in some shells):

npx "github:masood-ahmed-k/architect-loop#v1.0.2"

Tags are cut at commits that passed a live end-to-end install test, so the pinned form is the one to use in setup scripts and docs you hand to others. Available tags are listed under this repo's releases/tags.

Alternative: the skills CLI

This repo's layout (a SKILL.md at the repo root with valid name and description frontmatter) is directly compatible with vercel-labs/skills, the open agent-skills CLI (its own docs describe root-level SKILL.md as one of the locations it discovers automatically). Verified live against this repo: a real skills add run lands the full repo (references/, scripts/, and agents/ included) in the skill directory, no changes needed:

npx skills add masood-ahmed-k/architect-loop

That CLI targets 70+ agents beyond Claude Code and adds its own scope/agent-targeting flags; see its docs for those. Two differences worth knowing:

• It lands everything in one root, not two. The CLI copies the whole repo (agents/ included) into the skill directory, but Claude Code loads agent definitions only from ~/.claude/agents/. The skill handles this itself: on first invocation, section 0 self-installs the agent files from its own agents/ folder (they take effect the next session). To have them active immediately instead, copy them now:

  cp ~/.claude/skills/architect-loop/agents/*.md ~/.claude/agents/
  

• skills collects anonymous usage telemetry (disable with DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1); this repo's own npx github:... installer makes no network call beyond fetching the repo and never phones home.

Manual (git clone)

git clone https://github.com/masood-ahmed-k/architect-loop.git
cp -r architect-loop ~/.claude/skills/architect-loop
mkdir -p ~/.claude/agents && cp architect-loop/agents/*.md ~/.claude/agents/

Note the second line: copying the repo into skills/ alone is not a complete install. The agents must land in ~/.claude/agents/ or the effort settings never take effect. The clone also carries scripts/ in full, so scripts/cost-report.py and scripts/quiet.py land with it.

House style, machine-enforced

This repo bans two characters outright: the em dash and the section sign, in code, comments, docs, commit messages, everywhere. The skill passes the same ban to every agent it dispatches, so it holds in conversation, code, docs, and generated deliverables alike. And it isn't on the honor system: CI's style-gate job fails any commit that reintroduces either character.

After installing

At the start of a lead/architect session (Opus or your strongest available model):

/architect-loop

That loads SKILL.md into context. It's deliberately short: depth lives in references/, loaded only when that specific topic comes up, so invoking the skill doesn't itself burn a large chunk of your budget.

Confirm the agents resolved: you should see architect-loop-builder, architect-loop-verifier, and architect-loop-auditor in the available agent types. If they are missing, the agent files did not land in ~/.claude/agents/ and every dispatch will silently inherit your architect session's effort level.

Per-project setup

Copy references/project-facts.md into your own repo (suggested path: docs/PROJECT-FACTS.md) and fill it in once: paths, ports, environment variables, service topology, current baseline numbers, and known gotchas. This is what makes dispatch prompts carry facts instead of agents spending their own budget rediscovering them, and it's the single highest-leverage file in this whole package. An architect session that skips it will still work; it will just cost more per dispatch.

You don't have to write it from scratch. The first time the skill runs in a repo that has no project-facts file, the architect offers, once, to dispatch the read-only auditor to draft docs/PROJECT-FACTS.md for you. Everything the auditor could not confirm from the repo itself is labeled Unverified, so your job is to correct a draft, not compose from a blank page.

The project-facts file also carries a Dispatch effort section. Fill it in and the architect applies it silently; leave it blank and the architect asks you once: a single question at session start, then never again for that project. It is deliberately the only thing this skill asks you, because it is the only setting that cannot be read off the repo.

Change the levels any time:

python scripts/configure-agents.py --show
python scripts/configure-agents.py --builder medium --verifier low
python scripts/configure-agents.py --auditor xhigh --auditor-model opus

That edits the installed agent frontmatter in ~/.claude/agents/, which is the only place effort can live. It sets models too, since they are independent dials. It preserves existing line endings and is idempotent, so re-running it is free.

Copy references/session-state.md into your own repo too (suggested path: docs/SESSION-STATE.md). Unlike project-facts, the architect maintains this one for you: it gets rewritten at every merge and at every usage-cap park. A fresh session resumes from a single file read instead of re-deriving branch state, in-flight work, and baseline numbers. This is the fix for cross-session amnesia.

Also copy scripts/quiet.py somewhere on your path (or into the repo's own scripts/) if you want compressed local test/build output; see the script's docstring for usage. scripts/cost-report.py needs no per-project setup at all; it reads the transcript directory directly (see "Read your own receipts" above).

When NOT to use this

• Tiny tasks. A one-line fix or a single-file change doesn't need a spec, a worktree, and a three-model relay: just make the edit. The loop pays for itself on multi-step work, not on everything.
• No-subagent environments. If your setup can't dispatch background agents at all, the core mechanic (cold-context delegation) isn't available. What still transfers: the token mechanics in SKILL.md section 3 (targeted reads, output compression, batching, background long tasks), the verification bar, and the anti-patterns catalog, all useful even working solo in one context.
• Solo exploratory/throwaway work. Prototyping, spike code, "let me see if this is even possible" work: the overhead of specs and verification bars is wasted on work you might delete in an hour.
• When you don't trust the lead model to write a precise spec. The entire loop depends on step 1 (a spec precise enough that a cold-context agent doesn't have to guess). If the spec is vague, the dispatch will produce something plausible-looking but wrong, and you'll pay for the redo. Garbage spec in, garbage build out, same as any delegation.

How this differs

Two existing tools cover related but distinct ground. Worth knowing both; neither does what this does, and this doesn't try to do what they do.

caveman compresses an agent's output: it rewrites responses to be terser (sentence fragments, dropped filler) while keeping code and commands byte-exact, with measured ~65% output-token reduction across many agents. It's a prompt-level technique: one model, one context, talking less. It's honest that input and reasoning tokens are untouched, so net session savings vary.

token-savior attacks a different layer: symbol-indexed code navigation instead of full-file reads, persistent cross-session memory, and a large library of Bash-output compactors (git, test runners, cloud CLIs). It's an MCP server with real benchmark numbers, a big win on single-context token efficiency, and its Bash compaction and targeted-read philosophy overlap with pieces of SKILL.md section 3.

architect-loop doesn't compress a single context; it changes how many contexts there are and who's expensive in each. The tools above optimize "one model doing the whole job, using fewer tokens per turn." This one says the lead model shouldn't be doing most of the job in the first place: hand mechanical work to a cold-context Sonnet dispatch, hand checklist verification to a cold-context Haiku dispatch, and reserve the expensive, ever-growing lead context for judgement calls only. It also ships something neither of the above does: a verification discipline (skips are findings, sub-green needs a proven cause, verify the verifier) and a failure-mode runbook (cap-kill parking, stale-worker blind spot, drift guards) distilled from operating this loop on a real production project. Not a token-shaving trick, an operating model. You could reasonably run all three together: caveman/token-savior-style compression inside each dispatch this loop creates.

FAQ

Does this work without Opus as the lead? Yes, with a caveat: the loop's value comes from the cost asymmetry between the lead and the dispatched models. Any capable model can be the architect; the bigger the gap between its cost/turn and Sonnet/Haiku's, the more this loop saves. If your lead and builder are the same model and price, you still get the verification bar and anti-patterns catalog, but the core "spend cold tokens on mechanical work" saving shrinks.

Does this work on the API (pay-per-token) instead of a subscription? Yes; arguably it's easier to see the win there, since every avoided lead token and every dispatched-to-a-cheaper-model token is a line item you can total up directly. The mechanics don't change; only the units the savings are measured in do.

Do I need all three model tiers? No. Two tiers (a lead + one dispatch model doing both building and verification) still captures most of the benefit: the biggest single win is not doing mechanical work in the lead context at all, which you get with two tiers. Three tiers adds the false-positive discipline of a cheap, fast, independent verifier.

What if my agent runtime doesn't support background dispatch? Then run the loop's spec-writing and diff-review discipline manually and sequentially: write the same precise spec, execute it yourself in a clean context (a new chat/session rather than the same growing one), and apply the same verification bar before merging. You lose the parallelism and the cold-context cost saving, but the "spec precisely, verify honestly, never trust a claim you haven't checked" discipline still holds.

Is this specific to Python/JS backends? No. The loop, the verification bar, and the anti-patterns are stack-agnostic. project-facts.md and quiet.py are the only stack-flavored pieces, and both are templates meant to be adapted, not used verbatim.

Why is SKILL.md so short? Because the skill itself has to practice what it preaches. A skill file that's expensive to load defeats its own purpose. Depth lives in references/, read on demand when that specific topic (a dispatch, a cap kill, a verification question) actually comes up.

License

MIT. See LICENSE.