
superlite
Lightweight Claude Code skills for the build lifecycle: one approval gate, parallel waves, short reports
- version
- 4.2.0
- GitHub stars
- 313
Install
/plugin install superlite@superlite-devRun it inside Claude Code after adding the marketplace with /plugin marketplace add iha2/superlite.
Contents
Discovered from sourceSkills 14
Diagnosis
Find the root cause before fixing. A fix without a known cause is a guess, and guesses create new bugs. Do not stack several changes at once.
Obvious failures: fix directly
A typo, a missing import, a clear stack trace pointing at the faulty line, a failing assertion whose cause is plain on reading the code. Fix it, re-run the focused test, move on. No ceremony.
Everything else
- Reproduce. Get a reliable, minimal trigger: a command, a test, an input. Read the full error and stack trace, not just the first line. If it cannot be reproduced, gather more data (logs, inputs, environment); do not guess.
- Check what changed. Recent diffs, new dependencies, config and environment differences often point straight at the cause.
- Trace the evidence. In multi-component systems, log or inspect what enters and leaves each boundary to find which component breaks. For bad values, trace backward through the call chain to where the bad value originates and fix it there, not at the symptom. Compare with similar working code and list every difference.
- Hypothesize. State the single most likely root cause in one sentence: "X is wrong because Y". Base it on evidence, not hunch.
- Probe. Test the hypothesis with the smallest possible change or observation: one print, one assertion, one input. Change one thing at a time. Confirmed: go on. Refuted: form a new hypothesis from what you learned. Do not pile fixes on top.
- Fix. Write a failing regression test that captures the bug (see
superlite:testing), apply one fix at the root cause, and run the focused tests. Do not bundle refactors or "while I'm here" changes. - Verify. Confirm the original reproduction now passes and nothing nearby broke (focused run; the full suite goes through
bash <skill-dir>/../swarm/scripts/superlite-cli run_tests --fullat the wave or branch end; focused:--fast PATHS; read its one-line summary).
When fixes fail
- After 2 failed fixes: stop. Re-read the evidence from scratch. Your model of the problem is wrong somewhere; list what you assumed and check each assumption.
- After 3 failed fixes: change the approach. Attended: tell the human what you tried and what you learned, and ask. Unattended: hand it to a fresh agent on a stronger model with the repro, the evidence and the failed attempts. Three failures in different places often signal an architectural problem, not a bug. Record the ruling.
Red flags: back to step 1
- "Quick fix now, investigate later."
- "Just try changing X and see."
- Proposing a fix before tracing where the bad value comes from.
- Another fix attempt without new evidence.
- "It's probably X" with nothing checked.
Handing off investigation
Give a subagent the repro, the error text and the hypotheses already ruled out. Ask for the cause and evidence, not a patch. Keep its report short.
Wrap-up
State the root cause, the fix, the regression test, and the evidence that it passes. If the cause was never found, say so rather than shipping a guess.
Drafting
A plan is a set of contracts Sonnet implementers can execute without asking questions, and also the input to the 0.3 engine: a machine-readable task graph, interface stubs, per-task time predictions, a predicted schedule and probe plans. Write it so scripts can parse it. Code the implementer would write anyway burns Opus time and invites transcription errors.
Any build with 2+ tasks runs through superlite:swarm: load it before writing the plan. Never use general-purpose agents for build or review work.
Save to docs/plans/YYYY-MM-DD-<topic>.md. When called from superlite:inventing, append to its doc instead. If the spec covers independent subsystems, write one plan per subsystem.
Lint, extract what's stable, fix the rest
lint --stable splits the plan into STABLE and FIX tasks (with reasons) and writes .superlite/stable.json. A task is stable when its own checks pass, every Consumes has a clean Produces line somewhere (even in an unstable task), it has no taskgraph edge to an unstable task, and it is not on a flagged CHAIN:. Plan-level issues (SPEC coverage, CHAIN:, the size cap, MISSED TARGET) never block stable tasks. dispatch offers only stable tasks. The order is fixed: lint, dispatch the whole stable set (lint --stable ends with DISPATCH NOW: ...), and only then patch the FIX tasks (edits or a full rewrite, as many rounds as needed), re-lint and dispatch the newly stable ones. No agent waits on plan polishing. Dispatched tasks are frozen: a rewrite keeps their blocks byte-identical, else lint reports FROZEN: and the change becomes a follow-up fix task, not a restart. **Status:** draft stays as an optional manual hold: next_tasks and dispatch skip draft tasks and their dependents, and draft tasks may keep placeholders.
Write for the split
Who orchestrates sets the mode (superlite-cli orchestrator status).
- Human orchestrator (the human validates the plan before it runs), two phases:
- Write the review plan:
docs/plans/<date>-<topic>.review.md, plain words, innomd-drawable diagrams and a few key code snippets, no taskgraph (review-plan.md). Nothing is built, dispatched or written except this file before the human's approving reply. With no question batch, list "Run the whole test suite at finish?" (default no) under "Decisions you can change"; the approving reply may set it. - When
open_in_harnessis on (superlite-cli agent_specs status), open the plan for the user first (After writing below; the harness's open row inusing-superlite/references/<harness>-tools.md). Show it in plain text, not AskUserQuestion: the path, a five-line summary and "Reply approve to start, or tell me what to change". END THE TURN and do nothing else until the human replies. - Read their answer. If you understand it as approval, send approve:
superlite-cli orchestrator approve --review <path>. Do not pass their words through and do not ask them to retype approve. If you understand it as changes with no approval, revise and ask again.lint --stable,dispatch,wave0andbuild_primerefuse until then. - Write the machine plan
docs/plans/<date>-<topic>.mdfrom the approved review plan, in the order below (same tasks and scope, header**Review plan:** <path>), thenlint --stable, and dispatch the stable set in the same turn. - It patches the FIX tasks, re-lints and dispatches the newly stable ones without asking again, as long as each fix stays inside what was approved (sizes, splits, stubs, field corrections). A fix that changes scope, an interface the human saw, or the spec coverage is decided without asking the human: record it as
Ruling: [scope] <decision> - <why> - <cost if wrong>;superlite-cli finishlists these under "Changed from the approved plan". AI orchestrator: no review plan, straight to the machine plan.
- Write the review plan:
- AI orchestrator (hands off: the user pre-approved, said "decide yourself", or an agent runs the session): write a queue that starts building while the fixes are made. Lint splits what you write into stable tasks, which build now, and fix tasks, which wait. Follow all six rules. Record open choices as
Ruling:lines.
In both modes, write for the split:
- Lessons. Before sizing tasks, run
superlite-cli lessons brief --agent drafter --files <paths the plan will touch>(no--task: tasks have no ids yet) and honour what it prints. - One Write, written as if in chunks. Write the plan whole, in one Write, but order it as if it were written in chunks, so the first tasks stand alone as a stable prefix: the header, Global constraints and the main diagram with its
%% taskgraph; then, optionally, a Wave 0 skeleton task (Kind: mechanical,Model: haiku; if you omit it,superlite-cli wave0builds the skeleton brief from your Produces lines and Global constraints, so state the language and test command there); then the root and producer tasks (no incoming edges), each with exactProduceslines, the correctKindand a size inside the band; then the consumers, each after its producers. Every block is complete, with no placeholders, so lint can mark it stable and the prefix dispatches before any later task is fixed. - Producers first, with exact
Produceslines. Lint resolves eachConsumesagainst some task'sProducesline, so write producers before their consumers: exact name, parameter types and return type. A consumer is then stable the moment it's written, even while its producer is still building or being fixed. - Finish each task block before starting the next. No placeholders, and every field filled. A half-written task is a fix task, and so is everything with an edge to it.
- Size each task for the band as you write it. Fill Components, LOC owned and Tests honestly, and aim for 2-5 min predicted. Something that looks over 6 min is two blocks from the start (server / UI, engine / CLI), not one block that lint sends back.
- Fewest edges. Draw an edge only when a task's tests run another task's code, never for an interface that has examples (rule 7). Order tasks so that those with no edges come first and each later task adds only what the earlier ones unblock.
- Mark the easy ones. A task that meets the
Kind: mechanicalrules getsKind: mechanicalandModel: haikuwhen you write it. - Contract examples. Under every
Producesanother task consumes that returns structured data, add 2-3e.g.lines: a call and its result with concrete values, in the plan's own language, for examplee.g. parse("1+2") -> Binary("+", Num(1), Num(2)). One source, two uses: the consumer's fake returns exactly these examples, and the producer's tests assert them. Lint reportsEXAMPLE:for a consumer whose producer has none (a fix task until it does), andEDGE:for an edge that exists only for interfaces with examples: drop it, or runplan_tools prunebefore the first dispatch. Never say stubs cannot compute values: examples are the values.
Plan shape, in this order
- Header: Goal, Architecture, Tech stack, Spec path,
**Detail:** contracts | tests | full(defaulttests),**Full suite:** yes | no(missing means no; from the "Run the whole test suite at finish?" answer),**Target-min:** N(predicted-total target, default 11),**Ignore:** a/, b, *.c(optional: paths or globs your tooling generates beyond the language defaults, e.g..next/,.env,*.sqlite), global constraints (exact values copied from the spec: version floors, names, formats). Task briefs point here, so do not repeat constraints per task. - Main diagram (always): Mermaid of components and data flow.
- File structure: every file and its one responsibility. Split by responsibility, not by layer, and follow the repo's patterns.
- Task graph (always, machine-readable): see below.
- Predicted schedule: generated, never hand-written.
- Sections, one per component or package: its tasks, a mini diagram only if the section interacts, and a
**Probe entry:**line. - Review Focus: the probe plan.
- Self-review.
Diagram rules
- Main diagram and task graph: always.
- Mini diagram only where something interacts: a sequence across components, a state machine or a protocol, at most about 15 nodes. Skip it for self-contained modules (slug, feed, errors). Their Consumes, Produces, Owns and tests already say everything, and a diagram only repeats them and risks contradicting them.
- Every Mermaid block must parse. Quote labels that contain parentheses or punctuation.
Task graph
One Tn --> Tm edge per line under a %% taskgraph comment. Only execution dependencies are edges: Tm's tests must run Tn's code. A names-only dependency (a route path, a CLI flag) or one a stub satisfies is not an edge, so it never makes a task wait. Declare nodes above the marker.
flowchart LR
T1[engine]
T2[app layer]
T3[ui]
T4[integration]
%% taskgraph
T1 --> T4
T2 --> T4
T3 --> T4
Here T1, T2 and T3 run in parallel; T2 and T3 build against T1's stubs, not its code. Waves are only a planning view: the scheduler dispatches a task the moment its dependencies are checkpointed, with no wave barrier and no wave width cap.
Split by interface
- Interface stubs in Wave 0. Wave 0 holds the skeleton (manifest, package inits, test config, shared error types) and interface stubs for every
Producesanother task consumes.plan_tools.py stubsgenerates them from yourProduceslines, so write those lines exactly asmodule.function(args) -> retorClass.method(args) -> ret, with a one-line contract in the task. The stub is the contract: implementers may not change a signature without a coordinator ruling. - A task waits only when its tests execute another task's code. Consumers test against stubs with small fakes, never against the real producer. Integration tests that run both sides go in one small integration task per package at the end, so the consumers themselves don't wait. Consumers' own tests still run against the real producer later, through the seam check (
SUPERLITE_REAL=1). A chain like parser → evaluator → workbook → CLI becomes one wave of four tasks against stubs, plus the integration task. 2a. Keep the chain short. Lint fails withCHAIN:when the predicted critical path is over 2.5 times its longest task (with 3 or more tasks on it). Stub more interfaces, or addRuling: sequential - <why>when the order really is forced, such as a migration before its users. - Keep every task inside the size band. The only measure is predicted time, held in
config/predictor.jsonassize_band(low_min 1.5, high_min 6.0). Over high_min lint failsSIZE:: split along components, for example a server+UI task becomes server (against the workbook stub) and UI (against the spec's JSON contract). Under low_min it printsNOTE:(consider merging with a related task in the same package) and never fails.predict --refitmoves the band from measured task times. The 80k context ceiling stays. - Slow tests stay out of the inner loop. Mark them
Tests: slow. Implementers run only fast tests during TDD, and slow suites run once in the background after the checkpoint. - Diagrams show the run. The graph and schedule show the width and length of the run before anything runs, when a bad split is cheapest to fix.
Task template
Size, not depth: a task is the smallest unit with its own test cycle that a reviewer could reject alone. Fold setup, config and docs into the task that needs them. Docs that describe other tasks' output depend on them.
### T7 minisheet server · Complexity 5 (O-1) · Est. context 38k
```mermaid
sequenceDiagram
Client->>Server: POST /api/cells {ref, raw}
Server->>Workbook: set(ref, raw)
Workbook-->>Server: changed refs
Server-->>Client: 200 {cells}
```
**Owns:** src/minisheet/server.py, tests/minisheet/test_server.py
**Components:** 1
**LOC owned:** 120
**Tests:** slow
**Model:** sonnet
**Est. time:** 2.5 min (1 component, about 120 LOC, slow tests)
**Consumes:** Workbook.set(ref: str, raw: str) -> list[str] (T5) · Workbook.get(ref: str) -> Value (T5)
**Produces:** create_server(wb: Workbook, port: int = 0) -> HTTPServer
**Review Focus:** `test_unknown_method_404`: PUT /api/cells gives 404 {"error": "not found"}; `test_oversize_body_413`: 2 MB body gives 413
**Test code (verbatim):** ```python … ```
**Steps:** 1 failing test, 2 run: FAIL, 3 implement, 4 run: PASS
**Notes:** only non-obvious detail (a tie-break rule, an ordering).
The title line shows Complexity and Est. context; drop the mini diagram if the task does not interact.
| Field | Rule |
|---|---|
Owns | Exact paths, only this task's. Two tasks that can run at once never share a file. |
Components | Integer count of components the task builds. |
LOC owned | Integer estimate of lines this task writes. |
Tests | fast or slow (browser, server and I/O suites are slow, pure functions fast). |
Kind | design (the default) or mechanical. Mechanical means the what is fully decided and only the typing is left: LOC owned ≤ 150, Components ≤ 2, Tests: fast, no Review Focus case in deep, numeric, state or protocol, and test code or named tests with exact inputs and outputs. Typical: skeleton and config, thin CLI or route wrappers over a given interface, constant tables, small pure functions with a crisp spec (slug, date format), tests from an explicit list, docs from existing code. Never: parsers, evaluators, servers, UI, anything with state or an ambiguous spec. Lint rejects (KIND:) a mechanical task that breaks a rule. |
Model | haiku for Kind: mechanical (lint rejects haiku on any other kind), otherwise always sonnet; lint rejects opus (Opus writes about half as fast). Split a task that seems to need Opus. If Sonnet can't get part of it right, a fixer-opus handles that part. Security-sensitive code still gets an Opus review. |
Est. time | predict.py recomputes it from the four fields above, and the fields win on disagreement. Write them honestly. |
Est. context | 18k + 3.3k + 21.6 per LOC owned + 0.45 per char of docs handed over + 36.9 per LOC read, plus a 10-15% margin. Over 80k means split. |
Consumes/Produces | Exact names, parameter types and return types. An implementer reads only its own task, so this is how it learns what neighbors named things. |
Review Focus | Cases from the Review Focus section that touch this task's files, as named tests (see below). |
Test code | At contracts, each test named with exact inputs and outputs. At tests and full, the code, runnable as written. Include the error and edge cases the spec implies. **Detail:** full on one task overrides the header, for tricky cores. |
Review Focus: the probe plan
Classify each package by app type, then pick its generic categories from the table. Add app-specific risks the domain implies (a spreadsheet: circular references through ranges, huge-range timing, CSV formula injection; a site generator: path traversal in slugs, template recursion).
| App type | Generic categories |
|---|---|
| library / parser / evaluator | deep, numeric, encoding, state |
| CLI | protocol (commands and args), encoding, state, file |
| HTTP service | protocol, encoding, numeric, state |
| web UI | protocol via its API, encoding (rendering, XSS) |
| file I/O / generator | file, encoding, deep |
| data pipeline | numeric, encoding, state, deep |
| concurrency | state (races, partial writes), protocol |
| auth | protocol, state; security review required (Opus) |
Rules:
- List, per package: app type, categories, specific risks.
- Copy into each task the cases that touch its files, as named tests with exact inputs and outcomes. The implementer writes them during TDD, so the failures never reach review (lever 1).
- Never list the spec's own examples: tests already cover them.
- A
**Probe entry:**line per package feeds the generated probe adapter, for examplecall=minisheet.Workbook.set · run=python -m minisheet · serve=minisheet.server.create_server. Usecall=for libraries,run=for CLIs,serve=for servers. No agent writes adapters.
Feature mode: the feature plan, the prototype plan, the integration plan
- Feature plan
docs/plans/<date>-<topic>.feature.md, plain language, the review plan of feature mode (approve --reviewtakes it):## Goal(and who it is for),## What changes(screens, commands, endpoints or outputs, by target kind),## Acceptance checks(bullets a human can try;superlite-cli proto tryoutprints them), then after research## Code map(entry points and how the app is stood up, touched files and tests with their seams, interfaces that must not change, conventions and toolchain), then after the Grill (superlite:inventing)## Decisions(at most 10 lines:Decided:,Assumption:,Prototype decides:,Ruling:),## Prototype scope(keep, stub, level L1 or L2) and## Integration outline. For a web UI the code map names the UI component set, or says there is none, and the prototype scope keeps that set. Use one-off markup only when there is no UI component set. - Prototype plan: the agent format, in the prototype worktree, at most 8 tasks and about a quarter of the integration estimate; see
superlite:feature-prototype. - Integration plan (agent format, in this feature's dedicated worktree on
superlite/<topic>— never another feature's checkout; header**Review plan:**the.feature.md): one task per touched module; every interface in the code map isFROZEN; migration tasks where data changes; a seam check task between new and existing code; the prototype's acceptance tests as the target. Code is ported task by task from the prototype, never merged: no stub, fake or fixture of the prototype may appear in anOwnslist. Every existing test must still pass.
Plan size cap: 15k characters
The plan rides in the shared prime and is written on the critical path. Keep contracts, verbatim tests and the required diagrams. Move spec excerpts out and reference them by section. Check with wc -c.
No placeholders
These are plan failures: "TBD", "TODO", "add error handling", "handle edge cases", "similar to Task N", a test without a name and an asserted value, or a type or function no task defines.
After writing: lint --stable (lint waits for approval with a human orchestrator)
Replace PLAN and SPEC with the paths. <superlite-root> is two levels above this skill's "Base directory for this skill: ..." path (run it through cygpath -u first if that exists).
bash "<superlite-root>/skills/swarm/scripts/superlite-cli" plan_tools lint --plan PLAN --spec SPEC --stable
Lint drops the edges that examples make removable (consumer not yet dispatched) itself; schedule only prints. CHAIN [chain-xxxx] is silenced only by Ruling: sequential [chain-xxxx] - <why> with the id lint printed; a ruling written before lint never matches.
Read the lint output:
MISSED TARGETis a warning, not a failure. Consider re-splitting or stubbing the tasks on the named critical path. If the chain is inherently sequential, accept the plan and recordRuling: <why>.NOTE:(under low_min) is advice only.- Every other error must be fixed: placeholders, Consumes/Produces mismatches, diagram parse errors,
SIZE:(over high_min),CHAIN:,KIND:,OPUS-TASK:, spec sections with no task. First dispatch every task on theDISPATCH NOW:line, then patch the FIX tasks listed under--stable(edit or rewrite; keep dispatched blocks unchanged), rerunlint --stable, until onlyMISSED TARGETandNOTE:remain. Stable tasks need no rework: in delegated mode they dispatch now; with a human approver they wait for the yes (see "Who decides sets the mode"). - Open it: check
superlite-cli agent_specs status. Only whenopen_in_harness: on, open every finished human-facing plan (review, feature, MVP, combined design+plan) using the open row inusing-superlite/references/<harness>-tools.md. This applies in both orchestrator modes; an AI orchestrator opens it too and does not wait for the user. Never open the machine,.proto.mdor integration plans.
Self-review checklist
Run it yourself, not as a subagent. Fix in place, with no re-review.
- Coverage: every spec requirement maps to a task.
- Placeholders: none.
- Type consistency: each Consumes line matches the Produces line of its owner.
clearLayersin T3 andclearFullLayersin T7 is a bug. - Graph: every edge is an execution dependency, with no cycles, and no two tasks that can run at once share a file.
- Measurable fields: every task has
Components,LOC owned,Tests,Model. - Review Focus: each package has an app type, categories and a
Probe entry, and each task carries the cases for its files. - Limits: the plan is at most 15k chars, no task is over the size band (
SIZE:), and schedule and lint have run.
Handoff
Do not ask about an execution method: it is superlite:swarm (its inline mode covers small plans). If called from inventing, return to it for the single approval; the stable set dispatches as soon as it is approved. Otherwise give the path and wait for the go-ahead, unless the user pre-approved, in which case record any open choice as Ruling: ... and proceed.
Red flags
| Thought | Reality |
|---|---|
| "I'll paste the full code so Sonnet can't go wrong" | tests is the default. full is for non-obvious algorithms. |
| "T5 can wait for T2, to be safe" | An edge is for code its tests execute. A stub or a name does not need one. |
| "Draw a diagram for every module" | Only for interactions. Self-contained modules get none. |
"I'll write Est. time by gut feel" | Fill in the measurable fields. The predictor and the schedule depend on them. |
| "Lint says MISSED TARGET, so the plan is bad" | It is a warning. Re-split or write a Ruling:. |
| "Its README can go in the first wave" | Docs wait for the code they describe. |
Feature prototype
The prototype is the smallest thing that stands up and shows the feature working, inside just enough of the original app to run. It lives in a sandbox folder inside the checkout, .superlite/sandboxes/<session>/<topic>/ (host when there is no session), made by superlite-cli proto start, is built by a normal superlite build scoped to that folder, and is tried by the human (superlite-cli proto tryout) before the integration build touches the real code. Its code is later ported, never merged, so stubs and fakes never reach the user's branch.
Keep, stub, drop
- Keep: the app's entry point and how it starts, the screens, routes, commands or calls the feature touches, and their direct dependencies. Keep the project's own language, framework, toolchain and conventions; never rewrite into another stack.
- Stub: everything the kept code calls that the feature does not change: the database becomes a seeded fixture or an in-memory store, external services become fakes returning the plan's example values, auth becomes one fixed test user, config uses test values with no real secrets.
- Drop: screens, commands and modules the feature never reaches. Do not delete them in the sandbox if the build needs them to compile; leave them untouched and unused.
Web UI component set
When the target is a web UI, the code map names the repo's UI component set: the directory or package existing screens import for buttons, fields, and layout. The prototype keeps that set, and the new screen is composed from those components. Use one-off markup only when the code map says the repo has no UI component set. The set is not stubbed and not dropped.
By target kind
| Kind | Keep | Stub | The try-out |
|---|---|---|---|
| web | the app shell, routing, the pages the feature changes, the repo's UI component set, their API calls | the backend behind those calls (a fake handler or fixture data), auth, analytics | a URL and port; show it in a preview pane |
| cli | the entry point, argument parsing, the commands the feature adds or changes | the file system or network the command reaches (a temp folder, fixtures) | a terminal session: the commands to type and what they print |
| library | the public modules the feature extends and their callers' types | heavy dependencies the new calls do not need | example calls with their results, or a short script |
| api | the server start, the routes the feature touches, request and response models | the data store (in-memory or seeded), downstream services (fakes) | example requests (curl or an HTTP file) and the responses |
| other (pipeline, bot, job) | the stage or handler the feature changes and its input and output formats | the sources and sinks (fixture input, a local output folder) | a run command on a sample input and the expected output |
Real code in place
The sandbox holds only the new code and the stand-ins. Reference the app's real code where it is; do not copy it in.
- Python:
PYTHONPATHor asys.pathinsert pointing at the checkout's source. - Node:
tsconfigpaths, or a relative import out of the sandbox. - Go: a
replacedirective in the sandbox'sgo.mod. - Rust: a path dependency in
Cargo.toml. - JVM: a source set that includes the checkout's source folders.
- .NET: a project reference to the real project.
Inject stand-ins at the sandbox entry point. Copy one real file only when it hard-wires a dependency that cannot be injected, and say so in the plan.
Sandbox levels
- L1 stubs (default): the sandbox reuses the checkout's installed dependencies and every service the feature does not change is stubbed. Seconds to set up.
- L2 isolated environment: only when the plan says the feature depends on real data shapes (a schema change, a migration, a query over real-looking data): the sandbox gets its own dependency install, a seeded fixture database with realistic shapes, a copied config with secrets replaced by test values, and offset ports. Record the level and why as a
Ruling:and pass--level L2tosuperlite-cli proto start. - Never real secrets or production data in either level.
The prototype plan
- When
superlite-cli agent_specs statusis on, keep the feature.spec.mdin view (acceptance from the spec); optional task-local notes stay under the sandbox's.superlite/specs/. - An agent-format plan in the sandbox,
<sandbox>/docs/plans/<date>-<topic>.proto.md, whoseOwnspaths all stay inside the sandbox, at most 8 tasks and about a quarter of the integration estimate (cost and time). A larger plan means the scope is wrong: cut it back to what the acceptance checks need. - Wave 0 sets up the container (the stubs, fakes and fixtures, the run command); the feature tasks then run in parallel, Haiku for mechanical pieces and Sonnet for the rest.
- Its tests are written against the feature plan's acceptance checks, so they carry into the integration build as its acceptance tests.
- Tests run by path:
superlite-cli run_tests --fast <sandbox>/tests. - The run command goes into
superlite-cli proto start --run "<command>"(orsuperlite-cli proto tryout --run), and how to reach it into--reach.
Inventing
Turn a request into an approved design with as little ceremony as the request allows. Intent comes first: know what the user wants to accomplish and what success looks like before you pick an approach. Who orchestrates is chosen first: with a human orchestrator the human approves the plan once, before it runs; with an AI orchestrator nothing is asked. After that, nothing stops you except destructive, outward-facing (push, merge, publish) or security-sensitive actions.
1. Size the request, in one line
Announce it: "This looks bounded, so I'll ask one batch of questions and show a short design here." The user can override.
- Trivial (a few tool calls: a typo, a rename, a one-line fix): do it. Exit this skill. With a human orchestrator, say the change in one line and wait for the human's yes in chat; only an orchestrated build needs a review plan.
- Bounded (a change to a flow that already exists in the repo): short in-chat design, one approval.
- Architectural (a new project or subsystem, or changes to interfaces others depend on): one combined design and plan doc, one approval.
- Spike ("can we...", "is it possible...", throwaway is fine): say what you will try in 2 sentences and try it. The output is an answer, not code you keep.
Hidden complexity found mid-task upgrades the size. Say so and step up. If the request describes several independent subsystems, say that first and brainstorm only the first one.
2. Explore and ask, once
Read the relevant code and recent commits first. Use an Explore agent (it runs on Haiku) for broad sweeps. Do not ask what the repo or the request already answers.
If purpose, constraints or success criteria are still missing, ask them in ONE AskUserQuestion call: up to 4 questions, multiple choice where possible, your recommended option first. For architectural work, include the plan detail choice in the same batch: contracts, tests or full. Recommend full when the core is algorithmic or risky, otherwise tests (the default). Add the orchestrator choice to that same call as one single-choice question, options Human orchestrator: I approve the plan before it runs and AI orchestrator: hands off, it does everything (details in ../swarm/orchestrator.md); never ask it when the request settles it, and in a headless run default to AI with a Ruling:. Once the request is known, and BEFORE recording it, run bash <skill-dir>/../swarm/scripts/superlite-cli session ensure --slug <topic>. Follow SESSION/REDIRECT. On ASK untracked=<N> slug=<s>: <files> (exit 4) ask in ONE AskUserQuestion "Stash with " / "Keep in the folder" / "Always stash (this repo)" / "Always keep (this repo)"; for an "Always" choice run bash <skill-dir>/../swarm/scripts/superlite-cli session untracked stash|keep first, then rerun with --untracked stash|keep. On ASK move slug=<s> (exit 4) ask "Move it" / "Not now", then do what the on yes: / on no: line says (rerun with --move yes on "Move it"; on "Not now" stop, nothing changed); if the hook printed superlite sync:, offer "Bring main in now" / "Later" via superlite-cli session sync --slug <s> (--later; on exit 5 dispatch a fixer, then --continue or --abort). Then record it: bash <skill-dir>/../swarm/scripts/superlite-cli orchestrator set human|ai. Add one more single-choice question to that same call, never a separate question round: "Run the whole test suite at finish?" with options No, affected tests only (Recommended) and Yes, once at finish; bounded work asks it with the in-chat design. With no batch, the review plan lists it under "Decisions you can change" and the approving reply may set it. Never one question per message. Bounded work gets at most one batch. If nothing is missing, ask nothing and restate your understanding in the design instead.
Grill (after discovery, existing code)
Run this in feature, debug and review modes, once the code is read: feature after research (code map), debug after the cause is reproduced, review after the target and its diff are read. Not in small, MVP or regular builds on an empty folder.
- Ask for cost saved, not for completeness. Cost is tasks, files, tests, agents, prototype rounds, rewrites, and the tier the work needs. Rank each candidate question by what its answer removes or cheapens, and ask only those that change the plan's size, direction or tier. A good answer either shrinks the plan ("does this need to exist?", "reuse X instead of building Y?", "which parts can wait?", "is the smaller version enough?") or makes the work mechanical enough for a cheaper agent ("one pattern for all five call sites?", "copy the existing X exactly?", "exact names and values?"). The recommended option is the cheapest one that still meets the goal; when it narrows what the user asked for, say so in the question. Decide the rest as
Ruling:orAssumption:. - Ask nothing the code, the code map or the request already answers; state the finding. Skip the grill when nothing material is open.
- Round 1 is the whole frontier in ONE
AskUserQuestion: at most 4 questions, recommended option first, so one click accepts all. Round 2 only for questions round 1's answers opened, in feature mode only. Never a round 3. - "I don't know" or "you decide" is an answer:
Assumption:and move on. A look-and-feel question is not grilled:Prototype decides:. - Human orchestrator: ask. AI orchestrator: grill yourself. Write the same round 1 questions, answer each from the code map and best default, run round 2 on what that opens (the same caps apply to what you write), and record each as
Ruling: <decision> (because <reason>). The AI orchestrator does not ask the full-suite question:Ruling: full suite no (because affected runs cover the change and the user was not asked). Edit the plan in place to match, so it reads as one plan. Whenagent_specsis on, keep the feature.spec.mdconsistent: reconcile any ruling that changes scope into it, or do not make that ruling (the spec wins). - The result is not a file: a
## Decisionssection of at most 10 lines in the plan (with no plan, as in debug and a review of a branch or path, in the chat, and in the regression test's comment only when one is written) (Decided:,Assumption:,Prototype decides:,Ruling:).
3. Design
Write what you understood (separate what the user said from your assumptions), then the design. Cover architecture, components, data flow, error handling and testing. Keep it as short as the size allows.
- YAGNI. Cut every feature the user did not ask for or the stated success criteria do not need.
- Clear units. Each unit has one purpose, a defined interface, and can be tested alone. For each, you can say what it does, how it is used and what it depends on. If someone must read the internals to use it, fix the boundary.
- Fit the codebase. Follow existing patterns. Include a targeted fix only where existing code blocks the work. No unrelated refactors.
- Name the approach you chose and, when a real alternative exists, why you rejected it in one sentence. Do not present three approaches by default.
4. Approve once, then build
Bounded: present the design in chat and stop until the user says yes. Then implement with superlite:testing. No spec file, no plan doc. After the tests pass, run superlite-cli finish in the session checkout: it marks the session finished and leaves uncommitted work in place.
Architectural:
- With an AI orchestrator write ONE doc,
docs/plans/YYYY-MM-DD-<topic>.md: the design above, then the plan. With a human orchestrator write the review plan instead (<date>-<topic>.review.md, template../drafting/review-plan.md); the machine plan comes after the yes. Invokesuperlite:draftingfor the plan half and append it to the same file. If the user named a different location, use theirs. With an AI orchestrator, whenopen_in_harnessis on (superlite-cli agent_specs status), open the doc for the user after writing it (superlite:drafting, After writing) and do not wait. - Self-review inline: placeholders, contradictions, scope (one plan, or decompose?), and requirements that could be read two ways. Fix them in place. No review loop, no subagent.
- With a human orchestrator: When
open_in_harnessis on (superlite-cli agent_specs status), open the plan for the user first (superlite:drafting, After writing). Then ask in plain text, not AskUserQuestion (the human's typed reply is what the hook verifies): the review plan's path, a five-line summary and "Reply approve to start, or tell me what to change"; END THE TURN and do nothing until the human replies. If you understand the answer as approval, send approve withsuperlite-cli orchestrator approve --review <path>and write the machine plan from it. Do not pass their words through and do not ask them to retype approve. If you do not, revise and re-present once. The human approves the design in the review plan, never the machine plan: that one is task-graph format for the orchestrator, is not shown for approval, and must not add or change anything the human approved. With an AI orchestrator skip the approval. Runbash <skill-dir>/../swarm/scripts/superlite-cli graphify_gate; when it reportsneeds_install: true, add the Graphify install opt-in (uv tool install graphifyy) to that same question. Never install without a yes. - On approval, invoke
superlite:swarmonce, in this session: this session is the one coordinator. It runslint --stable, dispatches the stable tasks at once and patches only the FIX tasks.
Until approval, only read-only exploration is allowed. No scaffolding, no dependency installs, no product code. Approval covers the doc as presented. Send approve only when you understand the answer as approval.
AI orchestrator (unattended)
If the user says they are away, or "decide yourself", or the prompt pre-approves design and plan, or the orchestrator is AI, the gate is already passed. Skip the questions and the approval. Choose the sensible default for each open question, including the plan detail (full for algorithmic or risky cores, otherwise tests), and record it in the doc, or in chat for bounded work, as a line:
Ruling: <decision> (because <reason>)
Install Graphify only if SUPERLITE_ALLOW_INSTALL=graphify is set. Then proceed straight to implementation (bounded) or to superlite:swarm (architectural). The closing message lists all rulings. Destructive, outward-facing and security-sensitive actions are deferred, not waited on: take the safe path, record it, and keep going.
Red flags
| Thought | Reality |
|---|---|
| "Too simple to need a design" | Trivial is exempt. Bounded gets a short design and a yes. |
| "Let me ask one thing first" (again) | Batch everything into one AskUserQuestion. |
| "I'll start while they read the design" | The approval is the gate. Present, then stop. |
| "I know this kind of app, so it's bounded" | Bounded means the flow exists in this repo. A new project is architectural. |
| "Let me offer three approaches" | Recommend one. Mention an alternative only if it is real. |
| "They are away, so I will ask anyway" | Unattended means rule and record, not wait. |
Merged
The PR is merged on the remote. Bring the local repo up to date and remove what the PR left behind. Only existing tools, in this order; never push, never touch the remote branch. Nothing here is guessed: each step checks before it changes anything, and any check that fails stops the flow with nothing changed after it.
1. Find the branch
Take the first that works:
- the argument: a session slug, a branch name, or a PR number (
gh pr view <n> --json headRefName). Resolve a slug throughbash <skill-dir>/../swarm/scripts/superlite-cli session status --jsonor<hub>/.superlite/session-store/<slug>/session.jsonand use its recorded branch; only fall back tosuperlite/sessions/<slug>when no session metadata exists. - the current branch, when it is not the base branch
- otherwise list live sessions, archived session manifests and local branches, and ask once (one AskUserQuestion) which one was merged
Find the base branch the way superlite:shipping step 2 does. Retain the slug resolved from an argument. For a branch selected by argument, PR, current checkout or the user's answer, find the slug by matching its branch in live session rows or archived <hub>/.superlite/session-store/*/session.json manifests. Only infer the slug from the superlite/sessions/ prefix when no matching metadata exists; otherwise a branch without matching metadata or that prefix has no slug.
2. Confirm the merge
gh pr list --head <branch> --state all --json number,state,url,headRefOid,headRepositoryOwner,mergeCommit,baseRefName
Keep only PRs whose headRepositoryOwner is this repo's owner (gh repo view --json owner): --head also matches same-named fork branches. The PR with the highest number decides.
- No
gh, not signed in, or no PR for the branch: say so and stop. Do not fall back togit branch --merged; a squash merge never shows there. OPEN: say it is still open and stop.CLOSED, not merged: ask once, "Keep the branch" / "Discard it". On keep, stop. On discard, skip the head check below and step 4: run steps 3, 5 and 6.MERGED: use itsbaseRefNameas the base and go on.
Then check the local branch holds nothing the PR did not. If git cat-file -e <headRefOid> fails, run git fetch origin pull/<number>/head first; if it still fails, stop. Then git rev-parse --verify refs/heads/<branch> must equal headRefOid, or git log --oneline <headRefOid>..refs/heads/<branch> must exit 0 and print nothing. If it lists commits or exits non-zero, name them (or the error) and stop: they were never in the PR.
3. Leave the branch
Look up the branch's checkout in git worktree list --porcelain.
- Its checkout has uncommitted work (
git status --shortthere is not empty), its session row insession statusreportsstash:yes, orgit rev-parse -q --verify refs/superlite/wip/<slug>finds parked work: that work is not in the PR. Name it and ask once, "Stop and keep it" / "Discard it". On stop, stop. - The session is still listed in
session status: first leave its worktree if you are in one (ExitWorktreewithaction: "keep"under Claude Code, elsecdto the main checkout), then from the main checkout runbash <skill-dir>/../swarm/scripts/superlite-cli session close --slug <slug> --keep-branch. It puts the host back on the base branch and removes a worktree superlite cut. On anASKline (exit 4, nothing changed), ask exactly what itsask:line says and do what the chosenon ...:line says. A Claude-created worktree is not removed by close: end it withExitWorktreeremove, assuperlite:shippingstep 7 says. - No session, but the branch is checked out: if the user chose to discard its uncommitted work above, first run
git reset --hardandgit clean -fdin that checkout while it is still on the feature branch. Then switch that checkout to the base branch (git switch <base>), or leave a linked worktree the way step 7 ofsuperlite:shippingdoes.
4. Update the base branch
git fetch --prune origin, then fast-forward only:
- The base is checked out in a clean, unoccupied checkout (
session statuslists no session hosted there, even one whose run is finished):git merge --ff-only origin/<base>there. If another session hosts that checkout, report it and skip this step without changing its files. - The base is not checked out anywhere:
git fetch origin <base>:<base>. - The base is checked out with uncommitted work, or the fast-forward fails (local base has commits origin does not): report it and skip this step. Never merge, rebase or reset the base.
5. Delete the branch
- With a slug (a listed or archived superlite session):
bash <skill-dir>/../swarm/scripts/superlite-cli session discard --slug <slug>. It drops the session's store and parked work ref, and the branch unless superlite adopted it. - Then, or without a slug: if
git rev-parse -q --verify refs/heads/<branch>still finds it,git branch -D <branch>.-Dis safe here only because step 2 proved the branch is in the merged PR, or the user chose "Discard it"; never use it otherwise.
The remote branch is not touched. GitHub's "delete branch on merge" or the user removes it.
6. Report
Run bash <skill-dir>/../swarm/scripts/superlite-cli session status. Print one line per step: PR number and URL, merge commit, the session closed, base <old sha>..<new sha> (or why it was skipped), the branch deleted. Name each session now behind the base (main:+N); each one is offered the update in its own chat, nothing is synced here.
Never
- Push, delete a remote branch, or open, close or merge a PR.
- Delete a branch
ghhas not reported as merged, or one with commits the PR does not hold, unless the user chose "Discard it". - Merge, rebase or reset the base branch.
- Discard uncommitted or parked work without the user's answer.
MVP prototype
One self-contained page, .superlite/mvp/prototype.html: raw HTML and JS, no build step, no network, fake data. It is a spec
for behavior, not product code. Design: docs/mvp-flow.md. Tools: superlite-cli mvp_check (see below).
1. The plan the page is built from
docs/plans/<date>-<topic>.mvp.md opens with the usage diagram, then **Target:** (web, cli, library, api, other;
combined as web, api), optionally **Estimate:** 30-45 min, $4-7, then one heading per feature, which mvp_check parses:
### F1: Create a note
- **Gets:** a note saved in one step
- **Use:** type, press Enter
- **Depends:** none
- **Size:** S
- **Priority:** must
- **Recommend:** in - the core of the product
Features considered and left out go under ## Left out as plain bullets, with no F id.
2. Write the mock, not the page
Write only the main area as an HTML fragment, .superlite/mvp/mock.html, in the style for the target from
mock-patterns.md. Then:
bash <skill-dir>/../swarm/scripts/superlite-cli mvp_check build --plan docs/plans/<date>-<topic>.mvp.md --mock .superlite/mvp/mock.html
build fills page-template.html (side panel, footer, save logic) with the plan's features and your mock,
stamps the page's sha, and checks it; it does not open it. Do not copy or rewrite the template by hand.
Show the page to the user; how is your choice, by what your harness offers: an in-IDE view (in the Claude desktop
app, send the page as a file with display render), a browser tool you can drive, or superlite-cli mvp_check open for the default
browser. In a headless run, skip it. If the view cannot save files, Save feedback falls back to a download, and Copy
feedback to the clipboard.
Mock rules:
- Every element a feature adds carries
data-feature="F2"(several ids:data-feature="F2 F4", hidden if any is cut). Every feature appears at least once. Cutting it in the panel hides those elements. data-screen="S1" data-title="Note list"marks a screen (web: one shown at a time),data-go="S2"navigates on click,data-editmarks a label the user may retype (never on the same element asdata-go).data-sl-orderon a container reorders itsdata-featurechildren with the panel's order.- Fake data inline. No
http://orhttps://anywhere (writeapi.example/notesor/notes), nofetch, no CDN, no fonts.
3. Check
superlite-cli mvp_check check --plan <mvp.md> must print mvp_check: ok. It checks: the page parses and its structural tags close,
the panel's data matches the plan, every feature id is in the mock, no external URLs or network calls, and (when the feedback
file exists) the feedback schema, its features against the plan, and its prototype_sha against the page. Fix the mock or the
plan, then build again. After any hand edit of the page run superlite-cli mvp_check stamp.
In either orchestrator mode, when open_in_harness is on (superlite-cli agent_specs status), open the .mvp.md for the user
(superlite:drafting, After writing); do not wait on it.
4. Human orchestrator
Show the path, a five-line summary (goal, target, features in, features out, rough time and cost) and: open the page, cut or
reorder features, edit labels, leave notes, press Save feedback, then reply in chat. END THE TURN. The chat reply
approves, never the file. If you understand that reply as approval, send approve: superlite-cli orchestrator approve --review docs/plans/<date>-<topic>.mvp.md, then
superlite-cli mvp_check fetch (the project file, else the newest mvp-feedback*.json in Downloads, copied in; if none, ask the user to
paste the Copy feedback block and save it yourself to .superlite/mvp/mvp-feedback.json), then
superlite-cli mvp_check check --plan <mvp.md> --require-feedback. A sha mismatch means the file came from an older page: ask once for a
fresh save. From here on the human is not asked again: a scope change is a Ruling: [scope] ... line, listed by superlite-cli finish under
"Changed from the approved plan".
5. AI orchestrator (self-check, no stop)
superlite-cli mvp_check check --plan <mvp.md> until ok, then superlite-cli mvp_check ai --plan <mvp.md> writes the feedback with source: "ai",
every feature as the plan recommends, and no edits. Log Ruling: MVP scope taken as the plan recommends - AI orchestrator - cost if wrong: a feature rebuilt later. No approve.
6. Feedback into the agent-format plan
Schema and rules: feedback-schema.md. in: false features go to "Out of scope"; kept features become tasks
in order, each keeping its F id as the trace id; added entries become features marked "unreviewed"; label edits change
the FROZEN names; screens and click paths become FROZEN interfaces and CHAINs; fake data becomes EXAMPLE blocks. Write
docs/plans/<date>-<topic>.md with **Review plan:** docs/plans/<date>-<topic>.mvp.md, then lint --stable. If lint fails,
fix the plan, never the feedback.
7. At finish
Delete .superlite/mvp/ unless the target includes web and the feedback says keep_as_frontend: true; then the page is the
first producer task's starting file, converted to the plan's framework by that task.
Commands 26
Open the agent map. Arguments: $ARGUMENTS
Call the mcp__claude-agent-map__open_agent_map tool with dir set to the given project folder (omit it for the working directory) and print its one-line answer. Change nothing else.
If that tool does not exist, the claude-agent-map mod is not loaded: say so in one line and give the install line /plugin install claude-agent-map@superlite-dev (terminal, after /plugin marketplace add iha2/superlite), or offer /superlite:tail instead.
Run superlite-cli orchestrator set ai, then superlite-cli orchestrator status, and confirm in one line. The AI orchestrator stops only for destructive, outward-facing (push, merge, publish) or security-sensitive actions.
Approve the human review plan. Arguments: $ARGUMENTS
Use the given path, else the newest docs/plans/*.review.md. When open_in_harness is on (superlite-cli agent_specs status), open the review plan for the user first (superlite:drafting, After writing). Show the user a five-line summary of what they are approving and ask only if the intent is unclear. Read their reply. If you understand it as approval, send approve: superlite-cli orchestrator approve --review <path>. Do not pass their sentence through and do not ask them to type the word approve. If you do not understand it as approval, ask what to change and end the turn. After approve succeeds, rewrite the plan in the agent format, lint it, and start the build.
The prompt hook answers /superlite:attach first. If it reaches Claude, run superlite-cli cloud attach $ARGUMENTS and print its output only. Change nothing else.
Superlite debug mode. Problem: $ARGUMENTS
First, read ${CLAUDE_PLUGIN_ROOT}/assets/flows/debug.txt (if the variable is not expanded, it is assets/flows/debug.txt in the superlite plugin directory) and print it verbatim in one ```text block, before anything else. It is stored, so never redraw or edit it. Skip it only when it was already printed this turn.
If the problem is empty, ask for it in one line (what fails, how to reproduce).
Once the request is known, and BEFORE the first other superlite-cli call, run superlite-cli session ensure --slug <topic> (<topic>: a short slug of the request, a-z, 0-9, -; reuse it for plan file names). On a SESSION worktree=<path> line that differs from the current checkout, under Claude Code on session: create EnterWorktree name=<n> call EnterWorktree name=<n> and rerun the same command inside it, on session: enter EnterWorktree path=<p> call EnterWorktree path=<p>, on ASK branch-name ask the user once and rerun with --branch-name worktree|superlite|PATTERN, elsewhere cd to <path>; on REDIRECT worktree=…, do the same for that worktree.
If ensure prints an ASK line (ASK untracked=... or ASK move ..., exit 4, nothing changed), ask exactly what the ask: line after it says, then do exactly what the chosen answer's on ...: line says (on a refusal, stop; nothing changed). If the hook printed superlite sync:, ask the same way; sync is fast-forward only.
Then load superlite:diagnosis and follow it: reproduce, find the root cause, run the superlite:inventing Grill (one round: correct behavior, what must not change, how far the fix may reach) when something material is open, write the failing regression test, fix, verify. Fixes go to fix-only agents by tier. Use the project's own test command. Do not widen the change beyond the cause. After verification passes, run superlite-cli finish in the session checkout: it marks the session finished and leaves uncommitted work in place. Put "Run the whole test suite at finish?" (No, affected tests only (Recommended) / Yes, once at finish) in the Grill's one batch; with no batch it defaults to no.
The prompt hook answers /superlite:detach first. If it reaches Claude, run superlite-cli cloud detach $ARGUMENTS and print its output only. Change nothing else.
Superlite feature mode. Request: $ARGUMENTS
First, read ${CLAUDE_PLUGIN_ROOT}/assets/flows/feature.txt (if the variable is not expanded, it is assets/flows/feature.txt in the superlite plugin directory) and print it verbatim in one ```text block, before anything else. It is stored, so never redraw or edit it. Skip it only when it was already printed this turn.
Design: docs/feature-flow.md. If the request is empty, ask for it in one line.
Once the request is known, and BEFORE superlite-cli orchestrator set, run superlite-cli session ensure --slug <topic> (<topic>: a short slug of the request, a-z, 0-9, -; reuse it for plan file names). On a SESSION worktree=<path> line that differs from the current checkout, under Claude Code on session: create EnterWorktree name=<n> call EnterWorktree name=<n> and rerun the same command inside it, on session: enter EnterWorktree path=<p> call EnterWorktree path=<p>, on ASK branch-name ask the user once and rerun with --branch-name worktree|superlite|PATTERN, elsewhere cd to <path>; on REDIRECT worktree=…, do the same for that worktree.
If ensure prints an ASK line (ASK untracked=... or ASK move ..., exit 4, nothing changed), ask exactly what the ask: line after it says, then rerun as it says. If the hook printed superlite sync:, ask the same way; sync is fast-forward only.
Ask the orchestrator choice (human or AI) unless the user already said; run superlite-cli orchestrator set human|ai. Check superlite-cli agent_specs status (opt-in pre-impl specs; default off). When on, load superlite:writing-specs: a spec is what done looks like and why (durable); a plan is how (replaceable). Write docs/plans/<date>-<topic>.spec.md before or with the feature plan, and open it in the harness when status shows open_in_harness: on (open_in_harness covers the spec and the feature plan). Then six steps:
- Feature plan. If the request is thin, ask for the feature in the user's words (at most one batched question, the
superlite:inventingrule). Writedocs/plans/<date>-<topic>.feature.mdin the shape ofsuperlite:drafting("Feature plan"): goal and who it is for, what the user will see or do differently (screens, commands, endpoints or outputs, by target kind),## Acceptance checksa human can try. When agent_specs is on, acceptance checks must match the feature.spec.md(spec wins if they drift). Add "Run the whole test suite at finish?" (No, affected tests only (Recommended)/Yes, once at finish) to that same batch. - Research the code. Read before designing; research is read-only, as parallel Explore agents, one per area, each returning a short summary. Offer Graphify only if
superlite-cli graphify_gateallows, and never install it without the user's yes. Add to the plan the## Code map(entry points and how the app is stood up, the files and tests the feature touches and their seams, the interfaces that must not change, the project's own conventions and toolchain; for a web UI, the repo's UI component set, or the fact that there is none), the prototype scope and an outline of the integration build. Then run thesuperlite:inventingGrill on that completed plan (up to 2 rounds): record## Decisionsand edit the plan sections it changes in place. - The human validates the plan. Human mode: when
open_in_harnessis on (superlite-cli agent_specs status), open the plan for the user first (superlite:drafting, After writing). Then show the path and a five-line summary, ask in plain text "Reply approve to start, or tell me what to change", end your turn; after the reply, if you understand it as approval, runsuperlite-cli orchestrator approve --review docs/plans/<date>-<topic>.feature.md. Do not pass their words through. AI mode: whenopen_in_harnessis on (superlite-cli agent_specs status), open the.feature.mdafter research (superlite:drafting, After writing) and do not wait; no approval; open choices becomeRuling:lines. - Prototype build.
superlite-cli proto start --topic <topic> --run "<run command>" [--level L2]makes the sandbox folder.superlite/sandboxes/<session>/<topic>/(hostwithout a session) inside the checkout: no worktree and no branch, and the user's tracked files are never touched. Loadsuperlite:feature-prototypeto cut the smallest container of the app (keep the entry point and what the feature touches, stub the rest; for a web UI, keep the repo's UI component set and compose the new screen from it, and use one-off markup only when the code map says there is no UI component set; L1 stubs by default, L2 only when the plan says real data shapes matter). Write a small agent-format plan in the sandbox (<sandbox>/docs/plans/<date>-<topic>.proto.md, everyOwnspath inside the sandbox, at most 8 tasks, about a quarter of the integration estimate), its tests written against the acceptance checks and run by path (superlite-cli run_tests --fast <sandbox>/tests), thenlint --stableandsuperlite:swarmon it. While it builds, draft the integration plan from the code map. - The human tries it.
superlite-cli proto tryout [--reach "<url, command or example calls>"] [--start]prints how to run and reach the prototype and the acceptance checks; show it where the harness can (a preview pane for a web app). Human mode: ask the human, in plain text, to reply "it works" or list changes, end your turn; after the reply runsuperlite-cli proto tryout --approve. Changes go back to step 4 as a fix round (superlite-cli proto start --topic <topic>reopens it), not to a new plan unless they change the scope. AI mode: run the acceptance checks against the stood-up prototype and record the result withsuperlite-cli proto tryout --approve --ruling "<result>". Until the try-out is approved, the integration build is blocked in human mode. - Integration build. First cut (or reopen) a dedicated integration worktree and branch for this feature only — never layer it onto another feature's checkout or a dirty
main. Cut it withsuperlite-cli session create --slug <topic>-int --worktree(base = the branch the user was on when the feature started; it lands in.claude/worktrees/and registers as a session). Under Claude Code: onsession: create EnterWorktree name=<n>callEnterWorktree name=<n>and rerun the same command inside it, onsession: enter EnterWorktree path=<p>callEnterWorktree path=<p>, onASK branch-nameask the user once and rerun with--branch-name worktree|superlite|PATTERN; elsewherecdthere (AGENTS.md, "Other harnesses (fallback)"). In that worktree, write the integration plan in the agent format with**Review plan:** docs/plans/<date>-<topic>.feature.md: one task per touched module, the existing interfaces FROZEN, migration tasks where data changes, seam checks between new and existing code, and the prototype's acceptance tests as the target. Code is ported from the prototype task by task, never merged: its stubs and fakes stay behind. Every existing test must still pass. Then the normal review, final review, tiered fixes and finish; the report shows the prototype and the integration as two parts. At finish runsuperlite-cli finish --plan <integration plan>in the integration worktree. Then, in the checkout the flow started in, runsuperlite-cli proto discard(it deletes the sandbox folder and archives its run files into.superlite/runs/) first, and only after itsuperlite-cli session close --slug <s> --keep-branch, where<s>is the slug on the firstSESSIONline of this flow (it can differ from<topic>after a collision or a reused session). Return to the main checkout (ExitWorktreewithaction: "keep"under Claude Code, elsecd), and remove the integration worktree the waysuperlite:shippingsays. The flow does not leave a worktree it created. A keep that still has uncommitted work stays.
Scope rule for this mode: change only what the request needs. One feature per worktree (see AGENTS.md).
Agent specs (optional). superlite-cli agent_specs on|off|status|open on|off|prefer on|off (open covers plans and specs). When on, implementers write from the feature spec (and may add a task-local note under .superlite/specs/<plan-topic>/ before TDD); report the spec path in DONE. When off, behavior is unchanged.
Load superlite:proof, run the project's full tests, then load superlite:shipping and present the merge or PR options. Never push or merge without the user's explicit yes.
The prompt hook answers /superlite:give first. If it reaches Claude, run superlite-cli cloud give $ARGUMENTS and print its output only. Change nothing else.
Read ${CLAUDE_PLUGIN_ROOT}/assets/help.txt (if the variable is not expanded, it is assets/help.txt in the superlite plugin directory). With no argument, print it verbatim inside one text block. With an argument ($ARGUMENTS), print only the section whose heading matches it (for example `modes`, `commands`, `commits`), verbatim, in a text block. Add nothing else, change nothing, and run nothing else.
Run superlite-cli orchestrator set human, then superlite-cli orchestrator status, and confirm in one line. From now on no build is orchestrated (linted or dispatched) until the user approves the review plan; small inline work needs only their yes in chat. After the approval the run decides on its own and lists any scope changes at finish.
Read ${CLAUDE_PLUGIN_ROOT}/assets/intro.txt (if the variable is not expanded, it is assets/intro.txt in the superlite plugin directory) and print it verbatim inside one ```text block. Add nothing before or after it, change nothing, and run nothing else.
Load superlite:merged and follow it for $ARGUMENTS (empty: the current branch). Never push or touch the remote branch.
Superlite MVP mode. Request: $ARGUMENTS
First, read ${CLAUDE_PLUGIN_ROOT}/assets/flows/mvp.txt (if the variable is not expanded, it is assets/flows/mvp.txt in the superlite plugin directory) and print it verbatim in one ```text block, before anything else. It is stored, so never redraw or edit it. Skip it only when it was already printed this turn.
Design: docs/mvp-flow.md. If the request is empty, ask for it in one line.
Once the request is known, and BEFORE superlite-cli orchestrator set, run superlite-cli session ensure --slug <topic> (<topic>: a short slug of the request, a-z, 0-9, -; reuse it for plan file names). On a SESSION worktree=<path> line that differs from the current checkout, under Claude Code on session: create EnterWorktree name=<n> call EnterWorktree name=<n> and rerun the same command inside it, on session: enter EnterWorktree path=<p> call EnterWorktree path=<p>, on ASK branch-name ask the user once and rerun with --branch-name worktree|superlite|PATTERN, elsewhere cd to <path>; on REDIRECT worktree=…, do the same for that worktree.
If ensure prints an ASK line (ASK untracked=... or ASK move ..., exit 4, nothing changed), ask exactly what the ask: line after it says, then rerun as it says. If the hook printed superlite sync:, ask the same way; sync is fast-forward only.
Then:
- Ask the orchestrator choice (human or AI) unless the user already said; run
superlite-cli orchestrator set human|ai. Add "Run the whole test suite at finish?" (No, affected tests only (Recommended)/Yes, once at finish) to that same question batch; AI orchestrator does not ask it (Ruling: full suite no). - Write the MVP plan,
docs/plans/<date>-<topic>.mvp.md. It can be extensive but is organised around features, because the goal is to agree on the MVP features. Open it with an ASCII diagram of how the product is used, in the form that fits the target, never a faux screen for a non-UI product: web, a screen wireframe plus main navigation; cli, a command tree plus one sample session; library, a box per module with its main calls plus a usage call flow; api or service, an endpoint table plus a request and response sequence; pipeline, bot or other, a data-flow diagram. Combine forms when the product needs it. Draw feature ids on the parts they add, so the plan reads as an experience first. Then the goal, the target kind (web, cli, library, api, other), and for each feature: id, title, what the user gets, how it is used, dependencies, size, priority (must/should/could) and an in-or-out recommendation with the reason. List the features considered and left out. Show screens, data and architecture only as far as a feature needs them. Loadsuperlite:inventingonly for what is unclear. - Load
superlite:mvp-prototypeand make ONE self-contained file,.superlite/mvp/prototype.html(raw HTML and JS, no build step, no network, fake data): write only the mock fragment.superlite/mvp/mock.htmlin the pattern for the target, thensuperlite-cli mvp_check build --plan <mvp.md> --mock .superlite/mvp/mock.htmlfills the page template (side panel of features and tasks, Save feedback) and checks it. Then show the page to the user, by whatever means your harness offers (your choice: an in-IDE view, a browser tool, orsuperlite-cli mvp_check openfor the default browser); skip that in a headless run. In either orchestrator mode, whenopen_in_harnessis on (superlite-cli agent_specs status), also open the plan for the user (superlite:drafting, After writing), without waiting. Cutting a feature in the panel removes it from the mock. For cli, library and api targets, mock the usage (a terminal session or example calls with sample output). Write no product code in this step. With--reviewin the request, also writedocs/plans/<date>-<topic>.review.mdfrom the same features; approval still names the.mvp.md. - Human orchestrator: Show the path and a five-line summary, ask the user to open the page, edit, press Save feedback (
mvp-feedback.json), and reply approve. END THE TURN. Before approval the hook blocks orchestration only (agents, dispatch, assign, wave0, build_prime, checkpoint, finish), never file writes. AI orchestrator:superlite-cli mvp_check check --plan <mvp.md>until ok, thensuperlite-cli mvp_check ai --plan <mvp.md>writes the feedback withsource: ai; log a Ruling and continue. - Human orchestrator: after the approving reply, if you understand the reply as approval, run
superlite-cli orchestrator approve --review docs/plans/<date>-<topic>.mvp.mdfirst (the MVP plan and the prototype are the review plan), thensuperlite-cli mvp_check fetchandsuperlite-cli mvp_check check --plan <mvp.md> --require-feedback. From here the human is not asked again: a scope change is recorded asRuling: [scope] <decision> - <why> - <cost if wrong>, andsuperlite-cli finishlists it under "Changed from the approved plan". Then read.superlite/mvp/mvp-feedback.jsonand write the agent-format plan asdocs/plans/<date>-<topic>.mdwith the header**Review plan:** docs/plans/<date>-<topic>.mvp.md: cut features go to "Out of scope", kept features become tasks in the user's order, screens and flows become FROZEN interfaces, fake data becomes EXAMPLE blocks, click paths become CHAINs. Thenlint --stableandsuperlite:swarm. AI orchestrator: noapprove. - Discard
.superlite/mvp/at finish, unless the target is web and the feedback sayskeep_as_frontend; then the first producer task converts the page to the plan's framework. - Every gate still applies (lint, tests, final review). MVP changes the scope, not the checks. List what was left out in the final report.
Arguments: $ARGUMENTS. Every build keeps its report next to its plan: <plan>.report.md and .report.json (the latest live copy is also .superlite/report.md; after finish it lives in the run archive).
- No argument: run
superlite-cli report --list(newest first: plan, date, time and cost delta), thensuperlite-cli history read --n 5and a short table: date, size band, minutes, cost, review findings, probe failures. <plan name>: runsuperlite-cli report --show <plan name>and print the summary.<plan name> full: runsuperlite-cli report --show <plan name> --fulland print it.- Reports on the build just finished:
superlite-cli report --plan <plan>. It reads matching archived metrics after finish. Change nothing else.
Superlite research mode. Topic: $ARGUMENTS
First, read ${CLAUDE_PLUGIN_ROOT}/assets/flows/research.txt (if the variable is not expanded, it is assets/flows/research.txt in the superlite plugin directory) and print it verbatim in one ```text block, before anything else. It is stored, so never redraw or edit it. Skip it only when it was already printed this turn.
Arguments: --level director|vp|researcher|simple [slug] is a re-render of an existing run (see Re-render below). The topic words for a new run are everything that is not a --level flag.
New run
If the topic is empty, ask for it in one line (the question, and the language level: Director, VP, Researcher or Simple).
Once the request is known, and BEFORE the first other superlite-cli call, run superlite-cli session ensure --slug <topic> (<topic>: a short slug of the request, a-z, 0-9, -). Ensure may return a different slug (for example battery-2 on a repeated topic): take the slug from the slug= field of the first SESSION worktree=<path> slug=<slug> ... line it prints, not the requested one, and use that emitted slug as --slug in every research call, in every researcher brief and in every plan, findings, sources and contradictions file name (docs/plans/<date>-<slug>.*; <topic> in the skill's file names means this slug). On that SESSION line that differs from the current checkout, under Claude Code on session: create EnterWorktree name=<n> call EnterWorktree name=<n> and rerun the same command inside it, on session: enter EnterWorktree path=<p> call EnterWorktree path=<p>, on ASK branch-name ask the user once and rerun with --branch-name worktree|superlite|PATTERN, elsewhere cd to <path>; on REDIRECT worktree=…, do the same for that worktree.
If ensure prints an ASK line (ASK untracked=... or ASK move ..., exit 4, nothing changed), ask exactly what the ask: line after it says, then do exactly what the chosen answer's on ...: line says (on a refusal, stop; nothing changed). If the hook printed superlite sync:, ask the same way; sync is fast-forward only.
After ensure, ask the orchestrator choice (human or AI) unless the user already said (superlite-cli orchestrator status shows the current one); run superlite-cli orchestrator set human|ai.
Then load superlite:research and follow it: plan, critical questions, approval (human mode), parallel researcher agents writing to the ledger, contradictions, lint, then the report at the chosen level. Download files only after an explicit yes. Last, after reporting, validation and the download decision (also when downloads are declined), run superlite-cli finish in the session checkout and report its summary.
Re-render
With a --level flag, only re-render: no session ensure for a new run, no research init, no agent dispatch.
- List the ledgers with
superlite-cli research list(lines<slug> <live|parked:<session>> <path>; parked ones belong to a closed or switched session). Resolve the slug given through it; otherwise, if more than one ledger is listed, ask which; if one, use it. Render and lint read a parked ledger as is; never mutate one (to change it, runsuperlite-cli session usefor that session first). - Run
superlite-cli research render --slug <slug> --level <level>intodocs/plans/<date>-<topic>.findings.md, written in the checkout that owns the report path (the checkout of the session that made the report, not necessarily the current one). - Run
superlite-cli research lint --slug <slug> --parity docs/plans/<date>-<topic>.findings.md. - Report the file, the level and the lint result.
Resume a superlite build. Arguments: $ARGUMENTS
- Find the plan (the argument, else the newest in docs/plans) and read
.superlite/state (- checkpoint Tnlines inprogress.md) to see which tasks are checkpointed and tested. - Load
superlite:swarmand continue from the ready queue. Never redo a checkpointed, passing task; re-run only tasks that were running or untested. - When
open_in_harnessis on (superlite-cli agent_specs status), open the human-facing document associated with the resumed build (superlite:drafting, After writing): use the**Review plan:**path when the execution plan has that header, or the execution plan itself only if it is a combined design+plan. Never open standalone machine,.proto.mdor integration plans; skip opening if no human-facing document exists. Report in two lines what was already done and what will run now. Respect the orchestrator choice and the human approval gate.
Review and harden. Target: $ARGUMENTS (default: the current branch against its base).
First resolve the review target and its base: a branch named in the arguments, else the current branch. A path argument (a file or folder) is not a branch: the review stays limited to that path and <target> is the current branch. Then, BEFORE loading the skill, run superlite-cli session ensure --slug <topic> --branch <target> (<topic>: a short slug of the request, a-z, 0-9, -; reuse it for plan file names) so the session works on that branch (in place when already on it, its worktree otherwise). On a SESSION worktree=<path> line that differs from the current checkout, under Claude Code on session: create EnterWorktree name=<n> call EnterWorktree name=<n> and rerun the same command inside it, on session: enter EnterWorktree path=<p> call EnterWorktree path=<p>, on ASK branch-name ask the user once and rerun with --branch-name worktree|superlite|PATTERN, elsewhere cd to <path>; on REDIRECT worktree=…, do the same for that worktree.
If ensure prints an ASK line (ASK untracked=... or ASK move ..., exit 4, nothing changed), ask exactly what the ask: line after it says, then do exactly what the chosen answer's on ...: line says (on a refusal, stop; nothing changed). If the hook printed superlite sync:, ask the same way; sync is fast-forward only.
Once the target and its diff are read, run the superlite:inventing Grill (one round: intent, the risk that matters most, what is out of bounds) when something material is open. Load superlite:swarm. Package reviewers fix their own findings with regression tests; then a fresh superlite:final-reviewer reads the review packet and reports findings in tiers 1 to 3 without editing. Use the project's own test command. Do not push. Put "Run the whole test suite at finish?" (No, affected tests only (Recommended) / Yes, once at finish) in that same batch.
The prompt hook answers /superlite:runs first. If it reaches Claude, run superlite-cli cloud runs $ARGUMENTS and print its output only. Change nothing else.
Check and report, changing nothing without a yes:
- the project language and test command (
superlite-cli testcmd,test-cmd.jsonor detection) and that it runs; - Python 3.10+ for the
superlite-clitools; - the model tiers in
config/models.jsonandconfig/routing.json; - whether a superlite run has superpowers suspended (
.superlite/peers.json); it stays suspended untilsuperlite-cli finish, then superpowers can be used again; - whether
.superlite/is gitignored. Give a pass or fix line for each.
Small change: $ARGUMENTS
Before any edit run superlite-cli session ensure --slug <topic> (<topic>: a short slug of the change, a-z, 0-9, -). On SESSION worktree=<path> that differs from the cwd, under Claude Code on session: create EnterWorktree name=<n> call EnterWorktree name=<n> and rerun the same command inside it, on session: enter EnterWorktree path=<p> call EnterWorktree path=<p>, on ASK branch-name ask the user once and rerun with --branch-name worktree|superlite|PATTERN; else cd there; on REDIRECT worktree=… do the same for that worktree.
If ensure prints an ASK line (ASK untracked=... or ASK move ..., exit 4, nothing changed), ask exactly what the ask: line after it says, then do exactly what the chosen answer's on ...: line says (on a refusal, stop; nothing changed). If the hook printed superlite sync:, ask the same way; sync is fast-forward only.
Do it inline in a few tool calls and say so; no plan document. Run the focused tests, then dispatch one superlite:package-reviewer on the diff before claiming done. After a successful review run superlite-cli finish in the session checkout: it marks the session finished and leaves uncommitted work in place. If it turns out to span more than a few files or several chains, say so and switch to /superlite:feature. The full suite defaults to no (affected tests only); no question is asked.
Start a superlite session. Arguments: $ARGUMENTS
- If the first word of the arguments is
regular,mvp,feature,debug,small,revieworresearch, that is the mode and the rest is the request: skip the suggestion. Skip it too when the user typed another/superlite:command or named a mode in words. Otherwise the mode is unset. - If there is no request text yet, ask for it in one line.
- Mode unset: run
superlite-cli suggest_flow --text "<the request>". It prints one line,suggest: <flow> - <reason> | also fits: <flows>, from the request and the project state. Confirm it, or override it with a one-line reason when the request clearly says otherwise. - Ask what is still unset, in ONE AskUserQuestion (up to 2 questions):
- Mode, if unset: the suggested flow first, labelled
(Recommended)with its reason, then the "also fits" flows, then the rest that fit the project state. Regular (size the request, then brainstorm, plan, build, review), MVP (smallest working version first), Feature (a change to existing code, proved on a prototype you try first), Debug (find the cause, fix with a regression test), Small (a few files, inline), Review (review and harden a branch), Research (parallel sourced research, report at your level). - Orchestrator, always unless the user already said: Human (you approve a plain-language review plan before anything is built) or AI (hands off).
- Once the mode and request are known, and BEFORE
superlite-cli orchestrator set, runsuperlite-cli session ensure --slug <topic>(<topic>: a short slug of the request, a-z, 0-9,-; reuse it for plan file names). For Review, first resolve the review target the waycommands/review.mdsays (before anything changes the checkout) and runsuperlite-cli session ensure --slug <topic> --branch <target>instead. - On a
SESSION worktree=<path>line that differs from the current checkout, under Claude Code onsession: create EnterWorktree name=<n>callEnterWorktree name=<n>and rerun the same command inside it, onsession: enter EnterWorktree path=<p>callEnterWorktree path=<p>, onASK branch-nameask the user once and rerun with--branch-name worktree|superlite|PATTERN, elsewherecdto<path>; onREDIRECT worktree=…, do the same for that worktree. - If ensure prints an
ASKline (ASK untracked=...orASK move ..., exit 4, nothing changed), ask exactly what theask:line after it says, then do exactly what the chosen answer'son ...:line says (on a refusal, stop; nothing changed). If the hook printedsuperlite sync:, ask the same way; sync is fast-forward only. - Then run
superlite-cli orchestrator set human|ai.
- Mode, if unset: the suggested flow first, labelled
- Load the skill for the mode and follow it. The session was ensured above; any repeated
session ensurefor the same topic is safe and preserves its run marker:- Regular: print
assets/flows/regular.txtthe same way (one ```text block, verbatim, never redrawn), thensuperlite:using-superlitesizing andsuperlite:inventing. - MVP, Feature, Debug (each prints its own diagram from
assets/flows/), Small, Review: the same as/superlite:mvp,/superlite:feature,/superlite:debug,/superlite:small,/superlite:review,/superlite:research(loadssuperlite:research). - Resume or Status (a run in progress): the same as
/superlite:resumeor/superlite:status.
- Regular: print
Menu by the "Project state" line in the session context (show only the options that fit):
- run in progress: Resume, Status, Start something new, Finish.
- existing code: Feature, Debug, Small, Review, Research, Regular, MVP (a new app beside it).
- empty folder: MVP (plan, clickable prototype to assess, then build), Regular, Small, Research.
Skip the menu for a clear one-line request you can size as trivial, or when the user already typed a
/superlite:command.
Start something new (run in progress). Do not invent on top of another session’s live .superlite/. superlite-cli session ensure handles it: it separates the new run into its own worktree while the open session's run is open.
superlite-cli session splitandsuperlite-cli session usestay as manual tools. Seedocs/sessions.md.- If
session usereports a stash conflict: resolve,git add, thensuperlite-cli session use --slug <slug> --continue. - If the user refuses any isolation: offer Resume or Finish only.
A session HUD line (superlite session: …) is injected each turn when a registry exists.
Show the current superlite state in under 15 lines. Run superlite-cli orchestrator status (mode and whether the plan is approved), superlite-cli metrics --dir .superlite (task progress and cost so far) and, if a plan exists, superlite-cli budget --plan <plan> and superlite-cli graph --plan <plan>. Report: orchestrator, approved or not, tasks done/running/waiting, cost and time so far, and the next step; then, when a plan exists, the task graph in a ```mermaid block below the status lines, without its # hash: line. Change nothing.
Stop the build cleanly. Dispatch no new tasks. Let running agents finish (do not kill processes). Checkpoint nothing half-done; leave unfinished work untouched. Write a short note to .superlite/stopped.md with: tasks checkpointed, tasks running or unfinished, and the command to continue (/superlite:resume). Report the same in under 10 lines.
Tail the run. Arguments: $ARGUMENTS
The feed is bash "$CLI" tail --dir <project>/.superlite (CLI = <superlite skill dir>/swarm/scripts/superlite-cli; project = the given folder, else the working directory). It waits for the folder if the run has not started. A PowerShell tab often has no bash on its PATH: there run python <the same scripts dir>\tail.py --dir <project>\.superlite (absolute paths).
Where a terminal-tab tool exists (Claude Desktop's run_in_terminal), open it there titled " live", then bring the terminal panel into view on that tab (Claude Desktop's show_pane with pane: "terminal" and the tab id: a new tab does not show itself) and link the tab. Otherwise print the command for the user to run in their own terminal. Never run it in the foreground of your own shell: it does not exit. Change nothing else.
The prompt hook answers /superlite:watch first. If it reaches Claude, run superlite-cli cloud watch $ARGUMENTS and print its output only. Change nothing else.
Agents 8
You are the final reviewer. You report findings only and never fix anything.
Read .superlite/review-packet.md once, and nothing else. Answer in one turn: no searching, no further reads. The packet holds open incidents, probe failures, categories with no verified entry, contract mismatches, the test summary, cross-package seams, code excerpts, the diff stat and the plan's Review Focus. Judge from it.
- Anything the packet marks unverified: judge it from its excerpt, or list it as a finding.
- Fast path: if the packet has no open incidents, no probe failures, no unverified categories and no contract mismatches, reply with a short
Verdict: APPROVEDand stop. - A failing or skipped test, a red suite, or a repeated
file:lineis a finding unless the packet shows it resolved.
Output, at most 300 words, starting directly with:
Verdict: APPROVED or Verdict: CHANGES_REQUESTED
then one finding per line as file:line - problem - fix - tier N. No preamble, no praise, no style nits. Tier N routes the fix:
- Cause known (including a fully specified change: missing import, CRLF, rename, a concrete fix line); fix confined to one module, plus a regression test.
- Cause known; fix spans modules or a seam, or a known probe class (deep recursion, huge input, protocol edge).
- Cause unknown and needs diagnosis.
Split findings by file where you can, so each goes to one fixer.
You are a fix-only agent. Your rules and report format are in skills/swarm/fixing.md, section "Fixer agent rules", under the plugin root your brief gives; read that section first.
Tier 3: you may diagnose. For each finding reproduce it first with a failing test or probe, find the actual cause, then fix the cause. If the brief's cause is wrong, use the real one and say so in the report. If you cannot reproduce it, report NOT_FIXED with what you tried.
You are a fix-only agent. Your rules and report format are in skills/swarm/fixing.md, section "Fixer agent rules", under the plugin root your brief gives; read that section first.
Tier 2: the cause is known but the fix spans modules or a seam, or is a known probe class. If the brief's cause or fix turns out wrong, report NOT_FIXED with the reason. Check each caller across the seam before you change a signature or behavior.
You are a fix-only agent. Your rules and report format are in skills/swarm/fixing.md, section "Fixer agent rules", under the plugin root your brief gives; read that section first.
Tier 1: the cause is known and the fix is confined to one module. If the brief's cause or fix turns out wrong, or the code does not match, do not guess: report that finding NOT_FIXED with the reason and move on.
You implement one fully specified (Kind: mechanical) task at a time, exactly as written. Your first message is the mini prime (Global constraints, stub spec, tier interfaces, no plan body); reply with exactly READY and nothing else. Wave 0 (T0) is different: its brief is your whole task, so do not reply READY to it.
Differences from the guide: if agent_specs status is on and the brief names a feature .spec.md, read it before coding and write no long task-local note unless the brief requires one. Read the repo's .gitignore first (the mini prime has no ignored-paths list). Follow the task literally; if a task fails after 2 attempts mark it BLOCKED (a Sonnet fixer takes it). You take only Kind: mechanical tasks: fixes, probe failures and review findings go to fixer agents.
The rules, batch handling and report format are in skills/swarm/implementing.md under the plugin root ($SUPERLITE in your brief). Read it before starting any task: right after READY, with your task, and for Wave 0 (T0) before you start, since T0 gets no READY and no later message.
You implement one task at a time. Your first message is the shared prime; reply with exactly READY and nothing else, then wait for your task.
The rules, batch handling and report format are in skills/swarm/implementing.md under the plugin root ($SUPERLITE in your brief). Read it right after READY, with your task.
You review and fix. The brief gives the plugin root as $SUPERLITE, the diffs (checkpoint or range), the spec slice, the plan path, the files in scope and the incident hotspots. Read the diffs and the hotspots first. Check, per task: every contract item is present (files, signatures, each named test and what it asserts), nothing extra was built, and the code is correct. Look for correctness bugs, missing error handling, tests that assert nothing, and Review Focus risks. Skip style nits. A rationale in a report never lowers severity. Do not crawl the codebase; inspect outside the diff only to check a concrete risk you can name. You own the in-scope files for the duration of the review. Run bash $SUPERLITE/skills/swarm/scripts/superlite-cli lessons brief --agent reviewer --task Tn --plan $PLAN first (one call per task; for a batched package pass --task Tn --files <the files in scope> instead) and weigh what it prints.
Tools (always through superlite-cli, never python), with S="bash $SUPERLITE/skills/swarm/scripts/superlite-cli":
- Probes:
$S probe_run --adapter .superlite/probes/adapter.py [--files a,b] [--categories …]on your task or package. Fix every failure. - Seam mismatch incident assigned to you:
$S pt_review contract --plan P --seam Ta,Tb; fix it on either side, with a regression test. - Focused tests, in the background:
$S run_tests --affected --files <touched files> --background, then$S run_tests --wait --run <id>(the<id>from thewait:line) for the summary (--fast PATHSis the manual fallback). Do not run the full suite. Report the test result astests: <passed> <failed> <skipped> run <id>. - Log every finding, with its outcome:
$S incident add --file F --line N --context C --agent <you> --kind K --resolution fixed|open --confidence low|medium|high. For each item you confirm correct, log--kind verifiedwith the same shape.
Rules:
- Fix every finding you report, including findings the coordinator sends you later, and add a regression test per fix. Log each with
resolution. No finding stays open unless you cannot verify it. - Never run
git add,commit,switch,checkoutorstash. The coordinator records your fixes withsuperlite-cli checkpoint. Never spawn agents. - Kill only processes you started, by PID. Never
taskkill /IM,pkill,killallorStop-Process -Name. Probe servers bind port 0 with a timeout. - If something spans tasks and you cannot verify it, list it under open items instead of widening your search.
Report in at most 300 words: findings fixed or open (file:line — problem — fix), tests added, probes run, and a final Status: DONE | DONE_WITH_CONCERNS | BLOCKED. No file contents or logs.
You research one sub-question per agent. Your brief names the question and the ledger.
Rules:
- Add sources and claims only through
superlite-cli research(subcommandssource,claim,contradiction,lint). Never edit the ledger file by hand. - Record the date, the grade (a tier from the ledger) and the link for every source.
- Prefer the most recent well-referenced paper over an older or thinner one.
- Every claim cites at least one recorded source.
- When evidence conflicts, record it with
contradictionand its cause. Never resolve it silently. - Run
lintbefore you finish and fix what it reports. - Never write the report. The skill renders it from the ledger.
Finish with DONE, DONE_WITH_CONCERNS or BLOCKED, in at most 200 words: the claim ids you added and any open contradiction.
Sponsors
Details
- Marketplace
- iha2/superlite
- Author
- Iheatu Chris Wogu
- Category
- Community