Quick start

One interview per project, then Orstrum works in the background. Here is the first session, start to finish.

1. Set up the project

>/orstrum:orstrum start

The agent reads what's already there (README, package.json, CLAUDE.md) and asks at most four questions: what the project is and what "done" looks like, how to run the tests and the build, what it should never and always do, and how cautious to be with the budget (relaxed, default or strict). It writes three files:

.orstrum/spec.mdunder 40 linesWhat the project is, what done looks like, the commands. Read on recall.

.orstrum/rules.mdunder 20 linesNever and always lists. Pushed into the agent's context at every session start (Pro), so each line costs budget.

.orstrum/policy.jsonpresetBudget thresholds and detector sensitivity. See Budget policy.

Nothing outside .orstrum/ is written. The folder carries its own .gitignore, so it stays out of your repository without touching yours.

2. Work

At session start the agent sees one line, for example Orstrum budget: week 31% · 5h 12% · measured · mode normal (orstrum skill). The mode tells it how to behave. When the budget changes mode, when a loop is detected, or when a test file is changed to make a check pass, another one-line Orstrum: message arrives with the agent's next tool result, and the agent explains it to you and asks.

On Pro, every passing test, build or run takes a checkpoint on its own. You'll rarely call a tool by hand; the plugin tells the agent when.

3. Look at the report

>/orstrum:orstrum report

Where the last session's budget went: the share of the week, the files edited, the loops detected and what the agent did after each nudge, the largest tool outputs, and whether a handoff was written. Compare the share with /usage; they come from the same numbers.

4. End the session well (Pro)

>/orstrum:orstrum handoff

The agent writes a summary (goal, done, decisions, next steps) and Orstrum validates it against the event log. The next session, including one that starts right after a /compact, gets it back before the first turn. If you forget, the session end stores a digest on its own.