Prototype sandbox
flowchart LR
P["Sandbox folder: the prototype"] --> T{"You decide: try it"}
T -->|"it works"| I["Integration worktree: the real build"]
T -->|"changes"| F["Fix round in the same sandbox"]
F --> T
I --> D["proto discard deletes the sandbox"]
P -.->|"or session close"| D
How it works
Section titled “How it works”Before a feature touches your real code, you get something to try. The prototype is the smallest runnable piece of your app that shows the feature working. It keeps the entry point and what the feature touches, and stubs the rest: a fake database, a fixed test user, fake services. For a CSV export, that is a tiny app with the export button and a fake list of orders.
It lives in one folder inside your checkout:
Directory.superlite/
- feature.json topic, status and run command of the open prototype
Directorysandboxes/
Directorycsv-export/ the session slug, or
hostwhen there is no sessionDirectorycsv-export/ the topic
Directorydocs/plans/ the prototype’s own plan, at most 8 tasks
- …
Directorytests/ written against the feature’s acceptance checks
- …
Directorysrc/ new code and stand-ins, in your project’s own layout
- …
Real code, no edits
Section titled “Real code, no edits”The sandbox holds only new code and stand-ins. It reaches your real code where it already is, so nothing is copied and nothing is edited. It sees your uncommitted code too.
| Language | How the sandbox reaches your code |
|---|---|
| Python | PYTHONPATH, or a sys.path entry pointing at your 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 |
Stand-ins are injected at the sandbox’s entry point. A real file is copied only when it hard-wires a dependency that cannot be injected, and the plan says so.
Sandbox or worktree?
Section titled “Sandbox or worktree?”| Sandbox | Worktree | |
|---|---|---|
| What it is | A plain folder | A second checkout git knows about |
| Where | .superlite/sandboxes/<session>/<topic>/ |
.claude/worktrees/<name>/ |
| Branch | None | Its own |
| Holds | A small app with stubs | Your whole project |
| Used for | The throwaway prototype | Sessions and the real integration build |
| Your tracked files | Never touched | Edited on its own branch |
| Deleted by | proto discard or session close |
session close, or ExitWorktree for Claude’s |
| Moves when sessions switch | Never | Never |
The two meet at one point. The prototype’s code is ported to the integration worktree task by task, never merged, so stubs and fakes stay behind.
Example: trying People you may know
Section titled “Example: trying People you may know”Say your social network lives in ~/social and you want to suggest “People you may know” from friends of friends. It is a feature, so you try it before the real code changes.
-
You ask for the feature and approve its plan.
Claude Code · ~/social ❯ /superlite:feature Suggest "People you may know" from friends of friendsThe plan has a “Prototype scope” section. It says how real the prototype must be, here one that keeps the app’s entry point, feed and profile pages and stubs the friends database. It also lists what to keep and what to stub.
-
superlite builds the prototype. You wait. superlite makes the sandbox folder and builds the prototype inside it. Nothing outside the folder is written.
Directory~/social/
Directory.superlite/
Directorysandboxes/
Directorypeople-you-may-know/ the session
Directorypeople-you-may-know/ the topic
Directoryapp/ the social app’s entry point, feed and profile pages
- …
Directoryproto/ new code: suggestion query, “People you may know” card, Dismiss button
- …
Directorystubs/ friends database and notifications, faked
- …
Directorytests/ written from the acceptance checks
- …
- package.json npm run dev starts it
-
You decide: try it. superlite prints how to reach the prototype and the acceptance checks. You run the command it gives.
Try-out · ~/social/.superlite/sandboxes/people-you-may-know/people-you-may-know ❯ npm run devsocial (sandbox): http://localhost:3000/feedsuggestions: 4 people you may knowfriends database: stubbed...social files changed: noneThe command starts the sandbox app and prints the address to open. You open the feed, see the “People you may know” card, click Dismiss and reload, as the acceptance checks say. The last line proves the point of a sandbox: no app file was touched.
-
You decide: it works, or change it. You reply in plain text. Say you ask for one round of changes first.
Claude Code · ~/social ❯ <what you want different>A change request starts a fix round in the same sandbox, not a new plan, and then another try-out. Replying that it works records your approval. In human mode the real build stays blocked until you give it.
-
The real feature gets its own worktree. The integration build runs in
.claude/worktrees/sessions-people-you-may-know-int(see Worktrees). The prototype’s acceptance tests are ported as unit tests, task by task. Stubs stay behind.Directory~/social/
Directory.claude/worktrees/sessions-people-you-may-know-int/ the real build
- …
Directory.superlite/sandboxes/people-you-may-know/ deleted at the end
- …
-
superlite cleans up. At the end of the feature,
superlite-cli proto discarddeletes the sandbox and archives its run files. If it was left open,session closeremoves it.
What you end up with: a branch superlite/sessions/people-you-may-know-int ready for a pull request, with only the real code and the ported tests, a prototype you tried before any of it was written, and no stubs or fakes on your branch.
Good to know
Section titled “Good to know”- In human mode the integration build stays blocked until you approve the try-out.
- Your reply to the try-out is plain text: “it works”, or a list of changes. Changes start a fix round, not a new plan.
- The default is stubs for everything the feature does not change. When the feature depends on real data shapes, the plan can ask for an isolated environment with seeded fixtures and test values instead of secrets.
- Real secrets and production data never enter a sandbox.
proto discardkeeps the prototype’s report headline and archives its run files.session closediscards an open sandbox too.
Read the Feature flow, or see where the integration build runs in Worktrees.