Runic
HANDOFF

A plan-mode kickoff, a memory file, and hooks that hold

KICKOFF.md is a prompt under 40 lines: read the files in order, run Milestone 0 if the stack is unknown, ask for the sign-in method if nothing states it, then for each milestone plan, branch, write failing tests named by id, implement, verify, review with a fresh subagent, commit, and ask before the next. CLAUDE.md keeps it honest afterwards; .claude/ holds what a request cannot.

Try it free →Read the docs

What the kickoff says

KICKOFF.md starts with the command to run, claude --permission-mode plan in the repo root, and a rule to paste everything below the divider as the first message. The message opens with “You are building <project>: <one-liner>”, the same sentence CLAUDE.md, the spec and the brief carry, then the reading order: 1. CLAUDE.md, 2. docs/spec.md, 3. docs/plan.md, 4. docs/design-brief.md, 5. every docs/flows/*.runic and docs/sequences/*.runic, with the rule that the .runic files are the exact logic, the spec is the contract and the plan is the order, and that ids such as F1.D2.evet, S1.M3 and US-4.AC2 are shared across all of them and belong in tests, commits and questions.

Two paragraphs appear only when needed. Milestone 0 shows when CLAUDE.md carries TODO(M0) lines, that is when the install, dev, test, lint or typecheck command is unknown: propose the stack and commands, scaffold, get the test command green on one trivial test, replace the TODOs in CLAUDE.md, add the PostToolUse test hook and the PreToolUse guard against editing docs/flows/ to .claude/settings.json, commit m0: scaffold, then stop for approval. Before M1 shows when nothing in the package says how users sign in, meaning no auth block, no NF row and no flow or sequence with a sign-in word such as login, password, OTP, SSO, giriş or kimlik: “the package does not say how users sign in (docs/spec.md §Open questions: "Kimlik doğrulama yöntemi?"). Ask me for the method and the identity field first, log the answer in docs/decisions.md, then plan.”

Then the loop for each milestone M1 to the last in docs/plan.md, as six lettered steps: (a) plan mode, listing the files to create or change, the contracts touched and one test per acceptance line and per branch id, reading design/ first if it exists, then waiting for approval; (b) a branch named m<n>-<slug>, failing tests first named by id, implement until green, run lint and typecheck; (c) walk the milestone's flows end to end in the running app, the Verify line being the exit condition; (d) a subagent with a fresh context reviews the diff against the milestone and fixes real gaps only; (e) paste the test summary, commit as m<n>: <summary> (US-…, F…), open a PR whose body is the acceptance checklist, ticked; (f) ask before the next milestone. It closes with the ask-versus-decide rule (stop only for an Open question that blocks the step; a field, entity, endpoint or external system not in the spec; an unspecified permission or security behaviour; a .runic branch with no acceptance line; otherwise decide, log it in docs/decisions.md with the id it affects, continue), a Never list (no story done with a red or skipped test, no invented fields, no edits to docs/flows/ or docs/sequences/, no two milestones on one branch) and the advice to /clear after the same correction twice.

What CLAUDE.md holds, and what it no longer does

CLAUDE.md stays under 150 lines because Claude Code reads it on every turn and adherence drops as it grows. It opens with the project name and “This repo builds <project>: <one-liner>”. Source of truth: the spec and the .runic files outrank anything inferred from code; the id legend with the package's own first entity as the E- example; the brief in the spec's Overview is the founder's own words; the product's UI language is the language the brief and the flows are written in, every label, button, status and error using the flows' exact wording, never translated; and a pointer to .claude/rules/runic-dsl.md for how to read a .runic file. Stack & commands: one line with Language, Framework and Database, each “TODO(M0): choose” when unknown, then install, dev, test, test one, lint, typecheck and migrate; a missing core command prints “TODO(M0): the command to …”, while migrate and test one print “none yet — M0 …” or “none (no migrations)” and “none — run the test command”, since a product without migrations is not an unknown stack.

Repo layout names the four docs and the design/ folder Claude Design hands off into. Conventions that differ from defaults: names verbatim; entities and fields only from the spec's Data model; Sign-in with the method and identity field when known; one State line per stateful entity giving the field, its closed value list and the rule that every transition is performed by the branch the spec's table names, at most ten such lines before the rest are pointed at the spec; every .fail is a distinct user-visible error state with its recovery; External systems to stub in tests, never called for real in CI; Async messages, the first four ->> sends, with the instruction to decide the transport and its delivery guarantee per message and log it; and tests named after the id they prove, a test name without an id being a smell. Verification asks for the test, lint and typecheck output to be pasted before saying done and for the Verify sentence to be walked with evidence. Workflow fixes one branch per milestone, the commit format and the PR body. When to ask vs. decide repeats the four reasons. Gotchas appears only when there is one: up to six failure lines such as “F1.X1 "…" — the path CONTINUES after the failure: the lines below it are the recovery, ending in F1.L1 back to "…"” or “— nothing follows it in its branch: the flow ends at this failure, so the screen stays in its error state.”, plus up to four “Assumed while planning, unconfirmed: …” lines from the plan. Compaction says what to keep: the milestone id, the modified files and the test command.

The two reading legends are no longer in it. They live in .claude/rules/runic-dsl.md with a paths frontmatter for docs/flows/**, docs/sequences/** and docs/spec.md, so they enter the context only when Claude Code works on those files. Guardrails moved out too: a sentence in CLAUDE.md is a request, so the do-not-edit-the-flows rule and the run-tests-after-edit habit are hooks in .claude/settings.json, emitted when the interview gave a test command.

How the plan defines done

docs/plan.md opens with one sentence on vertical slices, then Definition of Done (every milestone): every test named by an id in the milestone's checklist is green and none skipped; lint and typecheck are clean; the commit cites the ids; the Verify sentence was walked in the running app or an integration test and the output pasted; every decision taken on the way is in docs/decisions.md. An Order list follows, then one block per milestone headed “M<n> — <title>” with Scope and Out of scope as ids, one Verify sentence, an Acceptance checklist of - [ ] <id> lines, and a backticked /goal line: “/goal all tests named US-1.*, F1.D2.* … pass and lint and typecheck are clean”. A prefix wildcard such as US-1.* is used only when every sibling id of that prefix lands in this milestone; a family split across milestones is listed id by id, so an unattended run never demands tests another milestone owns. The hardening milestone's goal line reads “/goal every NF-* row is measured as its "How" column says and the number meets its target; lint and typecheck are clean”.

Milestones come from the spec when it has them, their ids forced to M<n> by position, NF ids in scope added to the checklist, and a generator-added NF row joining the last milestone that scopes NF ids. Otherwise Runic derives them. M1, “<entry flow> — happy path”, scopes F1, its happy branches (a .then whose body reaches no .fail, .back or .go and that sits under no such branch), the .alt success sections of the sequences it calls, those sequences' non-alternative messages, its screens and its entities; its Verify reads “Walk F1 <name> end to end in the running app, from "<first step>" to <terminal step>, taking every happy-path branch (…) once, with S1 stubbed as drawn.” M2, “<entry flow> — failures, loops and alternatives”, takes the other branches, the .fail and .back lines and every .else, .opt and .break section. Then one milestone per further flow, one for sequences no flow calls, and Non-functional hardening scoping every NF id. Every criterion is homed with the milestone that owns its F-branch ids, else its section ids, else the flow its story names, else M1, so every branch id, criterion and NF id lands in exactly one milestone, which the milestone-closure tell confirms.

The hooks, the rules file and the decisions log

.claude/settings.json is emitted only when the spec's test command is known. Its PreToolUse hook matches Edit, Write and MultiEdit, reads the tool input from stdin, and when the file_path is a .runic file under docs/flows/ or docs/sequences/ prints “docs/flows and docs/sequences are read-only — propose the change in chat” to stderr and exits 2, which Claude Code treats as a refusal it must read. Its PostToolUse hook, on the same matcher, runs <test> >&2 || exit 2 with a 300-second timeout: the whole suite, never the single-test command, because a hook only knows which file changed, and a filter that matches nothing exits green and proves nothing. A red suite therefore reaches Claude as an exit 2 with the output, instead of vanishing into the transcript.

.claude/rules/runic-dsl.md opens with the YAML frontmatter paths: ["docs/flows/**", "docs/sequences/**", "docs/spec.md"], then “# Reading Runic files”, the process legend, the sequence legend and one line on the ids. docs/decisions.md is a heading, one sentence saying it holds every decision Claude Code took without asking and every decision made in the Claude Design chat, and an empty table with the columns Date, Milestone, IDs affected, Decision, Why and Alternatives rejected. The kickoff, CLAUDE.md, the plan's Definition of Done and the design brief all point at it.

Screens go to Claude Design

Copy design brief on the done screen copies docs/design-brief.md, the one file Claude Design receives. It stands alone: the product and the verbatim brief, the audience, tone, platform, one journey per flow, the screen inventory with four states each, the components, the copy rules, the WCAG 2.2 AA numbers, what to design first, what is out of scope, every ticked flow embedded with the legend, an integration touchpoints table per sequence, and a handoff section asking for artboards named SC-n and states named by branch id, with the bundle landing in design/ where step (a) of the kickoff reads it before planning a milestone with screens. The same file works with /design @docs/design-brief.md inside Claude Code. The design-brief page describes all thirteen sections.

Limits and gotchas

Copy kickoff prompt copies the whole of KICKOFF.md, heading and Start line included; paste from the divider down if you prefer. Plan mode, the subagent review and the approval pauses are things the prompt asks Claude Code to do; Runic does not run Claude Code or watch what it does. The hooks only exist when the test command is known; otherwise Milestone 0 is where they get added, and the kickoff says so. The Before M1 sign-in ask is worded with a Turkish question in parentheses whatever language your flows are in; it is the same question the spec's Open questions carry. The package is a snapshot of your documents at export time. For a live connection where Claude reads and edits documents as they change, use the MCP server, whose export_build_package tool returns the same files plus the lint.

How to use it

  1. Finish the wizard
    Complete the Build Package interview and click Generate package. Read the Package quality panel, then click Download .zip.
  2. Unzip
    Unzip the archive into an empty folder. CLAUDE.md and KICKOFF.md sit at the root; the spec, plan, brief, decisions log, flows and sequences are under docs/; the rules and hooks under .claude/.
  3. Run claude in plan mode
    Open a terminal in that folder and run claude --permission-mode plan, as the first line of KICKOFF.md says.
  4. Paste the kickoff
    Back in Runic, click Copy kickoff prompt, the label flips to Copied ✓, and paste into Claude Code. Or open KICKOFF.md and copy it from there.
  5. Approve Milestone 0, answer the sign-in ask, or approve Milestone 1
    With TODO(M0) lines in CLAUDE.md, Claude Code proposes a stack and scaffolds first. If the package does not say how users sign in, it asks for the method and the identity field. Otherwise it returns the plan for Milestone 1 and waits. Approve or redirect it there; Runic is not involved after the paste.
  6. Hand off the screens
    Click Copy design brief and paste it into Claude Design, or run /design @docs/design-brief.md inside Claude Code. Its handoff bundle belongs in design/, which the kickoff reads before planning screens.

Commands & shortcuts

Copy kickoff promptCopies the contents of KICKOFF.md; shows Copied ✓ for a moment.
Copy CLAUDE.mdCopies CLAUDE.md, for a repo that already exists.
Copy design briefCopies docs/design-brief.md; the same file is in the zip.
claude --permission-mode planRun in the unzipped folder to start Claude Code in plan mode, as KICKOFF.md says.
KICKOFF.mdThe prompt: reading order, Milestone 0, the Before M1 sign-in ask, the per-milestone loop a to f, the ask-versus-decide rule, the Never list.
CLAUDE.mdOne-line goal, source of truth and ids, stack and commands, layout, conventions, verification, workflow, ask-versus-decide, gotchas, compaction.
docs/plan.mdDefinition of Done, the milestone order, and per milestone Scope, Out of scope, Verify, the acceptance checklist and a /goal line.
.claude/rules/runic-dsl.mdBoth reading legends and the id legend, loaded only for docs/flows/**, docs/sequences/** and docs/spec.md.
.claude/settings.jsonA PostToolUse test hook and a PreToolUse guard on docs/flows/ and docs/sequences/ .runic files; present only when the test command is known.
docs/decisions.mdAn empty table where Claude Code and the design chat log what was decided without asking, with the ids affected.

Tips

  • Give the test command in the interview. It is what turns the verification rule into a hook that runs after every edit, and what lets the kickoff skip Milestone 0.
  • Read docs/plan.md before you paste. The milestones are slices, not thirds; move ids between them in the file if the cut is wrong, and the kickoff still points at the same file.
  • Keep docs/flows/ and docs/sequences/ in the repo and let the hook guard them. A flow change belongs in Runic, then in a new package or over MCP, never in a Claude Code edit.
  • State the sign-in method somewhere: a login flow, a sequence with an OTP call, or one interview answer. Otherwise the kickoff stops Claude Code before M1 to ask, which is right, but slower than answering once in Runic.
  • When flows keep changing after kickoff, connect Claude Code to Runic over MCP so it reads the current text instead of the snapshot in the zip.

Questions

Is the kickoff prompt AI-generated?

No. It is fixed text from a template with your project name, one-liner, commands and milestone range filled in. Only the spec object comes from the AI; every file in the zip is rendered deterministically.

Why plan mode and a pause?

The prompt tells Claude Code to produce a plan for each milestone and wait for your approval before writing code, so the first thing it is asked for is a plan, not a diff. CLAUDE.md then keeps the acceptance criteria binding for every story after that.

Why are the legends not in CLAUDE.md any more?

CLAUDE.md is loaded on every turn; the legends are only needed when a .runic file or the spec is open. A path-scoped rules file loads them exactly then and keeps CLAUDE.md under its 150-line budget.

Why does the test hook run the whole suite?

A PostToolUse hook knows only which file was edited, not which test proves it. A single-test command with a filter that matches nothing exits green and proves nothing, so the hook runs everything, bounded by a 300-second timeout.

What if the clipboard is blocked?

The Copy chips fail silently on purpose. Every file is in the zip; open it and copy from there.

Does Runic talk to Claude Code directly?

Not through the package: it is files you paste. For a live connection, create a token under Settings → Claude & MCP or connect from claude.ai, and add Runic as an MCP server; the build-mcp page describes the package over that route.