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-dev

Run it inside Claude Code after adding the marketplace with /plugin marketplace add iha2/superlite.

Contents

Discovered from source

Skills 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

  1. 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.
  2. Check what changed. Recent diffs, new dependencies, config and environment differences often point straight at the cause.
  3. 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.
  4. Hypothesize. State the single most likely root cause in one sentence: "X is wrong because Y". Base it on evidence, not hunch.
  5. 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.
  6. 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.
  7. 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 --full at 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:
    1. 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.
    2. When open_in_harness is on (superlite-cli agent_specs status), open the plan for the user first (After writing below; the harness's open row in using-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.
    3. 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, wave0 and build_prime refuse until then.
    4. Write the machine plan docs/plans/<date>-<topic>.md from the approved review plan, in the order below (same tasks and scope, header **Review plan:** <path>), then lint --stable, and dispatch the stable set in the same turn.
    5. 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 finish lists these under "Changed from the approved plan". AI orchestrator: no review plan, straight to the machine 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:

  1. 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.
  2. 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 wave0 builds 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 exact Produces lines, the correct Kind and 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.
  3. Producers first, with exact Produces lines. Lint resolves each Consumes against some task's Produces line, 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.
  4. 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.
  5. 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.
  6. 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.
  7. Mark the easy ones. A task that meets the Kind: mechanical rules gets Kind: mechanical and Model: haiku when you write it.
  8. Contract examples. Under every Produces another task consumes that returns structured data, add 2-3 e.g. lines: a call and its result with concrete values, in the plan's own language, for example e.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 reports EXAMPLE: for a consumer whose producer has none (a fix task until it does), and EDGE: for an edge that exists only for interfaces with examples: drop it, or run plan_tools prune before the first dispatch. Never say stubs cannot compute values: examples are the values.

Plan shape, in this order

  1. Header: Goal, Architecture, Tech stack, Spec path, **Detail:** contracts | tests | full (default tests), **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.
  2. Main diagram (always): Mermaid of components and data flow.
  3. File structure: every file and its one responsibility. Split by responsibility, not by layer, and follow the repo's patterns.
  4. Task graph (always, machine-readable): see below.
  5. Predicted schedule: generated, never hand-written.
  6. Sections, one per component or package: its tasks, a mini diagram only if the section interacts, and a **Probe entry:** line.
  7. Review Focus: the probe plan.
  8. 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

  1. Interface stubs in Wave 0. Wave 0 holds the skeleton (manifest, package inits, test config, shared error types) and interface stubs for every Produces another task consumes. plan_tools.py stubs generates them from your Produces lines, so write those lines exactly as module.function(args) -> ret or Class.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.
  2. 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 with CHAIN: when the predicted critical path is over 2.5 times its longest task (with 3 or more tasks on it). Stub more interfaces, or add Ruling: sequential - <why> when the order really is forced, such as a migration before its users.
  3. Keep every task inside the size band. The only measure is predicted time, held in config/predictor.json as size_band (low_min 1.5, high_min 6.0). Over high_min lint fails SIZE:: 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 prints NOTE: (consider merging with a related task in the same package) and never fails. predict --refit moves the band from measured task times. The 80k context ceiling stays.
  4. 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.
  5. 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.

FieldRule
OwnsExact paths, only this task's. Two tasks that can run at once never share a file.
ComponentsInteger count of components the task builds.
LOC ownedInteger estimate of lines this task writes.
Testsfast or slow (browser, server and I/O suites are slow, pure functions fast).
Kinddesign (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.
Modelhaiku 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. timepredict.py recomputes it from the four fields above, and the fields win on disagreement. Write them honestly.
Est. context18k + 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/ProducesExact names, parameter types and return types. An implementer reads only its own task, so this is how it learns what neighbors named things.
Review FocusCases from the Review Focus section that touch this task's files, as named tests (see below).
Test codeAt 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 typeGeneric categories
library / parser / evaluatordeep, numeric, encoding, state
CLIprotocol (commands and args), encoding, state, file
HTTP serviceprotocol, encoding, numeric, state
web UIprotocol via its API, encoding (rendering, XSS)
file I/O / generatorfile, encoding, deep
data pipelinenumeric, encoding, state, deep
concurrencystate (races, partial writes), protocol
authprotocol, 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 example call=minisheet.Workbook.set · run=python -m minisheet · serve=minisheet.server.create_server. Use call= 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 --review takes 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 tryout prints 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 is FROZEN; 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 an Owns list. 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 TARGET is 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 record Ruling: <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 the DISPATCH NOW: line, then patch the FIX tasks listed under --stable (edit or rewrite; keep dispatched blocks unchanged), rerun lint --stable, until only MISSED TARGET and NOTE: 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 when open_in_harness: on, open every finished human-facing plan (review, feature, MVP, combined design+plan) using the open row in using-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.md or integration plans.

Self-review checklist

Run it yourself, not as a subagent. Fix in place, with no re-review.

  1. Coverage: every spec requirement maps to a task.
  2. Placeholders: none.
  3. Type consistency: each Consumes line matches the Produces line of its owner. clearLayers in T3 and clearFullLayers in T7 is a bug.
  4. Graph: every edge is an execution dependency, with no cycles, and no two tasks that can run at once share a file.
  5. Measurable fields: every task has Components, LOC owned, Tests, Model.
  6. Review Focus: each package has an app type, categories and a Probe entry, and each task carries the cases for its files.
  7. 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

ThoughtReality
"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

KindKeepStubThe try-out
webthe app shell, routing, the pages the feature changes, the repo's UI component set, their API callsthe backend behind those calls (a fake handler or fixture data), auth, analyticsa URL and port; show it in a preview pane
clithe entry point, argument parsing, the commands the feature adds or changesthe file system or network the command reaches (a temp folder, fixtures)a terminal session: the commands to type and what they print
librarythe public modules the feature extends and their callers' typesheavy dependencies the new calls do not needexample calls with their results, or a short script
apithe server start, the routes the feature touches, request and response modelsthe 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 formatsthe 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: PYTHONPATH or a sys.path insert pointing at the checkout's source.
  • Node: tsconfig paths, or a relative import out of the sandbox.
  • Go: a replace directive in the sandbox's go.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 L2 to superlite-cli proto start.
  • Never real secrets or production data in either level.

The prototype plan

  • When superlite-cli agent_specs status is on, keep the feature .spec.md in 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, whose Owns paths 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>" (or superlite-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: or Assumption:.
  • 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. When agent_specs is on, keep the feature .spec.md consistent: reconcile any ruling that changes scope into it, or do not make that ruling (the spec wins).
  • The result is not a file: a ## Decisions section 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:

  1. 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. Invoke superlite:drafting for the plan half and append it to the same file. If the user named a different location, use theirs. With an AI orchestrator, when open_in_harness is on (superlite-cli agent_specs status), open the doc for the user after writing it (superlite:drafting, After writing) and do not wait.
  2. 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.
  3. With a human orchestrator: When open_in_harness is 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 with superlite-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. Run bash <skill-dir>/../swarm/scripts/superlite-cli graphify_gate; when it reports needs_install: true, add the Graphify install opt-in (uv tool install graphifyy) to that same question. Never install without a yes.
  4. On approval, invoke superlite:swarm once, in this session: this session is the one coordinator. It runs lint --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

ThoughtReality
"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 through bash <skill-dir>/../swarm/scripts/superlite-cli session status --json or <hub>/.superlite/session-store/<slug>/session.json and use its recorded branch; only fall back to superlite/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 to git 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 its baseRefName as 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 --short there is not empty), its session row in session status reports stash:yes, or git 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 (ExitWorktree with action: "keep" under Claude Code, else cd to the main checkout), then from the main checkout run bash <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 an ASK line (exit 4, nothing changed), ask exactly what its ask: line says and do what the chosen on ...: line says. A Claude-created worktree is not removed by close: end it with ExitWorktree remove, as superlite:shipping step 7 says.
  • No session, but the branch is checked out: if the user chose to discard its uncommitted work above, first run git reset --hard and git clean -fd in 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 of superlite:shipping does.

4. Update the base branch

git fetch --prune origin, then fast-forward only:

  • The base is checked out in a clean, unoccupied checkout (session status lists 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>. -D is 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 gh has 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-edit marks a label the user may retype (never on the same element as data-go). data-sl-order on a container reorders its data-feature children with the panel's order.
  • Fake data inline. No http:// or https:// anywhere (write api.example/notes or /notes), no fetch, 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.

proofresearchshippingswarmtestingupgrade-scanusing-superlitewriting-specs

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:

  1. Feature plan. If the request is thin, ask for the feature in the user's words (at most one batched question, the superlite:inventing rule). Write docs/plans/<date>-<topic>.feature.md in the shape of superlite: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 checks a 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.
  2. 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_gate allows, 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 the superlite:inventing Grill on that completed plan (up to 2 rounds): record ## Decisions and edit the plan sections it changes in place.
  3. The human validates the plan. Human mode: when open_in_harness is 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, run superlite-cli orchestrator approve --review docs/plans/<date>-<topic>.feature.md. Do not pass their words through. AI mode: when open_in_harness is on (superlite-cli agent_specs status), open the .feature.md after research (superlite:drafting, After writing) and do not wait; no approval; open choices become Ruling: lines.
  4. Prototype build. superlite-cli proto start --topic <topic> --run "<run command>" [--level L2] makes the sandbox folder .superlite/sandboxes/<session>/<topic>/ (host without a session) inside the checkout: no worktree and no branch, and the user's tracked files are never touched. Load superlite:feature-prototype to 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, every Owns path 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), then lint --stable and superlite:swarm on it. While it builds, draft the integration plan from the code map.
  5. 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 run superlite-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 with superlite-cli proto tryout --approve --ruling "<result>". Until the try-out is approved, the integration build is blocked in human mode.
  6. 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 with superlite-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: 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 there (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 run superlite-cli finish --plan <integration plan> in the integration worktree. Then, in the checkout the flow started in, run superlite-cli proto discard (it deletes the sandbox folder and archives its run files into .superlite/runs/) first, and only after it superlite-cli session close --slug <s> --keep-branch, where <s> is the slug on the first SESSION line of this flow (it can differ from <topic> after a collision or a reused session). Return to the main checkout (ExitWorktree with action: "keep" under Claude Code, else cd), and remove the integration worktree the way superlite:shipping says. 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:

  1. 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).
  2. 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. Load superlite:inventing only for what is unclear.
  3. Load superlite:mvp-prototype and 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.html in the pattern for the target, then superlite-cli mvp_check build --plan <mvp.md> --mock .superlite/mvp/mock.html fills 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, or superlite-cli mvp_check open for the default browser); skip that in a headless run. In either orchestrator mode, when open_in_harness is 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 --review in the request, also write docs/plans/<date>-<topic>.review.md from the same features; approval still names the .mvp.md.
  4. 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, then superlite-cli mvp_check ai --plan <mvp.md> writes the feedback with source: ai; log a Ruling and continue.
  5. Human orchestrator: after the approving reply, if you understand the reply as approval, run superlite-cli orchestrator approve --review docs/plans/<date>-<topic>.mvp.md first (the MVP plan and the prototype are the review plan), then superlite-cli mvp_check fetch and superlite-cli mvp_check check --plan <mvp.md> --require-feedback. From here the human is not asked again: a scope change is recorded as Ruling: [scope] <decision> - <why> - <cost if wrong>, and superlite-cli finish lists it under "Changed from the approved plan". Then read .superlite/mvp/mvp-feedback.json and write the agent-format plan as docs/plans/<date>-<topic>.md with 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. Then lint --stable and superlite:swarm. AI orchestrator: no approve.
  6. Discard .superlite/mvp/ at finish, unless the target is web and the feedback says keep_as_frontend; then the first producer task converts the page to the plan's framework.
  7. 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), then superlite-cli history read --n 5 and a short table: date, size band, minutes, cost, review findings, probe failures.
  • <plan name>: run superlite-cli report --show <plan name> and print the summary.
  • <plan name> full: run superlite-cli report --show <plan name> --full and 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.

  1. 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, run superlite-cli session use for that session first).
  2. Run superlite-cli research render --slug <slug> --level <level> into docs/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).
  3. Run superlite-cli research lint --slug <slug> --parity docs/plans/<date>-<topic>.findings.md.
  4. Report the file, the level and the lint result.

