Skip to main content
kane-cli design tests takes one committed use-case and produces everything needed to prove it: acceptance criteria (ACs), scenarios, and exactly one runnable test per scenario. It works as a conversation, on the same chat surface that kane-cli context extract uses. Everything the engine produces starts as derived knowledge for you to review. Your approval promotes it, and nothing becomes trusted without that approval.
<ref> is a short logical id (uc-manage-the-cart, t-login-smoke) or a full cid (content id).

​
Flags

​
The session: five phases

An interactive run is a chat. The engine works through the phases in order and pauses after each one for your approval. You steer it in plain words.
  1. Grounding. The engine reads the use-case and its cited criteria, follows the citations into the actual source text, and checks what already exists that it can reuse.
  2. Invariant ACs. These are promises that hold on every path, each with a complete oracle (an expected result a machine can check). If the source never states the expected result for a promise, the engine records a missing-expected-result gap with a recommended default instead of inventing an answer.
  3. Scenarios. The engine expands the use-case into paths using test-design techniques: happy, negative, boundary, and edge paths, plus security, accessibility, performance, and i18n paths where the use-case calls for them. Existing scenarios are linked, never duplicated, and preconditions become dependencies.
  4. Path ACs and wiring. The engine writes criteria for each scenario and records which scenario exercises which invariant. An invariant that no scenario exercises becomes an invariant-unexercised gap.
  5. Tests. The engine writes exactly one test per scenario (strict 1:1). Pairs are scored and cut to fit the budget. Each kept test has a runnable body, a step that captures a baseline when a check needs a before and after comparison, and a written check whose expected value comes from its AC. A check that disagrees with its criterion is rejected, so a test cannot quietly assert something weaker than the requirement.
Between phases the session pauses on a check-in panel, the same kind of panel extract uses. The headline reads <phase> done — next: <next>. A dim line under it explains in plain words what the finished phase produced. The rows are:
  • continue to <next> (row 1). Pressing Enter at every check-in walks through the whole design.
  • view what's saved
  • finish here
  • ✎ adjust — tell me what to change
Typing anywhere opens the ✎ editor, and your words steer the engine (rename, drop, redirect) before the next phase. Questions that need a typed value. When an answer has to be a concrete value, such as a URL or a fixture id, the question does one of two things. It either offers an option row that takes input, where selecting the row opens an inline editor so the answer carries both the pick and your value, or it tells you to type the value directly. A plain option row sends only its label, so the plain options on such a question are the real alternatives (use a placeholder, reduce scope, skip). If a needed value does not arrive, the agent asks once more and then continues with the fallback it stated. It announces this in the narrative; it never happens silently. In headless runs, each phase reports its progress. Any question pauses an agent-mode run, which you can resume. A high-risk question stops a ci-mode run with a failure. Each phase still commits and reports on the event stream as it completes. See Automation.

​
What you get

A design run commits to the graph and writes files. Each kept test is written as a normal, runnable *_test.md file under <cwd>/.testmuai/tests/:
Three things to notice:
  • @verifies tags bind each assert step to the acceptance criteria it proves. kane-cli cover measures coverage against this link. It is captured when the test is written, and it is permanent and auditable.
  • {{variables}} appear wherever the requirements did not specify a value, such as the store URL or a known in-stock product. See Variables declared by design below.
  • The assurance: frontmatter links the file to its design entry in the graph, so coverage lookups stay exact even after you move the file.

​
Variables declared by design

Before naming a variable, design reads every *.json file in your variable directories and reuses a name you already have. Each name it has to create is declared: an empty stub is added to .testmuai/variables/assurance.json. Design never writes a value, and never overwrites a key that already exists anywhere. You are told about new variables twice:
  • As the phase commits: ⚒ declared 2 new variables — store_url · in_stock_product (values needed).
  • At the end of the run: 2 variable(s) need values — see .testmuai/variables/assurance.json.
On the --mode agent stream, these two moments are separate events:
  • variables_declared lists the stubs a phase commit wrote: file, plus variables[] with name, description and secret. It fires in the tests phase, just before that phase’s commit event.
  • variables_summary lists every name the run declared. It is sent after session_complete when a run completes cleanly; a paused run does not send it.
See Automation for the stream. Fill in the values before you author the tests. If a name has no value, the run warns you and types the name as written. An agent fills in the values it already has from your documents or your messages and asks you for the rest. A secret value goes straight into the file, never through the chat. See Variables & context.

​
What else the run records

Alongside the tests, the run records:
  • the ACs and scenarios themselves, and the wiring between them;
  • gap nodes, with full context, for everything it could not resolve;
  • a rationale file per test (under .context/design/rationale/) that design explain replays.
You also see warnings at commit time, for example when a test’s @verifies list claims more criteria than its written check actually asserts. Design output starts as derived, like everything else. Review it with kane-cli context review, or browse it with kane-cli context view.

​
From design to execution

A designed test is a normal test file, but it is still derived and it has never been run. Work through it in this order:
  1. Review the design output like anything else the engine produces. Approve, edit, or reject the generated ACs, scenarios, and tests with kane-cli context review. The commit-time warnings appear again there.
  2. Author each kept test once. After that it runs in batches like any other test.
kane-cli testrun can also author fresh tests itself: they are classified as author at preflight and consolidated after the run. kane-cli testmd run is the way to author a single test. See Coverage. Until a test’s first authored run, kane-cli cover reports its criteria as covered on paper but not yet proven. This is intentional.

​
Gates, re-runs, and --force

Designing against an unreviewed use-case. If the use-case is still unreviewed (derived), the run stops so you can decide explicitly:
  • On a terminal, you see what this means and choose.
  • In agent mode, the run exits 2 with the review command to run in next.
  • In ci mode, the run refuses outright.
--allow-unreviewed skips this gate on purpose. The recommended path is to review the use-case first with context review. Re-runs check whether the design is stale. If a use-case already has a live design, design does not silently redesign it. It asks you what to do:
  • On a terminal, the session tells you whether the design is current or stale and what a redesign would supersede. You can view the design, redesign it, refresh a stale design first with maintain evolve, or pick another use-case. A redesign asks for your reason, which goes on the record.
  • In agent mode, the run exits 2 with the follow-up commands in next, including the --force form.
  • In ci mode, the run fails without redesigning.
design tests has no --because flag. A headless --force run proceeds and records a reason automatically. --force regenerates the scenario and test pairs and supersedes the old ones. ACs are deduplicated first: if the engine produces an AC equivalent to an existing one, it reuses the existing node instead of adding a copy.
  • If the staleness comes from a source document you just changed, kane-cli maintain reconcile offers the same redesign as part of reviewing the changed source.
  • For staleness from older changes, kane-cli maintain evolve redesigns the use-case and tells you first what the redesign will affect.
Citations are verified before they commit. Every citation a design run wants to record is checked against the pinned source text before anything lands. A citation that does not match is sent back to the agent to fix, so designed items never carry made-up provenance.

​
design explain: replay the why

Replays the rationale recorded at design time, without ever calling a model:
  • For a test: the technique that produced it, the boundary values considered, the covering-array strength and why it was chosen, the criteria it verifies, and the scenario it automates.
  • For a scenario, AC, or gap: its content plus every recorded judgement and review verdict.
If you ask “why does this test exist?” six months later, you get the answer recorded at design time, not a reconstruction.

​
Extending the technique catalog

The design engine includes a built-in catalog of test-design techniques and surface profiles. To extend it for one store, add YAML files under .context/design/. An entry with an existing id replaces the built-in one, and a new id adds an entry. No upgrade is needed.

​
Exit codes

​
Next steps