Quickstart.

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.

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:

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):

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.

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, 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.