hand an agent a spec, come again to examined work

I had a dream. I’d hand an agent a spec, shut the laptop computer, make a sandwich, and are available again to completed, examined, dedicated work.

Here’s what truly occurred. I handed over the spec. I made the sandwich. I got here again. The agent had written one paragraph and was asking, very politely, whether or not I authorized part 1 of the design.

I authorized it. I sat down. I waited.

Section 2. Approve? Yes. Section 3. Approve? Yes. The spec? Yes. The plan? Yes, clearly, it is the plan I simply watched you write. And how would I just like the plan executed? However is quickest, please, I encourage you.

Then it began constructing. One activity. Then a assessment of that activity. Then a repair for the assessment. Then a re-review of the repair. Then the subsequent activity. I watched a progress log scroll previous like a prepare at a degree crossing: no stopping it, no getting previous it, and no thought what number of carriages had been left.

I’d refresh the terminal. Still on activity 3. I’d reply an e mail. Still on activity 3. I’d begin a second sandwich purely to have one thing to do with my arms. Task 4, below assessment.

The sandwiches had been excellent. The software program did not exist but. And the worst half wasn’t the time. It was that I could not depart. Every time I walked away, I got here again to a query that had been sitting there for twenty minutes, ready for me to sort “sure.”

I did not need a collaborator that wanted me each 4 minutes. I needed a contractor. Here’s the spec, here is the important thing, name me when it is completed.

So I constructed superlite: a Claude Code plugin that plans a construct, splits it into duties that may run facet by facet, arms every one to the most affordable agent that may do it properly, checks the seams between them, and evaluations the outcome. Then it leaves you a tidy record of each resolution it made whilst you had been busy with the sandwich.

This put up covers why it exists, the way it works, and easy methods to use it. The benchmarks are there to point out I’m not simply saying it is quick as a result of I wrote it.

Why I constructed it

First, a disclaimer, as a result of I like this venture and don’t need indignant emails. I take advantage of superpowers rather a lot. It’s a cautious, collaborative workflow that retains a human shut to each step, and it is genuinely glorious at that. Superlite borrows its bones shamelessly: the plugin format, the session-start hook, the lifecycle expertise. Credit the place it is due, after which some.

But once I already knew precisely what I needed, more often than not went on the workflow ready for itself. I profiled it, the way in which you’d examine your financial institution assertion after a suspicious weekend. The time went to 5 locations:

• 8–12 human gates per function. One query per message, designs authorized part by part, then separate evaluations of the spec, the plan, and the strategy of executing the plan. It’s very thorough. It’s additionally how a four-hour assembly will get scheduled.
• Strictly sequential execution. One implementer, then one reviewer, then the subsequent activity. On my first benchmark that was a single-file queue of 21 dispatches, like a financial institution with one teller and a really lengthy lunch.
• A assessment after each activity, with re-review loops. About 12 minutes of a 34-minute construct.
• The full check suite, re-run by a number of expertise. In case it modified its thoughts.
• Opus subagents on the crucial path, writing code at about half Sonnet’s pace. Brilliant, considerate, and in no hurry in anyway.

None of those are errors. Each one is a smart security internet. Stacked collectively, they’re good once you wish to steer each step, and barely maddening once you simply need the factor constructed.

So superlite is not a rival to superpowers. It’s tuned for a unique job: autonomous improvement, at pace. If you wish to steer every step, use superpowers. If you wish to hand over a spec and are available again to working code, use superlite. Just do not allow each in the identical session. They share talent names, each inject context at startup, they usually argue like siblings within the again seat.

How it really works

The quick model: one approval, a plan written for parallelism, brokers matched to the work, and guidelines enforced by code as a result of, because it seems, brokers learn the principles after which do what they like.

flowchart LR
A([Your request]) –> B[One batch of questions]
B –> C[Plan]
C –> D[Agents build
in parallel]
D –> E[Review and fix]
E –> F([Done])

