The kit
One package, golem-spec, with one command, golem. It reads the EARS lines of a Kiro spec, runs them as physics tests, and hands counterexamples to the agent.
The output below is copied from docs/cli-transcript.md, a run on the real G1 app. Long blocks are cut at the line shown and the file has the rest.
Commands
golem check
Compiles every EARS line against the app lexicon. No trial runs. Exit 0 when all lines compile.
golem check [file] [--app <dir>] [--json]Real output, golem check. Node 21 on Windows, the G1 app, 11 lines.
$ golem check
11 requirements compiled, 0 warningsgolem test
Runs every requirement: pinned seeds, random trials, guided search, shrinking. Exit 2 when any line is broken.
golem test [--req <id>] [--budget <n>] [--time <s>] [--workers <n>] [--search-seed <n>] [--app <dir>] [--json]Real output, golem test --budget 200 (exit 2, 156 s). Node 21 on Windows, the G1 app, 11 lines.
$ golem test --budget 200
1.1 HELD closest margin +0.233 m no counterexample in 200 trials; from the 40 uniformly random ones, failure rate below 7.5 % (95 % confidence) [Expected_Hold: met]
1.2 BROKEN margin -0.339 m 50 trials push.force = 223 N, push.angle = 220 deg, push.phase = 0.0715 (stride phase) (shrunk, seed 2205968643) [Expected_Break: met]
1.3 BROKEN margin -0.442 m 122 trials push.force = 72.7 N, push.angle = 88.1 deg, push.phase = 0.277 (stride phase) (shrunk, seed 1291121316) [Expected_Hold: NOT met]
2.1 HELD closest margin +0.116 m/s no counterexample in 40 trials; from the 40 uniformly random ones, failure rate below 7.5 % (95 % confidence) [Expected_Hold: met]
2.2 HELD closest margin +0.257 m no counterexample in 200 trials; from the 40 uniformly random ones, failure rate below 7.5 % (95 % confidence) [Expected_Hold: met]
3.1 HELD closest margin +0.144 m no counterexample in 200 trials; from the 40 uniformly random ones, failure rate below 7.5 % (95 % confidence) [Expected_Hold: met]
4.1 HELD closest margin +0.191 m no counterexample in 200 trials; from the 40 uniformly random ones, failure rate below 7.5 % (95 % confidence) [Expected_Hold: met]
... 5 more lines in docs/cli-transcript.mdgolem falsify
Hunts one requirement. Pinned seeds re-run first.
golem falsify <reqId> [--budget <n>] [--time <s>] [--workers <n>] [--search-seed <n>] [--app <dir>] [--json]Real output, golem falsify 1.3 --budget 200 (exit 2, 11 s). Node 21 on Windows, the G1 app, 11 lines.
$ golem falsify 1.3 --budget 200
1.3 pinned generation 0: lowest -0.442 m, 1 trials used, 199 remaining
1.3 shrink generation 0: lowest -0.442 m, 19 trials used, 181 remaining
1.3 BROKEN margin -0.439 m 19 trials push.force = 72.1 N, push.angle = 88.1 deg, push.phase = 0.277 (stride phase) (shrunk, seed 1291121316)golem replay
Re-runs a pinned counterexample exactly and writes its trace to .golem/replays/.
golem replay <reqId> [--seed <n>] [--app <dir>] [--json]Real output, golem replay 1.3 (exit 0). Node 21 on Windows, the G1 app, 11 lines.
$ golem replay 1.3
replay 1.3: seed 1291121316, push.force = 72.1 N, push.angle = 88.1 deg, push.phase = 0.277 (stride phase)
robustness -0.439 m at t = 4.84 s (the worst moment)
signals: minimum, maximum, and value at the worst moment
pelvis_z: min 0.0613 m, max 0.774 m, at worst 0.0613 m
tilt_deg: min 0.339 deg, max 120 deg, at worst 87.7 deg
forward_speed: min -0.456 m/s, max 0.742 m/s, at worst -0.456 m/s
commanded_speed: min 0.5 m/s, max 0.5 m/s, at worst 0.5 m/s
... 4 more lines in docs/cli-transcript.mdgolem gate
Exit 0 only when every line meets its row of the Expectation table (Expected_Hold holds, Expected_Break breaks; no row means Expected_Hold) and no pinned seed fails. With --kiro it blocks an agent Stop with JSON on stdout and exits 0.
golem gate [--kiro] [--budget <n>] [--time <s>] [--workers <n>] [--search-seed <n>] [--app <dir>] [--json]Real output, golem gate (exit 2, 24 s). Node 21 on Windows, the G1 app, 11 lines.
$ golem gate
Expected_Hold (8 lines: must hold)
ok 1.1 HELD closest margin +0.252 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
FAIL 1.3 BROKEN margin -0.439 m 19 trials push.force = 72.1 N, push.angle = 88.1 deg, push.phase = 0.277 (stride phase) (shrunk, seed 1291121316) <- expected to hold but a counterexample was found
ok 2.1 HELD closest margin +0.117 m/s no counterexample in 4 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 2.2 HELD closest margin +0.257 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 3.1 HELD closest margin +0.197 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 4.1 HELD closest margin +0.192 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 5.1 HELD closest margin +0.262 m no counterexample in 4 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 6.1 HELD closest margin +0.227 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
Expected_Break (3 lines: must break)
ok 1.2 BROKEN margin -0.318 m 20 trials push.force = 216 N, push.angle = 220 deg, push.phase = 0.0715 (stride phase) (shrunk, seed 2205968643)
ok 4.2 BROKEN margin -0.41 m 17 trials payload.mass = 15 kg (not shrunk, seed 3160059130)
ok 6.2 BROKEN margin -0.445 m 15 trials latency.duration = 0.05 s (not shrunk, seed 229287175)
1.3: WHEN the pelvis is pushed with up to 100 N for 0.2 s from any direction at any point in its stride THE robot SHALL stay upright for 3 s
scenario: push.force = 72.1 N, push.angle = 88.1 deg, push.phase = 0.277 (stride phase) (seed 1291121316)
margin: -0.439 m
reproduce: npx golem-spec replay 1.3
gate RED: 1 of 11 requirements do not meet their expectationThe same gate with Kiro's balance reflex (GOLEM_REFLEX=kiro), where requirement 1.3 now holds:
$ GOLEM_REFLEX=kiro golem gate
Expected_Hold (8 lines: must hold)
ok 1.1 HELD closest margin +0.251 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 1.3 HELD closest margin +0.216 m no counterexample in 26 trials; from the 5 uniformly random ones, failure rate below 60 % (95 % confidence)
ok 2.1 HELD closest margin +0.116 m/s no counterexample in 4 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 2.2 HELD closest margin +0.257 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 3.1 HELD closest margin +0.207 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 4.1 HELD closest margin +0.193 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 5.1 HELD closest margin +0.262 m no counterexample in 4 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
ok 6.1 HELD closest margin +0.228 m no counterexample in 24 trials; from the 4 uniformly random ones, failure rate below 75 % (95 % confidence)
Expected_Break (3 lines: must break)
ok 1.2 BROKEN margin -0.439 m 16 trials push.force = 201 N, push.angle = 179 deg, push.phase = 0.56 (stride phase) (not shrunk, seed 3844575921)
ok 4.2 BROKEN margin -0.43 m 16 trials payload.mass = 15.2 kg (not shrunk, seed 3160059130)
ok 6.2 BROKEN margin -0.441 m 15 trials latency.duration = 0.05 s (not shrunk, seed 229287175)
gate GREEN: every requirement meets its expectation (8 held as expected, 3 broke as expected; 201 trials, pinned seeds first, then the quick budget)golem init
Copies the Kiro pack (hooks, steering, agents, skills, MCP entry) into the project .kiro/.
golem init [dir] [--force]No recorded output for this command in the transcript.
golem mcp
Starts the stdio MCP server for Kiro agents.
golem mcp [--app <dir>]Real output, golem mcp, over stdio. Node 21 on Windows, the G1 app, 11 lines.
$ golem mcp
> tools/list
list_requirements: List every requirement in the Requirements_Files in file order, with its EARS line and its last status from the last run
check_requirement: Compile one EARS line against the lexicon of the app without running any trial and without writing any file. Returns Dia
run_requirement: Run one requirement for at most `budget` random trials (pinned seeds first, default 24) and return its verdict: status,
falsify: Search for a counterexample to one requirement: pinned seeds, random trials, guided search, then shrinking to the mildes
get_counterexample: Return the most recently pinned counterexample of a requirement: scenario with units, seed and robustness with unit.
replay: Re-run a pinned counterexample exactly (the latest, or the one with `seed`) and return a 10 Hz trace summary of at most
explain_margin: Replay the latest pinned counterexample (or the closest scenario of the last run) and report which signal has the lowest
... 37 more lines in docs/cli-transcript.mdMCP tools
golem mcp speaks MCP over stdio. A Kiro agent gets these tools, so it can falsify, read a counterexample and explain the margin without a shell.
| Tool | What it does |
|---|---|
list_requirements | every requirement with its EARS line and last status. |
check_requirement | compile one EARS line without running anything. |
run_requirement | run one requirement with random trials, pinned seeds first. |
falsify | search for the mildest counterexample, with shrinking. |
get_counterexample | the latest pinned counterexample of a requirement. |
replay | re-run a pinned counterexample and summarise its trace. |
explain_margin | which signal has the lowest margin, and when. |
propose_requirement | record a proposed EARS line in `.kiro/specs/<robot>/proposals.md` for a human to review. |
A call, as recorded in the transcript:
> tools/call falsify {"reqId":"1.3","budget":96} (5.4 s, isError=false)
1.3 broken: margin -0.439 m at push.force = 72.1 N, push.angle = 88.1 deg, push.phase = 0.277 (stride phase) (seed 1291121316), 19 trials, shrunk; reproduce: npx golem-spec replay 1.3 [Expected_Hold:
{"expectation":"Expected_Hold","meetsExpectation":false,"reqId":"1.3","status":"broken","trials":19,"randomTrials":0,"guidedTrials":0,"closest":{"robustness":-0.44193487868792536,"scenario":{"push.angle":1.5384007323433917,"push.force":72.70052049021564,"push.phase":0.2771663910578735},"seed":3254842707,"unit":"m"},"counterexample":{"reqId":"1.3","scenario":{"push.angle":1.5384007323433917,"push.f ... [171 more characters not shown]Tool calls return a one-line summary and then a JSON block. See the full transcript.
Hooks
The Stop hook is the gate: while a line is red, golem gate --kiro blocks the stop and returns the counterexamples as the agent's next message. Kiro fires it once per user turn, so the repair loop also lives in the tuner agent and the workflow below.
| Scope | Hook | Trigger | Command | Timeout |
|---|---|---|---|---|
| Installed by golem init | Check requirements on save | PostFileSave | npx --no-install golem-spec check | 30 s |
| Installed by golem init | Falsify controller on save | PostFileSave | npx --no-install golem-spec test --budget 24 | 300 s |
| Installed by golem init | Gate the agent | Stop | npx --no-install golem-spec gate --kiro | 300 s |
| Installed by golem init | Test after spec task | PostTaskExec | npx --no-install golem-spec test | 300 s |
| Installed by golem init | Summon the ghosts | Manual | npx --no-install golem-spec test --budget 256 | 1800 s |
| This repository | Typecheck gate | Stop | node scripts/kiro-stop-typecheck.mjs | 180 s |
| This repository | Unit tests for the saved engine file | PostFileSave | npx vitest related --run --root skeleton --passWithNoTests | 300 s |
| This repository | Compile robot requirements | PostFileSave | node skeleton/dist/cli/main.js check --app apps/stagger && node skeleton/dist/cli/main.js check --app apps/candy | 60 s |
Agents
| Agent | Job | Where |
|---|---|---|
golem-tuner | Repairs controller code until npx --no-install golem-spec gate passes. Never edits requirements. | installed by golem init |
golem-skeptic | Looks for harsher, believable requirements that break the robot, and proposes them. | installed by golem init |
golem-scribe | Turns plain-language robot behaviour into GOLEM EARS lines and files them as proposals. | installed by golem init |
golem-auditor | Read-only principal-engineer reviewer for GOLEM modules: probes real behaviour, judges test quality, writes a ranked defect list to docs/reviews/. | this repository only |
The tuner never edits a requirement. A guard hook denies writes to requirements.md for that agent. New lines go through the propose_requirement tool into proposals.md for a human.
Skills and steering
| Skill | When it applies |
|---|---|
robot-ears | Write robot EARS requirement lines with units and ranges that compile with npx --no-install golem-spec check. Use it when writing or editing acceptance criteria for a robot, or when npx --no-install golem-spec check reports a compile error. |
falsify-and-fix | Repair a robot controller until its requirements hold. Use it when a requirement is red, a npx --no-install golem-spec test or npx --no-install golem-spec gate run reports a counterexample, or a gate blocked the stop. |
The steering file golem-ears.md (6,485 bytes) is included whenever a requirements.md is open.
Power, workflow and Crew app
Power
The golem Power bundles the MCP server, the skills and the steering: Turns the EARS acceptance criteria of a Kiro spec into physics property tests for robot controllers, and gates the agent until every requirement holds.
Workflow
The falsify-and-fix workflow repeats the tuner and golem gate up to 6 times and pauses if the gate is still red. The kit README marks its file format as the least verified part of the pack.
{
"name": "falsify-and-fix",
"nodes": [
{
"type": "repeat",
"id": "repair_loop",
"maxIterations": 6,
"onMaxIterations": "pause",
"stopCondition": {
"fileCheck": { "path": ".golem/report.json", "jsonPath": "meta.lastGateExitCode", "value": 0 }
},
"nodes": [
{
"type": "step",
"id": "tune",
"agent": "golem-tuner",
"prompt": "Run npx --no-install golem-spec falsify, fix the controller, re-run until it holds."
},
{
"type": "step",
"id": "gate",
"agent": "golem-tuner",
"prompt": "Run `npx --no-install golem-spec gate` (without --kiro) in the app directory. Report its full stdout. If it exits 1 (usage, compile or runtime error), stop and report the output unchanged."
}
]
}
]
}Crew app
GOLEM Night Watch: Runs the skeptic overnight and writes a summary of the proposals it made. It runs the agent golem-skeptic on the cron expression 0 3 * * * with network permission off, and ends each run with a summary in the run’s output. The manifest follows the documented Crew fields (crons, permissions, store assets). It has not been installed on a live Crew gateway.
The EARS dialect
GOLEM accepts Kiro's five EARS patterns. Every number carries a unit; a line that matches no phrase fails golem check with the closest phrase as the suggestion. The tables below are generated from the two lexicon.ts files.
| Pattern | Shape | Becomes |
|---|---|---|
| Ubiquitous | THE robot SHALL <response> | The response holds for the whole episode after warm-up. |
| Event | WHEN <trigger> THE robot SHALL <response> | The trigger is injected, and the response is checked over the window after it. |
| State | WHILE <state> THE robot SHALL <response> | The state is applied for the episode, or checked at each instant. |
| Unwanted | IF <fault> THEN THE robot SHALL <response> | The fault is injected like a trigger. |
| Optional | WHERE <feature> THE robot SHALL <response> | Applies only when the app enables the feature. |
Ranges in a trigger are the search space: up to 200 N is force from 0 to 200 N, from any direction is 0 to 360 deg, at any point in its stride is gait phase 0 to 1. A single value, such as for 0.2 s, is fixed.
Stagger: Unitree G1
The robot may be called golem, G1, robot after THE.
| Response phrase | Unit | Signals read |
|---|---|---|
| stay upright | m | pelvis_z tilt_deg |
| keep its pelvis above {length} | m | pelvis_z |
| track the commanded speed within {speed} | m/s | forward_speed commanded_speed episode_time |
| not drift sideways more than {length} | m | lateral_drift |
| Trigger, state or fault phrase | Latest onset |
|---|---|
| the pelvis is pushed with {range:force} for {duration} from {direction} at {phase} | |
| walking on a slope of {range:angle} | |
| carrying a payload of {range:mass} | |
| the floor friction drops to {ratio} | |
| the sensor latency rises to {range:duration} | |
| commanded to walk at {range:speed} |
The 11 compiled lines, with the search space each one defines
| Id | Pattern | Line | Searched dimensions |
|---|---|---|---|
| 1.1 | event | WHEN the pelvis is pushed with up to 60 N for 0.2 s from any direction at any point in its stride THE robot SHALL stay upright for 3 s | push.force push.angle push.phase |
| 1.2 | event | WHEN the pelvis is pushed with up to 250 N for 0.2 s from behind at any point in its stride THE robot SHALL stay upright for 3 s | push.force push.angle push.phase |
| 1.3 | event | WHEN the pelvis is pushed with up to 100 N for 0.2 s from any direction at any point in its stride THE robot SHALL stay upright for 3 s | push.force push.angle push.phase |
| 2.1 | ubiquitous | THE robot SHALL track the commanded speed within 0.15 m/s | none |
| 2.2 | event | WHEN commanded to walk at 0 m/s to 0.8 m/s THE robot SHALL stay upright for 5 s | command.speed |
| 3.1 | event | WHEN walking on a slope of up to 8 deg THE robot SHALL stay upright for 5 s | slope.angle |
| 4.1 | event | WHEN carrying a payload of up to 10 kg THE robot SHALL stay upright for 5 s | payload.mass |
| 4.2 | event | WHEN carrying a payload of up to 20 kg THE robot SHALL stay upright for 5 s | payload.mass |
| 5.1 | event | WHEN the floor friction drops to 30% THE robot SHALL stay upright for 5 s | none |
| 6.1 | event | WHEN the sensor latency rises to up to 40 ms THE robot SHALL stay upright for 5 s | latency.duration |
| 6.2 | event | WHEN the sensor latency rises to up to 100 ms THE robot SHALL stay upright for 5 s | latency.duration |
Candy: Franka Panda
The robot may be called arm, Panda, robot after THE.
| Response phrase | Unit | Signals read |
|---|---|---|
| drop every candy into the bowl of its colour within {duration} | candies | candies_sorted candies_misplaced candies_dropped_outside candies_active |
| keep every link at least {length} from the hand | m | min_link_hand_distance |
| keep its fastest link below {speed} | m/s | fastest_link_speed |
| not drop a candy outside the bowls | candies | candies_dropped_outside |
| never press on the table with more than {force} | N | table_force |
| Trigger, state or fault phrase | Latest onset |
|---|---|
| a hand reaches in from {direction} at {range:speed} | |
| the candies weigh {range:mass} | |
| the vacuum weakens to {range:ratio} | |
| the hand tracker lags by {range:duration} | |
| candies land anywhere on the tray | |
| the hand tracker lags by {range:duration} and a hand reaches in from {direction} at {range:speed} |
The 8 compiled lines, with the search space each one defines
| Id | Pattern | Line | Searched dimensions |
|---|---|---|---|
| 1.1 | event | WHEN a hand reaches in from any direction at up to 1.5 m/s THE arm SHALL keep every link at least 0.10 m from the hand | hand.angle hand.speed hand.entry hand.height |
| 2.1 | event | WHEN a hand reaches in from any direction at up to 1.5 m/s THE arm SHALL keep its fastest link below 1.0 m/s | hand.angle hand.speed hand.entry hand.height |
| 3.1 | event | WHEN candies land anywhere on the tray THE arm SHALL never press on the table with more than 20 N | candy.0.x candy.0.y candy.1.x candy.1.y candy.2.x candy.2.y candy.3.x candy.3.y candy.4.x candy.4.y candy.5.x candy.5.y |
| 4.1 | event | WHEN candies land anywhere on the tray THE arm SHALL not drop a candy outside the bowls | candy.0.x candy.0.y candy.1.x candy.1.y candy.2.x candy.2.y candy.3.x candy.3.y candy.4.x candy.4.y candy.5.x candy.5.y |
| 5.1 | event | WHEN candies land anywhere on the tray THE arm SHALL drop every candy into the bowl of its colour within 45 s | candy.0.x candy.0.y candy.1.x candy.1.y candy.2.x candy.2.y candy.3.x candy.3.y candy.4.x candy.4.y candy.5.x candy.5.y |
| 6.1 | event | WHEN the candies weigh 0.005 kg to 0.060 kg THE arm SHALL drop every candy into the bowl of its colour within 45 s | candy.mass |
| 7.1 | event | WHEN the vacuum weakens to 50% to 100% THE arm SHALL drop every candy into the bowl of its colour within 45 s | vacuum.ratio |
| 8.1 | event | WHEN the hand tracker lags by up to 0.3 s and a hand reaches in from any direction at up to 1.5 m/s THE arm SHALL keep every link at least 0.10 m from the hand | tracker.lag hand.angle hand.speed hand.entry hand.height |
Hover: Skydio X2
The robot may be called drone, quadrotor, X2, robot after THE.
| Response phrase | Unit | Signals read |
|---|---|---|
| stay within {length} of its hover point | m | hover_distance |
| keep its tilt below {angle} | deg | tilt_deg |
| stay above {length} | m | altitude |
| Trigger, state or fault phrase | Latest onset |
|---|---|
| a gust of {range:force} hits it for {duration} from {direction} | |
| the battery sags to {range:ratio} | |
| the position estimate lags by {range:duration} | |
| a gust of {range:force} hits it for {duration} from {direction} while the position estimate lags by {range:duration} |
The 6 compiled lines, with the search space each one defines
| Id | Pattern | Line | Searched dimensions |
|---|---|---|---|
| 1.1 | event | WHEN a gust of up to 2 N hits it for 0.5 s from any direction THE drone SHALL stay within 0.25 m of its hover point for 4 s | gust.force gust.angle |
| 1.2 | event | WHEN a gust of up to 3 N hits it for 0.5 s from any direction THE drone SHALL keep its tilt below 30 deg for 4 s | gust.force gust.angle |
| 1.3 | event | WHEN a gust of up to 20 N hits it for 0.5 s from any direction THE drone SHALL stay within 1.0 m of its hover point for 4 s | gust.force gust.angle |
| 2.1 | event | WHEN the battery sags to 60% to 100% THE drone SHALL stay above 0.5 m for 4 s | battery.ratio |
| 3.1 | event | WHEN a gust of up to 2 N hits it for 0.5 s from any direction while the position estimate lags by up to 0.10 s THE drone SHALL stay within 0.35 m of its hover point for 4 s | gust.force gust.angle estimate.lag |
| 3.2 | event | WHEN a gust of up to 2 N hits it for 0.5 s from any direction while the position estimate lags by up to 0.30 s THE drone SHALL stay within 0.35 m of its hover point for 4 s | gust.force gust.angle estimate.lag |