Resume a superlite build. Arguments: $ARGUMENTS

  1. Find the plan (the argument, else the newest in docs/plans) and read .superlite/ state (- checkpoint Tn lines in progress.md) to see which tasks are checkpointed and tested.
  2. Load superlite:swarm and continue from the ready queue. Never redo a checkpointed, passing task; re-run only tasks that were running or untested.
  3. When open_in_harness is 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.md or 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.json or detection) and that it runs;
  • Python 3.10+ for the superlite-cli tools;
  • the model tiers in config/models.json and config/routing.json;
  • whether a superlite run has superpowers suspended (.superlite/peers.json); it stays suspended until superlite-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

  1. If the first word of the arguments is regular, mvp, feature, debug, small, review or research, 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.
  2. If there is no request text yet, ask for it in one line.
  3. 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.
  4. 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, run superlite-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 way commands/review.md says (before anything changes the checkout) and run superlite-cli session ensure --slug <topic> --branch <target> instead.
    • 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 run superlite-cli orchestrator set human|ai.
  5. Load the skill for the mode and follow it. The session was ensured above; any repeated session ensure for the same topic is safe and preserves its run marker:
    • Regular: print assets/flows/regular.txt the same way (one ```text block, verbatim, never redrawn), then superlite:using-superlite sizing and superlite: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 (loads superlite:research).
    • Resume or Status (a run in progress): the same as /superlite:resume or /superlite:status.

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 split and superlite-cli session use stay as manual tools. See docs/sessions.md.
  • If session use reports a stash conflict: resolve, git add, then superlite-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: APPROVED and stop.
  • A failing or skipped test, a red suite, or a repeated file:line is 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:

  1. Cause known (including a fully specified change: missing import, CRLF, rename, a concrete fix line); fix confined to one module, plus a regression test.
  2. Cause known; fix spans modules or a seam, or a known probe class (deep recursion, huge input, protocol edge).
  3. 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 the wait: line) for the summary (--fast PATHS is the manual fallback). Do not run the full suite. Report the test result as tests: <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 verified with 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, checkout or stash. The coordinator records your fixes with superlite-cli checkpoint. Never spawn agents.
  • Kill only processes you started, by PID. Never taskkill /IM, pkill, killall or Stop-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 (subcommands source, 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 contradiction and its cause. Never resolve it silently.
  • Run lint before 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

More from iha2/superlite

All 2