One batch of questions, one approval. Superlite sizes the request first. A typo simply will get fastened, with no design doc concerning the typo. A change to an present circulation will get a brief design in chat. A brand new venture will get one batch of as much as 4 questions, then one design-and-plan doc. You approve it as soon as. After that it solely stops for issues which might be damaging, outward-facing or security-sensitive. It will not push to primary whilst you’re getting lunch. It will do all the pieces else.

You select who’s in cost. With a human orchestrator, you see the entire plan with its predicted schedule and approve it earlier than something runs. With an AI orchestrator, you are not wanted in any respect, which is both releasing or mildly insulting relying in your temper. Every selection it will usually ask about will get recorded as a ruling: what it determined, why, and what it prices if it received that flawed. When you come again, you understand precisely which selections to second-guess first.

A plan written for the cut up. The plan is a activity graph. Each activity lists the recordsdata it owns, the precise interfaces it consumes and produces, and the exams it has to cross. Tasks that do not share recordsdata and do not depend upon one another run on the identical time. The graph decides how large the construct goes. On the present benchmark that peaked at 18 brokers working without delay, which is roughly the dimensions of a small startup, minus the ping-pong desk.

Agents matched to the work. The org chart:

• Opus coordinates. It plans and dispatches, and it isn’t allowed to the touch the code. Management, mainly.
• Sonnet builds many of the duties.
• Haiku builds solely small, totally specified “mechanical” duties that are not on the crucial path. The intern will get the well-defined stuff.
• Sonnet evaluations the packages.
• A contemporary Opus remaining reviewer reads a assessment packet constructed from the run’s logs and returns findings solely. It’s by no means allowed to repair something. It simply factors.
• Fix-only brokers in three tiers take these findings, routed by how properly the trigger is known.

Gated by code, not by prompts. I discovered this one the arduous manner. You can write “the coordinator by no means edits code” in a immediate in daring, in capitals, with feeling. The coordinator will learn it, nod, and edit the code. So now hooks implement it. One hook blocks the coordinator from enhancing venture code. Another catches any uncooked pytest or npm check it runs and quietly turns it right into a background run, so exams by no means block it. Another refuses to let anybody kill processes by identify (there is a story there, and it is within the deep dive). A plan has to cross lint --stable earlier than work begins, and steady duties are despatched off the second it passes.

Every run is measured. Hooks report every agent’s tokens, price and time. That feeds the subsequent run’s predictions and a comfortable price range that faucets you on the shoulder at 70% of the cap.

How to make use of it

You’ll want Claude Code, git, Python 3.10 or newer (for superlite’s personal instruments; the venture you construct may be in any language), and bash (Git Bash on Windows).

The supply is iha2/superlite on GitHub. Install it from {the marketplace}:

/plugin market add iha2/superlite
/plugin set up superlite@superlite-dev

Or clone iha2/superlite and cargo a neighborhood checkout for one session:

claude --plugin-dir 

To examine it is working, open a contemporary session and ship Let's make a react todo record. A working set up begins brainstorming earlier than it writes any code. It’s the “hi there global community” of agent workflows, and actually the global community would not want one other todo record, but it surely’s a superb smoke check.

Then:

1. Describe what you need. A paragraph or a spec file is sufficient. No want for a 40-page necessities doc. Although it’ll learn one.
2. Choose the orchestrator when it asks: you examine the plan, or the AI does all the pieces.
3. Let it run. Watch .superlite/ in your venture like a nature documentary. progress.md has the rulings and the log, test-summary.json has the most recent check outcome, and metrics.jsonl has the time and price per agent.

What you say shapes the circulation:

Situation	Say one thing like
A brand new venture	“Build me a static web site generator from this spec”
A function on present code	“Add CSV export with column widths to the prevailing app”
Debugging	“This check fails on leap days: discover the foundation trigger and repair it”
A small change	“Rename construct to render in every single place”
Hands off	“Build X. I’m away, determine your self”
Shipping	“We’re completed: end the department”

