Concepts
flowchart LR
Y(["You"]) -->|"say what you want"| F["Flow"]
F -->|"opens"| S["Session: branch or worktree"]
F -->|"writes"| P["Plan"]
O{"Orchestrator: you or AI"} -->|"approves or decides"| P
P -->|"dispatches"| A["Agents build in parallel"]
S -.->|"holds the work"| A
A --> R["Review and fix"]
R --> RP(["Report"])
RP -->|"time and cost"| Y
How it works
Section titled “How it works”Read the diagram left to right. Your request chooses a flow, the flow opens a session, and the plan is the contract between you and the build. The orchestrator is the one who says yes to the plan. The agents do the work inside the session. The report is how you find out what happened.
For example, a request to change existing code picks the Feature flow, which opens a session, writes a plan, and so on down the table. This page is the map. It does not explain each idea in full, so every row links to the one page that does.
The pieces
Section titled “The pieces”| Concept | In one line | Read more |
|---|---|---|
| Flow | The path a request follows: MVP, Feature, Debug, Research, Small, Review or Regular. | Pick a flow |
| Session | One piece of work on its own branch, superlite/sessions/<topic>. Every run opens one. |
Sessions |
| Worktree | A second folder with its own copy of the project, used when another run is open. | Worktrees |
| Sandbox | A throwaway folder inside .superlite/ where a feature prototype is built. |
Sandbox |
| Session lifecycle | How a session starts, runs, finishes and closes after the merge. | Lifecycle |
| Orchestrator | Who approves the plan and decides open choices: you (human) or the AI. | Orchestrators |
| Plan | What will be built, in plain words, with a rough time and cost. | Plan and approval |
| Agents | Workers on cheaper or stronger models, run side by side in waves. | Parallel build |
| Review and fixes | Reviewers check the work, fixers repair findings by tier. | Reviews and fixes |
| Report | Time and cost, projected against actual, and what changed from the plan. | Report |
Example: a feature, from request to branch
Section titled “Example: a feature, from request to branch”Say your social network lives in ~/social and you want to suggest “People you may know” from friends of friends. It changes existing code, so it uses the Feature flow. Each step names the concept at work.
-
You ask for a change to existing code.
Claude Code · ~/social ❯ /superlite:feature Suggest "People you may know" from friends of friendsThe command picks the flow and opens a session, a branch
superlite/sessions/<topic>, before anything is touched. -
Researchers read the code and the field.
Directorydocs/plans/
- 2026-11-12-people-you-may-know.research.md
- 2026-11-12-people-you-may-know.findings.md
- 2026-11-12-people-you-may-know.contradictions.md
- 2026-11-12-people-you-may-know.sources.md
Agents run side by side and fill a sourced ledger, because each question is independent. They are the “agents” on the map.
-
You validate the feature plan. You decide: approve it or change it.
docs/plans/2026-11-12-people-you-may-know.feature.md # People you may know: feature plan## Goal**Suggest people a member may know, based on friends of friends.**The plan is the contract: the prototype and the build are judged against its acceptance checks. The one who says yes is the orchestrator, here you.
-
A prototype appears in a sandbox, and you try it. You decide: does it work?
docs/plans/2026-11-12-people-you-may-know.feature.md ## Prototype scope- **New in the sandbox:** a suggestion query, a "People you may know" card on the feed, a Dismiss button, and a stub for the friends database.The sandbox is a hidden folder in your checkout, not a second worktree, so there is no extra branch to clean up.
-
The build ports the prototype.
docs/plans/2026-11-12-people-you-may-know.feature.md Dedicated worktree `people-you-may-know-int` off `main`. One task per module.The prototype's acceptance tests are the target; code is ported task by task, and stubs stay behind.The prototype’s acceptance tests become unit tests in the real code. One task per module means agents work on separate files and do not collide.
-
You read the report.
Claude Code · build report Projected Actualwall-clock (min) 8.0 9.5agent cost (USD, +rework) 1.42 1.65The report puts forecast and actual side by side. See Report.
What you end up with: the branch superlite/sessions/people-you-may-know-int, with the app’s full suite green. What is left for you: open the pull request, review it and merge it yourself.
Good to know
Section titled “Good to know”- You do not create sessions or worktrees by hand. superlite opens them and picks the branch name.
- With the human orchestrator you see the plan first, which suits a first run. The AI orchestrator suits runs where you are away.
- A checkpoint is a hidden save of one finished task. Nothing is committed during a run.
Try it on Quickstart, or look up a command on Commands.