Get started
Install, initialise, open the app, ask your agent.
Install and Init
1. Install
One self-contained binary — no runtime to install first.
curl -fsSL https://shall.sh/install | shmacOS and Linux, Apple Silicon and x64; on Windows, run it inside WSL. Later, shall upgrade replaces the binary with the newest release.
Nothing else to install for the agent side: shall init wires the commands below into the project itself. Shall drives Claude Code and Codex today — the core is agent-agnostic, and each agent gets the same processes in its own grammar. (Building from source instead: see CONTRIBUTING.md.)
2. Initialise the project
Run it in your project's folder. It creates .shall/ — the spec tree the graph is read from and the ledgers your approvals are written to — and registers the project.
shall initThe spec is markdown in your repository: version it, diff it, review it like code.
3. Open the app
shallStarts (or reuses) the local daemon and opens http://localhost:9461 — the Control plane for governing the project and the Spec plane for reading and editing the graph.
Everything stays on your machine.
4. Ask your agent
/shall.help$shall:helpIt says what Shall is in a screen, reads where this project stands, and names the one or two commands that move it — the only command that also answers outside a Shall project.
Working with Shall
1. Driving your agents using Shall
Seven processes, each written as prose — everything they write lands in the Review Queue for your yes. The process is the same in every agent; only the call wears the agent's own grammar:/shall.specify in Claude Code is$shall:specify in Codex, and a dotted name likework.todo becomes $shall:work:todo.
| Process | In one line |
|---|---|
specify | interviews you and writes the spec, phase by phase |
plan | designs the layer below — modules, contracts, work items — for one yes |
work | takes one turn of work off the board and writes it up |
work.todo | surveys what the project needs, writes nothing |
work.report | writes up work already done, reconstructed from git |
raise | brings a doubt, lands a finding or a decision — or nothing |
help | says what Shall is and what to run next |
1.1 Specify
/shall.specify$shall:specifyThe staged elicitation that fills the domain and intent planes: goals, actors, use cases, scenarios, responsibilities, requirements, acceptance criteria and the project's own vocabulary. Each stage is drafted with you in the terminal, written once agreed, and lands in the Review Queue for your approval; --auto runs the stages through and asks once at the end.
1.2 Plan
/shall.plan$shall:planThe design pass one layer below, in two stages. First it plans the way an agent plans anything — reads the repository, proposes the stack, draws module boundaries, cuts the work — and puts the whole plan to you for one yes, writing nothing. Then it transcribes the agreed plan in one pass: modules, their contracts, the work items the board will hand out, and the technology decision. --auto skips the terminal yes and nothing else.
1.3 Work
/shall.work$shall:workOne turn of the work cycle: survey the board, pick a small bundle, do the development itself outside Shall, self-check the result against each item's definition of done and the criteria it targets, and write the turn up as one journal for the queue. --auto runs without stopping, --dry forecasts without writing; work.todo is the survey alone and work.report writes up work already done.
1.4 Anytime — raise
/shall.raise$shall:raiseThe door for a doubt rather than a request. It explores, says what it found, and leaves behind a finding, a decision you dictated, both — or nothing at all.
2. Governing your project on Shall
Everything below lives in the app — run shall and it opens in your browser athttp://localhost:9461. Judgements are yours and are made there; no command approves, rejects or closes anything.
2.1 Review & approve
The Review Queue holds everything waiting on you as cards — spec approvals, work reports, criterion closures, work item completions, standing findings — each with diffs, evidence and context in front. Approve, reject with a rationale that becomes the agent’s work order, close a criterion over its evidence or leave it open with your reason.
2.2 Explore the spec plane
The whole graph on one canvas, grid or graph view, banded domain → intent → plan → execution. Every node wears its state: red for something to fix, yellow for a judgement still owed, green for settled — plus the second-axis words, Open/Closed on criteria, Blocked/Ready/Done on work items, Sat/Unsat on requirements and scenarios. Read any node, edit it, or propose its deletion right there.
2.3 Watch the vitals
How far the spec has come and what it still lacks, computed on every read and stored nowhere: satisfaction, closure and completion ratios with drill-downs into what is open and why, and seven spec-health checks for the gaps that are neither errors nor waiting on anyone — every rule always shown, violated ones first.