nukadoko acceptance loop
A person approves a change by reading the feature file and the run
summary: the run is the evidence, and where the approval is recorded is
the team's process. The feature is written before the implementation it judges,
from the criteria and never from the program's output, which is what
makes a green run evidence rather than agreement. This file is the order
of work: open the reference a step names when you reach it.
node_modules/nukadoko/llms.txt names every command, flag, and code.
Before the first command
Say in two or three sentences what the loop is for and what it will
touch, then one line for each of these that applies:
- A
mutates: true step that reaches past the project (a real service, a
shared database, a file outside scratch) gets a go-ahead before its first
nuka do, once, not on every retry. A step that writes only under scratch,
or only to a server a fixture or nukadoko.program.ts started, needs none
(references/writing-steps.md, "Asking before a step changes something").
- A step that needs
page, context, pageAs, or request needs the project's
own playwright; nuka check reports playwright-missing with the
install line. Adding it is a dependency change: ask first. A page step
makes nuka run open a browser and take minutes. A project on e2e
drives it through e2e instead (references/fixtures.md, last section).
- A Playwright MCP server, when the loop explores a browser app whose
state cannot be repeated, drives the real application with whatever
login it holds. A click that submits something there needs the same
go-ahead (
references/exploring.md).
Run-time output lands under .nukadoko/, gitignored, and can hold
credentials in plaintext. nukadoko makes no outbound calls of its own and
never commits, pushes, or publishes. Keep the narration short.
Where to start
Run nuka from the directory that holds the config, and nuka init first
when there is none (references/running.md, "Setting up"); an app to start
needs nukadoko.program.ts (references/program.md). A Ruby project
writes steps as the "Ruby" section of llms.txt says. Pick one line:
- Prose only (a ticket, a request, a conversation):
references/from-prose.md, then line 2.
- Criteria sentences, no scenario yet:
references/scenario-rules.md
and references/writing-the-feature.md, then the loop.
- A concrete scenario, or one you can write directly: the loop.
- A path already run with
nuka do or a Playwright MCP server:
write the scenario from what you ran (references/exploring.md, "Then
fix what you found"), then the loop at step 3.
- A browser app whose state cannot be repeated (an account that
opens once): drive it through the host's Playwright MCP server,
connected when its
browser_* tools are listed; a Claude Code host
adds it with claude mcp add playwright npx @playwright/mcp@latest
once the person agrees. Then line 4 (references/exploring.md,
"Exploring state that cannot be repeated").
- A scenario the person wants to check step by step with you: walk
it with
nuka run <file>:<line> --step (references/reviewing.md).
If none is true, ask what this is supposed to do before writing anything.
The loop
- Feature first. Write the
.feature from the criteria, by
references/scenario-rules.md, and copy the criteria verbatim under
Feature: (references/writing-the-feature.md). Every expected value
is one the criteria state; a value they do not state is a question for
a person, not a guess and not a value read off the program.
- Steps.
nuka steps lists the vocabulary, nuka describe <step> one
contract; reuse before scaffolding. nuka scaffold --feature <file> stubs
each undefined line and prints each stub's own nuka scaffold ... --replace line. Redo the When that runs a program or sends a request, and
the Thens that read it, from those lines with --description, --command <entry point> (--cwd, --argv) or --request "<METHOD> <path>", and
--from <step>.<key> per value an earlier step returns (its producer has
to return that key already). A step that needs only what an earlier line
did requires the state that line's step gives (references/states.md).
A Then declares claims, never run (references/checking-steps.md). Run
each alone with nuka do <step> --args '<json>'
(references/writing-steps.md). Finished projects: references/examples/.
nuka check <feature>. Fix every error and read every warning: a
warning is a question about intent, not noise. Each finding names its
file, a fix: (an edit) or do: (a command) line; apply or run it.
nuka run <feature> until no table row is failed, reading the step
record a failure names first (references/diagnosing.md), then once more
with --order shuffled (references/running.md). A red Then, an
unexpected-failure, or a held row whose control passed
(references/verdicts.md) is fixed in the code or by asking the person,
never by weakening it or tagging it away. Read "What this run does not show",
measured: none (references/reviewing.md), undeclared-write, and each judgment- finding (references/judgments.md).
- Commit before the run you report, push, and open the pull request;
CI posts the summary of
nuka run --base <the base> (docs/ci.md). Run
it first: unproven, moved, and intent- findings are red
(references/verdicts.md, and INTENT.md in references/done.md).
- Decide where the feature lives, in the same pull request: the
product's core path moves into
featuresDir, which nuka run runs on
every commit; a feature for one change stays outside it, named in
additionalFeatureDirs (references/maintenance.md).
A lesson from a run becomes an example row, then a rule, then a finding
code (references/scenario-rules.md, "How this file grows").
What not to do
- Don't write a Then from what the program printed, or edit one after a red
run without the person's word: either is the implementation grading itself.
- Don't fill in a requirement the source never stated (
references/from-prose.md).
- Don't run a step that reaches past the project without a go-ahead, and
don't keep fixing one step past three cycles: report where it stands. A
prompt that gives a different budget overrides the three.
- Don't hand-edit a step record or a run summary: it was measured, and
editing it turns it back into an unmeasured account.
- Don't act unasked on a note about a step you are not writing:
report it (
references/maintenance.md).
1---2name: nukadoko3description: Use when turning a requirement into a Gherkin scenario and the run that is its evidence, for a person to review, starting from whatever is on hand, whether that is raw prose with no stated acceptance criteria yet (a ticket, a request, a conversation), acceptance criteria that still need concrete scenarios, a scenario ready to write, a path already explored one `nuka do` call at a time and now worth fixing in a scenario, a browser app whose state cannot be repeated and has to be explored through a Playwright MCP server first, or a scenario a person wants to walk one step at a time, the run paused after each step while the agent explains its record and waits for the person's answer.4compatibility: Requires the nukadoko npm package installed in the project (a devDependency), whose nuka CLI is run as `npx nuka`; the loop below shells out to it (nuka init, nuka steps, nuka describe, nuka scaffold, nuka do, nuka check, nuka run, nuka step, nuka verdict, nuka judge).5license: MIT6metadata:7 source: https://skillmd.com/skills/meganemura/nukadoko8---910# nukadoko acceptance loop1112A person approves a change by reading the feature file and the run13summary: the run is the evidence, and where the approval is recorded is14the team's process. The feature is written before the implementation it judges,15from the criteria and never from the program's output, which is what16makes a green run evidence rather than agreement. This file is the order17of work: open the reference a step names when you reach it.18`node_modules/nukadoko/llms.txt` names every command, flag, and code.1920## Before the first command2122Say in two or three sentences what the loop is for and what it will23touch, then one line for each of these that applies:2425- A `mutates: true` step that reaches past the project (a real service, a26 shared database, a file outside `scratch`) gets a go-ahead before its first27 `nuka do`, once, not on every retry. A step that writes only under `scratch`,28 or only to a server a fixture or `nukadoko.program.ts` started, needs none29 (`references/writing-steps.md`, "Asking before a step changes something").30- A step that needs `page`, `context`, `pageAs`, or `request` needs the project's31 own `playwright`; `nuka check` reports `playwright-missing` with the32 install line. Adding it is a dependency change: ask first. A `page` step33 makes `nuka run` open a browser and take minutes. A project on e2e34 drives it through e2e instead (`references/fixtures.md`, last section).35- A Playwright MCP server, when the loop explores a browser app whose36 state cannot be repeated, drives the real application with whatever37 login it holds. A click that submits something there needs the same38 go-ahead (`references/exploring.md`).3940Run-time output lands under `.nukadoko/`, gitignored, and can hold41credentials in plaintext. nukadoko makes no outbound calls of its own and42never commits, pushes, or publishes. Keep the narration short.4344## Where to start4546Run `nuka` from the directory that holds the config, and `nuka init` first47when there is none (`references/running.md`, "Setting up"); an app to start48needs `nukadoko.program.ts` (`references/program.md`). A Ruby project49writes steps as the "Ruby" section of `llms.txt` says. Pick one line:50511. **Prose only** (a ticket, a request, a conversation):52 `references/from-prose.md`, then line 2.532. **Criteria sentences, no scenario yet**: `references/scenario-rules.md`54 and `references/writing-the-feature.md`, then the loop.553. **A concrete scenario, or one you can write directly**: the loop.564. **A path already run** with `nuka do` or a Playwright MCP server:57 write the scenario from what you ran (`references/exploring.md`, "Then58 fix what you found"), then the loop at step 3.595. **A browser app whose state cannot be repeated** (an account that60 opens once): drive it through the host's Playwright MCP server,61 connected when its `browser_*` tools are listed; a Claude Code host62 adds it with `claude mcp add playwright npx @playwright/mcp@latest`63 once the person agrees. Then line 4 (`references/exploring.md`,64 "Exploring state that cannot be repeated").656. **A scenario the person wants to check step by step with you**: walk66 it with `nuka run <file>:<line> --step` (`references/reviewing.md`).6768If none is true, ask what this is supposed to do before writing anything.6970## The loop71721. **Feature first.** Write the `.feature` from the criteria, by73 `references/scenario-rules.md`, and copy the criteria verbatim under74 `Feature:` (`references/writing-the-feature.md`). Every expected value75 is one the criteria state; a value they do not state is a question for76 a person, not a guess and not a value read off the program.772. **Steps.** `nuka steps` lists the vocabulary, `nuka describe <step>` one78 contract; reuse before scaffolding. `nuka scaffold --feature <file>` stubs79 each undefined line and prints each stub's own `nuka scaffold ...80 --replace` line. Redo the When that runs a program or sends a request, and81 the Thens that read it, from those lines with `--description`, `--command82 <entry point>` (`--cwd`, `--argv`) or `--request "<METHOD> <path>"`, and83 `--from <step>.<key>` per value an earlier step returns (its producer has84 to return that key already). A step that needs only what an earlier line85 did `requires` the state that line's step `gives` (`references/states.md`).86 A Then declares `claims`, never `run` (`references/checking-steps.md`). Run87 each alone with `nuka do <step> --args '<json>'`88 (`references/writing-steps.md`). Finished projects: `references/examples/`.893. **`nuka check <feature>`.** Fix every error and read every warning: a90 warning is a question about intent, not noise. Each finding names its91 file, a `fix:` (an edit) or `do:` (a command) line; apply or run it.924. **`nuka run <feature>`** until no table row is `failed`, reading the step93 record a failure names first (`references/diagnosing.md`), then once more94 with `--order shuffled` (`references/running.md`). A red Then, an95 `unexpected-failure`, or a `held` row whose control passed96 (`references/verdicts.md`) is fixed in the code or by asking the person,97 never by weakening it or tagging it away. Read "What this run does not show",98 `measured: none` (`references/reviewing.md`), `undeclared-write`, and each `judgment-` finding (`references/judgments.md`).995. **Commit before the run you report**, push, and open the pull request;100 CI posts the summary of `nuka run --base <the base>` (`docs/ci.md`). Run101 it first: `unproven`, `moved`, and `intent-` findings are red102 (`references/verdicts.md`, and `INTENT.md` in `references/done.md`).1036. **Decide where the feature lives**, in the same pull request: the104 product's core path moves into `featuresDir`, which `nuka run` runs on105 every commit; a feature for one change stays outside it, named in106 `additionalFeatureDirs` (`references/maintenance.md`).107108A lesson from a run becomes an example row, then a rule, then a finding109code (`references/scenario-rules.md`, "How this file grows").110111## What not to do112113- Don't write a Then from what the program printed, or edit one after a red114 run without the person's word: either is the implementation grading itself.115- Don't fill in a requirement the source never stated (`references/from-prose.md`).116- Don't run a step that reaches past the project without a go-ahead, and117 don't keep fixing one step past three cycles: report where it stands. A118 prompt that gives a different budget overrides the three.119- Don't hand-edit a step record or a run summary: it was measured, and120 editing it turns it back into an unmeasured account.121- Don't act unasked on a note about a step you are not writing:122 report it (`references/maintenance.md`).