Turn Setup Knowledge Into a Runnable README Quickstart

If a teammate asks a setup question you already documented, the README may contain the fact but still fail as an interface. A useful quickstart gets a clean machine to one expected result without private context.

This guide belongs to reel R094. Comment README for the matching module and runnable starter.

Define the boundary before building

Input: repository files, supported runtime versions, install command, configuration keys, sample command, expected output, common failures, and clean-machine constraints.

Output: a first-screen quickstart, prerequisites, copy-paste commands, expected result, troubleshooting table, and clean-machine test report.

The starter keeps exact checks in code and gives Claude only the reviewable drafting work. Dry-run is the default. Live mode can call Anthropic's Messages API, but it still returns a draft and performs no external action.

Paste this boundary into Claude Code before asking for implementation:

Workflow: Turn Setup Knowledge Into a Runnable README Quickstart
Input: repository files, supported runtime versions, install command, configuration keys, sample command, expected output, common failures, and clean-machine constraints
Output: a first-screen quickstart, prerequisites, copy-paste commands, expected result, troubleshooting table, and clean-machine test report

Map the trigger, strict input fields, deterministic code checks, Claude drafting step, approval gate, failure queue, and saved evidence. Use null for missing facts. Do not change code or call an external service yet.

The modules that matter

Put the runnable path first

Start with supported runtime versions, one install command, configuration from an example file, one run command, and the expected output. Move architecture history below the first success.

Derive facts from the repo

Read package scripts, lockfiles, container files, example configuration, and CI. Do not copy commands from memory. Mark optional services as optional.

Test like a stranger

Use a clean container or machine with no global packages and no existing environment file. Copy every command exactly. Record the first hidden assumption, fix the README, then repeat from zero.

Rules worth keeping beside the code

Derive commands from repository files instead of memory.
Put the shortest successful path before architecture details.
Show expected output after each important command.
Test every step in a clean environment.

The dangerous version is publishing untested commands, leaking real environment values, assuming global tools, or documenting a maintainer-only setup path. The pack deliberately stops at a draft so a person can inspect those boundaries before enabling anything real.

Test the ugly paths

Supported runtime installs cleanly.
Lockfile command is correct.
Missing configuration gives a useful error.
Sample command returns the shown output.
Troubleshooting covers observed failures only.

The final verification is concrete: Give the README to a clean container or new machine, copy each command without extra knowledge, and record the first point where the expected output differs.

Use this prompt to turn the evidence into acceptance tests:

Design tests for Turn Setup Knowledge Into a Runnable README Quickstart using only the attached fictional fixtures.
Cover the normal path, missing input, malformed input, a repeated event, a permission failure, a dependency failure, and the named safety boundary.
For each test return: input, expected state, prohibited side effect, and evidence to save.
Do not execute external actions.

Run the pack locally

The ZIP is a complete Node 22 starter with no third-party npm dependency. It includes an importable n8n webhook, Docker Compose, GitHub Actions validation and manual-run workflows, deterministic samples, and tests.

npm test
npm run validate
npm run sample
cp .env.example .env
docker compose up --build

Only set WORKFLOW_MODE=live, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL after the dry-run output and tests make sense for your system. Keep real secrets in the environment, never in the n8n export.

Download the runnable pack

Start with the fictional dry-run. It validates the input and returns a reviewable draft without changing code, production data, customer accounts, or an external service.

Before enabling a real action

Replace every fictional fixture, assign the approval owner, define the duplicate key, set a timeout and retry rule, and save the original evidence. Then test one failure on purpose. If the workflow cannot stop visibly and replay safely, it is not ready to act.