# Quickstart

This page takes you from an empty directory to a green runward check. It is written for two readers at once: a human starting their first mission, and an AI agent driving runward end to end. runward does not write your product code: your agent does. runward lays down a neutral scaffold, then gates what gets built against evidence you (or your agent) supply. The gate is deterministic and offline: same inputs, same verdict, no model call, no network.

The whole tool is a loop: you describe the mission, your agent builds, then the check either sends you back to build or lets you out.

> **Diagram.** You describe the mission; your agent builds the code and fills the conformance manifests; then runward check --strict decides. If gaps remain, it sends you back to fill the named deliverable and re-run. When everything is filled and every rule accounted for, the gate goes green (exit 0). That is the loop: the check sends you back to build, or lets you exit.

## The one-minute path: see a gate go green

The fastest way to watch a gate pass is the shipped reference mission, which arrives already filled:

```bash
npx runward init --example    # scaffold the filled "request-triage" reference mission
runward check                 # exits 0 — every deliverable is filled
```

`init --example` copies a complete, pre-filled mission plus the reference floor code its manifests point at, laid down under `code/`. Under `runward check --strict` the evidence therefore resolves to real files rather than being unchecked.

This is the single case where a fresh scaffold is green out of the box:

- **plainly** — every deliverable is filled;
- **under `--strict`** — every pointer resolves.

Use it to see the whole chain, then start your own with `npx runward init` (no `--example`) for blank templates.

## What `runward init` actually writes

Run in the folder you want to seed (default is the current directory):

```bash
npx runward init            # interactive wizard
npx runward --yes init      # non-interactive: greenfield, floor tier, no tool profiles
```

`init` lays down a **neutral, vendor-neutral baseline** — no AI harness is privileged.

### What lands in the baseline

Concretely it writes:

- **`AGENTS.md`** at the project root — the agent charter, the "law" file, always written. `AGENTS.md` is the open standard read by a long list of agents (Codex, Cursor, Copilot, Windsurf, Cline, Zed, Amp, opencode, goose, Junie, Warp and more), so no single tool is favored. It states the non-negotiable boundaries:
  - the architecture constrains the model (not the reverse);
  - boundaries before the stack;
  - complexity deferred until a trigger;
  - a deterministic frontier;
  - and security on actions not display.
- **`.agents/skills/runward-<phase>/SKILL.md`** — vendor-neutral phase skills in the converged open `SKILL.md` format, always written alongside the charter. These surface the craft rules of a build phase by relevance, at the point of action; they help an agent *apply* rules but never enforce them — `runward check --strict` is the sole authority.
- **`runward/`** — the mission state. `init` copies the deliverable templates (framing note, mission contract, architecture note, execution topology, decision matrix, floor note, governance notes, port contract, runbook, hand-over note, ADR template — plus a few non-gated scaffolding notes: reference-stack, shared-bricks, gap-analysis) into it.
- **`runward/workflows/`** — the executable method your agent follows, starting with `method.md` (then `frame`, `architect`, `floor`, `iterate`, `govern`, `handover`, `brownfield`, `review`, `decision-loop`, `verify`).
- **`runward/rules/`** — the craft rules the agent applies while building.
- **`runward/adapters/`** — **inert sample** gate wiring (git `pre-commit`, CI, per-harness turn-end). runward never installs these; you wire them (see below).

### No harness channel by default

**No harness channel is written by default.** With `--yes`, the tool-profile list is empty; the wizard pre-checks nothing.

A per-harness channel (e.g. `.claude/`, `.cursor/`) is opt-in via `--tools claude,cursor,...` — an addition on top of the neutral baseline, which the agent may recommend for the detected harness only on the operator's approval.

### Overwrites, dry-run, and recorded choices

- `init` never overwrites an existing file unless you pass `--force`; existing paths are reported as `skip`.
- `RUNWARD_DRY_RUN=1` plans the writes without touching disk.
- The wizard also records your **entry mode** (greenfield / brownfield) and **stopping tier** (framing / floor / full chain) — the sponsor's choice, revisable.

## The build loop: describe → agent builds → check

runward frames; your agent builds. The loop is:

1. **Describe the product to your agent.** Point it at `AGENTS.md` and `runward/workflows/method.md`. Day one, you and your sponsor fill `runward/framing.md` — the problem, the value, an observable success criterion, floor vs target. This is a conversation, not code; do not architect before the framing gate passes.
2. **The agent builds against the mission.** It writes the actual product code, and for each gated deliverable it fills a `## Rule conformance` manifest: every CRITICAL/HIGH craft rule mapped to that phase is accounted for as one of:
   - `applied` — with a typed pointer the gate can verify (`file:PATH[:LINE][#SYMBOL]`, `test:PATH[::NAME]`, `adr:NNNN`) or prose;
   - `deviated` — with an ADR;
   - `n/a` — with a real reason.

   `runward manifest --sync` scaffolds missing rows; the agent fills the decision.
3. **Run the gate.**

```bash
runward check            # gap audit: which deliverable is missing / started / filled
runward check --strict   # also verify every phase's rule-conformance manifest + evidence
```

Repeat: fill the deliverable(s) named, re-run `runward check`. The agent can drive the whole loop; `runward check --json` emits one deterministic JSON object (verdict, current gate, per-deliverable state, exit code) so an agent reasons on data, not scraped text.

