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