It by no means pushes or merges with out you. Autonomous, not reckless.

Does it truly work?

Anyone can name their very own instrument quick. I as soon as referred to as a script I wrote “blazing” and it took eleven minutes to rename some recordsdata. So each quantity beneath comes from a headless benchmark harness. It builds the identical venture from the identical spec, on Opus, and scores the outcome with a hidden check suite the brokers by no means get to see. No peeking, no finding out for the examination.

The newest run: 16.1 minutes

The check venture is intentionally not a todo record. It’s a static web site generator plus a spreadsheet engine (components evaluator, HTTP API and a browser UI) constructed as one venture from one spec, and scored by 177 hidden exams.

Here’s the most recent run, on the present construct:

Wall-clock, spec to completed construct	16.1 min
Hidden exams	177 / 177
Agents	21 in complete, as much as 18 working without delay
First brokers constructing	about 3 minutes in
Final assessment	30 seconds
Stops to ask a human something	0

Compared with superpowers on the identical venture:

	Wall-clock
superpowers, inventory (imply of three runs)	33.6 min
superpowers, orchestrated (imply of three runs)	23.5 min
superlite, newest run	16.1 min	52% much less time than inventory, 31% much less than orchestrated

Same 177 out of 177 hidden exams, in about half the time. That’s one run of the present construct in opposition to earlier runs on the identical machine, so name it a powerful trace slightly than peer-reviewed science. But it is a very robust trace.

It additionally beat its personal earlier construct (which averaged 26.9 minutes) by 40%. Yes, I’m competing with my very own previous self. It’s the one rival I can bully freely.

How it received there

The newest run did not come out of nowhere. The first construct was already fast on a smaller activity: sitegen alone, 9 modules, 89 hidden exams.

	superpowers	superlite
Wall-clock	34.4 min	8.8 min
Hidden exams	89 / 89	89 / 89
Serial dispatch chain	21 dispatches	3 ranges

Most of that pace got here from eliminating the queue. Superpowers dispatched 21 brokers, one after one other. Superlite dispatched 10, as much as 5 without delay. Same work, fewer individuals standing in line.

On the complete 177-test venture, an earlier superlite construct ran 3 times in opposition to superpowers:

	superpowers	superlite
Mean wall-clock	33.6 min	25.1 min
Runs	21.2 / 31.9 / 47.6 min	21.4 / 23.2 / 30.5 min
Spread, quickest to slowest	26.4 min	9.1 min
Hidden exams	177 / 177 each run	177 / 177 each run

Faster on common and rather more predictable. A 47-minute worst case is the distinction between “completed earlier than standup” and “completed after standup, throughout which you needed to say it is practically completed.”

But the information additionally confirmed the place superlite was nonetheless ready on itself. The construct was ending at about 13 minutes, after which 10 to 18 extra minutes went on evaluations, fixes, and the coordinator working exams within the foreground and looking at them. So:

• The coordinator misplaced the flexibility to edit code. It took it surprisingly properly.
• Every check run moved to the background.
• Fixes went to tiered fix-only brokers.
• Stable duties began constructing whereas the remainder of the plan was nonetheless being fastened.

That’s the construct that ran in 16.1 minutes.

The takeaway

If your agent workflow is gradual, it is most likely not gradual as a result of the mannequin is considering deep ideas. It’s gradual as a result of work is ready in a line, and one thing retains asking permission.

Split the work alongside interface boundaries. Let impartial duties run without delay. Move the mechanical steps into scripts. And implement the principles that matter with code, as a result of asking properly solely works on individuals, and solely typically.

The plugin is on GitHub: github.com/iha2/superlite.

In the follow-up put up I am going a lot deeper into the philosophy and the choices behind superlite: the gates, the agent tiers, and the graveyard of concepts I used to be very assured about proper up till I measured them.