## What "a passing gate" means

### How deliverables are classified

`runward check` reads mission state and classifies each expected deliverable as `filled`, `in-progress` (placeholders remain), `untouched` (raw template), or `missing`. A deliverable counts as **filled** only when it departs meaningfully from the shipped template — several new lines and enough new words, not a one-byte edit — so you cannot pass a gate by leaving the scaffold in place.

### Gates and exit codes

- **Current gate** = the first phase whose deliverables are not all filled. As you fill a phase, the pointer advances to the next — that phase's gate has been crossed.
- **Exit code 0 (clean)** requires *every* expected deliverable across *all* phases to be filled, and under `--strict` every mapped CRITICAL/HIGH rule accounted for, and — when hooks are enabled (`--hooks`) — any hooks passing. This is why a blank `runward init` cannot reach exit 0 until the *entire* chain is filled; only `init --example` is green immediately. The message on success: "All expected deliverables are filled. Cross gates on evidence, not on paperwork."
- **Exit code 1** = gaps remain (unfilled deliverables, or `--strict` conformance gaps, or failed hooks).
- **Exit code 2** = no mission found here or above (`runward init` was never run). A mission root is a directory containing `runward/framing.md`.

### What `--strict` adds

Under `--strict`, the gate does more than presence:

- applied pointers must resolve to real, non-empty content;
- a signed rule's evidence must match its `signature:`;
- a stale pointer (drift) fails;
- and [the evidence seal](https://runward.dev/docs/en/concepts/evidence/), if present, must be intact.

This is the **deterministic, zero-LLM** part: it proves a decision was *traced* and points at something real — never that the code is correct, and it cannot be jailbroken by injected text; rerun it and get the same verdict.

### Documentary proof, not a runtime pass

**A passing gate is documentary proof, not a runtime pass.** The gate confirms the decisions are traced; it explicitly does **not** run your code — runward is not a runtime. The *behavioral* proof is your own test suite, which runward reports as present/fresh but never executes or reads. Likewise the `verify` workflow (an adversarial cite-vs-apply pass) is advisory and never blocks the gate. You cross on both proofs.

## Sealing and wiring (optional, on your say-so)

### Sealing a green gate

Once a `--strict` gate is green, you may seal it: `runward check --freeze` hashes every resolvable evidence file into `runward/evidence-lock.json` (SHA-256, committed). A sealed file that later changes or disappears fails `check --strict` until you re-verify and re-seal; it refuses to seal a red gate.

### Wiring the gate to run automatically

To make the gate run automatically, wire one of the **inert samples** in `runward/adapters/` at your harness's natural moment (git `pre-commit`, a CI required check, or a turn-end hook).

runward installs nothing and never writes to `.git/` (ADR-0012): `runward wire` is read-only — it detects the harness and points at the matching sample; the operator (or the agent, on explicit approval) does the wiring. On an `undetermined` harness the agent asks which tool you use rather than guessing.

"Agent-operable" means an agent can drive this end to end, including the wiring on your say-so — not that runward silently modifies your repo.

## Command reference for this quickstart

| Command | Effect | Exit codes |
|---|---|---|
| `npx runward init` | Scaffold neutral baseline: `AGENTS.md`, `.agents/skills/`, `runward/` (workflows, rules, adapters, deliverable templates) | 0 |
| `npx runward init --example` | Scaffold the filled `request-triage` reference mission (green plainly and under `--strict`) | 0 |
| `npx runward --yes init` | Non-interactive defaults: greenfield, floor tier, no tool profiles | 0 |
| `npx runward init --tools claude,cursor,…` | Add per-harness channels on top of the baseline (opt-in) | 0 |
| `runward check` | Gap audit of deliverables; names the current gate | 0 clean · 1 gaps · 2 no mission |
| `runward check --strict` | Also verify each phase's rule-conformance manifest and evidence (deterministic, zero-LLM) | 0 clean · 1 gaps · 2 no mission |
| `runward check --json` | Same verdict as one machine-readable JSON object | matches above |
| `runward check --freeze` | Seal a green strict gate into `runward/evidence-lock.json`; refuses on a red gate | 0 clean · 1 gaps · 2 no mission |

## Why this choice

### The neutral-baseline default (ADR-0030)

The neutral-baseline default (write only AGENTS.md + .agents/skills, no per-harness channel) is a deliberate vendor-neutral choice recorded as ADR-0030. The rejected alternative was pre-selecting or privileging one AI harness (e.g. writing .claude/ by default); that would favor one tool over its peers. Instead the baseline uses only open, converged standards (AGENTS.md and the SKILL.md format) that 14+ harnesses read, and any tool-specific wiring is an explicit opt-in via --tools that the operator adds afterward.

### Never installing the gate (ADR-0012)

Similarly, runward never installs the gate itself (ADR-0012): adapters are inert samples the operator wires, rejecting the alternative of silently writing to .git/ or a harness config, so the operator always owns the gate.

## See also

- [Concepts: the deterministic gate](https://runward.dev/docs/en/concepts/the-gate/)
- [The six phases](https://runward.dev/docs/en/concepts/six-phases/)
- [From an AI agent](https://runward.dev/docs/en/operating/from-an-agent/)
- [Resume an existing system](https://runward.dev/docs/en/operating/resume-existing/)