1.1. Getting started
SPEAR — Specification-driven Platform for Embedded Agentic Reasoning — is an engineering agent for specified systems. It changes code inside a confined workspace and reports what it can show about the result; it answers questions about a bound standard from the standard itself, with citations; and when a change has to satisfy that standard, it judges the result constraint by constraint on evidence the model cannot supply. Introduction explains why it is built that way.
This page goes from nothing to a first change, a first normative answer and a first MIXED task.
1.1.1. Prerequisites
Linux with systemd and
bubblewrap— the execution harness confines every command in a sandbox and refuses to run without one;Python 3.12 or later for a native installation, or Docker for the container;
a model endpoint: an OpenAI-compatible server, local or remote (Model backends).
The full list is in Installation.
1.1.2. Install
1.1.2.1. The container path
If you have access to a model server and want to use SPEAR, Docker is the only prerequisite:
$ git clone https://github.com/smartobjectoriented/spear ~/spear
$ cd ~/spear
$ scripts/docker/build.sh # spear:<version>-public, ~20 min, mostly the embedder
Then run it as Running the images shows: the image carries the harness
and the embedder, and you mount your own checkouts and point it at a model
endpoint. Its docker run line carries three --security-opt flags
without which the harness refuses to run any command (Container).
On a workstation that also has a native installation,
scripts/docker/build.sh --profile private builds the image
scripts/docker/spear-docker.sh runs, and spear-docker.sh --reds --auto
opens the tunnel and chats (Three profiles, Container).
At the institute there is a shorter path still: the reds image carries the
shared trees and their index, and spear runs it with nothing but
Docker (Running the reds image).
1.1.2.2. The native path
To change the harness, re-index, or register projects of your own, install it
natively as Installation describes. The launcher it leaves is
client/spear-chat.sh; linking it onto your PATH as spear-chat is
the usual arrangement, and the rest of this page assumes it.
1.1.3. Configure a model backend
spear-chat talks to an OpenAI-compatible endpoint. Without a flag it asks
which backend to use and remembers the answer:
$ spear-chat --local # llama-server on 127.0.0.1:8080
$ spear-chat --api-base http://gpu-host:8080/v1 # any OpenAI-compatible endpoint
$ spear-chat --provider anthropic --model <model-id> # the Anthropic API
The Anthropic backend serves questions and normative answers; changes run on the coding core, which needs an OpenAI-compatible endpoint. Serving a model yourself is covered in The model and its weights.
1.1.4. Use a project
Tools always run in the current directory. To work on a tree, start SPEAR in it:
$ cd ~/src/acme-firmware
$ spear-chat --ask # confirm each change and command
That is an ad-hoc project. To register it — so it gets a name, a retrieval index, declared build and test commands, and its own knowledge — add it to the registry and index it:
$ spear-corpus add acme-firmware ~/src/acme-firmware
$ spear-chat --corpus acme-firmware
> /reindex
Projects and corpora documents every key a project can declare, including
build_commands and test_commands, which SPEAR runs on the final tree of
every change; a project that declares none is probed for the usual ones.
The permission mode is chosen at launch — --safe (the default), --ask
or --auto; Security model says what each allows, and
Configuration reference lists the other flags.
1.1.5. Make a change
A request about the tree runs on the coding core (Implementation mode):
> Fix the off-by-one in ring_next() in src/ring.c, then run make.
The core reads, edits and runs make inside the workspace; every call
crosses the control plane, and in --ask you confirm each one. The answer
ends with SPEAR’s own verdict on what was shown — VERIFIED only if a check
ran and passed on the final source (Evidence and verdicts).
Tell SPEAR what it should keep knowing about the workspace with
/remember; later turns in that workspace are given it (Workspace knowledge).
Tools of external MCP servers are made available per workspace
(External capabilities).
1.1.6. Bind a standard
A specification is ingested once and then bound; the binding is shared by every session on the machine:
> /standard ingest ~/docs/acme-frame.pdf --id ACME-FRAME --revision 2024 --origin PUBLIC
> /standard use ACME-FRAME 2024
> /standard status
--origin defaults to LICENSED_STANDARD, the safe answer for a document
nobody classified. Then ask about it:
> What does Rule 7.1-3 require of the descriptor word?
That is a NORMATIVE request (Normative mode: authoritative standards): it is answered from the document first, every normative claim carries its provision, and an answer the evidence does not support is withheld with the reason.
1.1.7. Make a change the standard governs
Ask for a change in the standard’s terms:
> Update parse_descriptor() in src/frame.c so it reads the descriptor words
the way the standard requires.
That is a MIXED request (Mixed mode). SPEAR identifies the governing provisions first, read-only; turns them into a compact constraint packet; lets the coding core make the change; and judges the final source against the packet.
1.1.8. Read the result
A MIXED turn ends with a verdict that keeps two dimensions apart: whether the
change was shown to work, and whether SPEAR holds authoritative evidence that
each applicable requirement holds. COMPLIANCE NOT DEMONSTRATED does not
mean non-compliant: it means that evidence is missing, and a project can
supply it (Normative checks and applicability). Evidence and verdicts explains every
verdict and Mixed mode shows a complete one.
1.1.9. Retrieval is not a detail
Answers about a project are far better with its corpus indexed than without (Measured effect): index the projects you ask about.
1.1.10. Where next
spear-chat — the commands, inside and outside the chat;
Request modes and evidence — the request modes and their evidence;
The confined execution path — how every command is confined.