runward 0.20.0 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -6
- package/dist/commands/init.js +9 -2
- package/examples/request-triage/code/README.md +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
|
|
4
4
|
|
|
5
|
-
[
|
|
5
|
+
[<img alt="npm" height="28" src="https://raw.githubusercontent.com/stranxik/runward/main/assets/npm-badge.png">](https://www.npmjs.com/package/runward) [](https://runward.dev/docs) [](https://github.com/marketplace/actions/runward-gate) [](LICENSE) [](https://github.com/stranxik/designing-and-running-agentic-systems) [](https://ko-fi.com/stranxik)
|
|
6
6
|
|
|
7
7
|
**AI writes the code. Runward verifies the engineering decisions behind it.**
|
|
8
8
|
|
|
@@ -12,6 +12,8 @@ Runward is an open-source delivery methodology for AI-assisted software engineer
|
|
|
12
12
|
|
|
13
13
|
The core idea: don't ask an LLM whether the engineering process was followed. Verify it with plain code.
|
|
14
14
|
|
|
15
|
+
**Try it in one command** — `npx runward init --example` scaffolds a filled reference mission and ends by running the strict gate itself: the whole chain goes green in front of you. The reference floor even ships an intentional failure (a value the model invented) that the deterministic guard refuses — `npm run demo` in `code/` shows the catch. When you want it on your own project, `npx runward init` starts a blank mission. MIT, zero key, zero network by default.
|
|
16
|
+
|
|
15
17
|
> Spec Kit, OpenSpec and BMAD take you to tested, sometimes merged code. Runward pilots the whole mission — and picks up their output if you use them. What none of them *structures* is the run: governed memory, resilience, execution security, continuous evaluation, transmission.
|
|
16
18
|
|
|
17
19
|
## Documentation
|
|
@@ -23,16 +25,18 @@ The full documentation is at **[runward.dev/docs](https://runward.dev/docs)**
|
|
|
23
25
|
- **[The six phases](https://runward.dev/docs/concepts/six-phases/)** — the gated delivery spine, phase by phase.
|
|
24
26
|
- **[From an AI agent](https://runward.dev/docs/operating/from-an-agent/)** — how an agent installs and drives runward end to end.
|
|
25
27
|
- **[Compliance evidence](https://runward.dev/docs/compliance/evidence/)** — framed for ISO 42001, NIST AI RMF and the EU AI Act, exported as OSCAL.
|
|
28
|
+
- **[How it compares](https://runward.dev/docs/compare/)** — Spec Kit, BMAD, Kiro, OpenSpec, Spec Kitty: sourced, from their own docs.
|
|
29
|
+
- **[Case study: dropyour](https://runward.dev/docs/case-study/)** — a real product shipped with runward, the trail gate by gate.
|
|
26
30
|
|
|
27
31
|
## Why
|
|
28
32
|
|
|
29
|
-
|
|
33
|
+
Runward exists to carry an agentic system across the stretch where nearly everything dies today: between the demo and production. Not because the model is weak, but because nobody can evaluate a non-deterministic behavior, govern it, or say in advance when it fails. These are architecture problems, not model problems. The industry's own signal is unambiguous: model vendors now deploy engineers directly into client organizations, because the bottleneck has moved from the model to its integration into the real world.
|
|
30
34
|
|
|
31
|
-
Spec-driven frameworks answered the first half of that problem: write the right thing.
|
|
35
|
+
Spec-driven frameworks answered the first half of that problem: write the right thing. Runward structures the second half: ship it, run it, hand it over.
|
|
32
36
|
|
|
33
37
|
Agentic systems break four assumptions of classical distributed engineering. The core component is **non-deterministic**: same input, different output, by design. **Input is indistinguishable from instruction**: anything the model reads can try to command it, so prompt injection is structural, not a bug to patch. **Forgetting becomes an engineering problem**: memory that only grows drowns the signal, so decay, invalidation and consolidation have to be designed, not hoped for. And the **blast radius is unprecedented**: an agent with tools acts on the world, so a bad output is no longer just a bad answer.
|
|
34
38
|
|
|
35
|
-
Runward is the **FDE method** made executable. Its guiding principle: the architecture frames the model, never the other way around — the model and the infrastructure are adapter decisions
|
|
39
|
+
Runward is the **FDE (Forward Deployed Engineer) method** made executable — the way those embedded engineers deliver, written down and gated. Its guiding principle: the architecture frames the model, never the other way around — the model and the infrastructure are adapter decisions behind stable contracts. From there, a delivery spine: six gated phases (a gate: a checkpoint you cross on evidence, never on assertion), each with a Definition of Ready and a Definition of Done, a decision matrix, and 64 craft rules — the detail is in the sections below.
|
|
36
40
|
|
|
37
41
|
## Who it's for — and when
|
|
38
42
|
|
|
@@ -61,7 +65,7 @@ npx runward --yes init # non-interactive, defaults (CI-friendly)
|
|
|
61
65
|
npx runward init --tools claude,cursor,copilot,gemini,windsurf
|
|
62
66
|
```
|
|
63
67
|
|
|
64
|
-
**Fastest way to see what runward does:** `npx runward init --example` scaffolds the `request-triage` reference mission already filled
|
|
68
|
+
**Fastest way to see what runward does:** `npx runward init --example` scaffolds the `request-triage` reference mission already filled and ends by running `check --strict` itself — every gate green, in one command. Then `cd code && npm install && npm run demo` runs five requests end to end; one of them (req-005) carries an account reference the model invented, and you watch the deterministic guard refuse to route on it, fail-closed. `runward compliance iso-42001` emits an audit-ready OSCAL pack from the traced decisions. When you're ready, `npx runward init` (no `--example`) starts your own mission from blank templates.
|
|
65
69
|
|
|
66
70
|
**Install the gate where you already work — honestly tiered by how hard it blocks:**
|
|
67
71
|
|
|
@@ -155,7 +159,7 @@ Four things, and a code-level competitive check (July 2026) confirmed no other s
|
|
|
155
159
|
- **Security by architecture, not detection.** Prompt injection is constrained structurally (lethal trifecta, 2-of-3 rule), not filtered heuristically.
|
|
156
160
|
- **Craft rules, not vibes.** 64 engineering craft rules ship with the mission (memory scoring, tiered retrieval, event sourcing, request-id propagation, multi-provider fallback, cost routing, post-turn pipelines, prompt-injection defenses…) — your agent applies them, `runward check` will not invent them. Code examples follow the reference-stack default (a single language in the core — TypeScript by default, an adapter decision like any other: see the decision matrix). The patterns are the contract; the language is the adapter.
|
|
157
161
|
- **One accountable operator, not a simulated team.** One human owns every gate while the agent executes the workflows — see [the operator role](docs/operator-role.md).
|
|
158
|
-
- **Hand-over gated on proof, not a folder.** The mission ends when the receiving team redoes a real task without you — and that succession is a gated deliverable (`handover.md`, four handover rules), verified like every other phase.
|
|
162
|
+
- **Hand-over gated on proof, not a folder.** The mission ends when the receiving team redoes a real task without you — and that succession is a gated deliverable (`handover.md`, four handover rules), verified like every other phase. Only one other scaffold (Spec Kitty) carries the mission past tested code — and its acceptance verdict is an AI review; runward's succession check is plain code, and its evidence exports as standardized OSCAL, not bespoke YAML.
|
|
159
163
|
|
|
160
164
|
## The reference floor
|
|
161
165
|
|
package/dist/commands/init.js
CHANGED
|
@@ -4,6 +4,7 @@ import { checkbox, input, select } from "@inquirer/prompts";
|
|
|
4
4
|
import { TEMPLATES, EXAMPLE_MISSION, EXAMPLE_CODE, MISSION_LAYOUT, VERSION } from "../lib/paths.js";
|
|
5
5
|
import { TOOL_PROFILES, TOOL_IDS, baselineSkills } from "../lib/tools.js";
|
|
6
6
|
import { makeWriter } from "../lib/write.js";
|
|
7
|
+
import { checkCommand } from "./check.js";
|
|
7
8
|
import { c, createHeader, isNonInteractive, section, status } from "../lib/styles.js";
|
|
8
9
|
/** Recursively copy a shipped directory tree (used to lay down the filled reference mission). */
|
|
9
10
|
const COPY_SKIP = new Set(["node_modules", "package-lock.json", ".DS_Store"]);
|
|
@@ -130,12 +131,18 @@ export async function initCommand(opts) {
|
|
|
130
131
|
console.log(status.success(`${w.stats.written} file(s) ${dryRun ? "planned" : "written"}, ${w.stats.skipped} skipped`));
|
|
131
132
|
if (example) {
|
|
132
133
|
console.log(`
|
|
133
|
-
${c.primaryBold("Filled reference mission — the
|
|
134
|
-
1.
|
|
134
|
+
${c.primaryBold("Filled reference mission — the gate audit runs on it right below.")}
|
|
135
|
+
1. See the deterministic guard refuse a fabricated value: ${c.primary("cd code && npm install && npm run demo")} ${c.gray("(req-005 carries an account reference the model invented — refused, fail-closed).")}
|
|
135
136
|
2. Run ${c.primary("runward compliance iso-42001")} — an audit-ready evidence pack (OSCAL) derived from the traced decisions.
|
|
136
137
|
3. Read ${c.white("runward/framing.md")}, the ADRs in ${c.white("runward/adr/")}, and ${c.white("runward/governance/threat-model.md")} to see how a real mission is traced end to end.
|
|
137
138
|
|
|
138
139
|
${c.gray("Start your own mission with")} ${c.primary("runward init")} ${c.gray("(without --example) to get blank templates.")}`);
|
|
140
|
+
// One command, whole chain: the scaffold ends by auditing itself, so the first
|
|
141
|
+
// contact with runward is the strict gate going green — not a promise to run it later.
|
|
142
|
+
if (!dryRun) {
|
|
143
|
+
console.log();
|
|
144
|
+
await checkCommand({ path: dir, strict: true });
|
|
145
|
+
}
|
|
139
146
|
}
|
|
140
147
|
else {
|
|
141
148
|
console.log(`
|
|
@@ -41,7 +41,7 @@ Prerequisite: Node 20+.
|
|
|
41
41
|
```bash
|
|
42
42
|
npm install
|
|
43
43
|
npm test # 14 deterministic tests via node:test + tsx
|
|
44
|
-
npm run demo #
|
|
44
|
+
npm run demo # five requests end to end, including a compliance suspension and a fabricated account the guard refuses
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
## Layout
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "runward",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.21.0",
|
|
4
4
|
"description": "After the spec: ship and run. A delivery framework for agentic systems — floor first, evolution on evidence, governance from day zero, handover with proof.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agentic",
|