Runic
PACKAGE

Everything Claude Code and Claude Design need, in one zip

Press Build, tick the documents, answer up to eight questions, and download a repo-ready folder: CLAUDE.md under 150 lines, a plan-mode KICKOFF.md, docs/spec.md with a roles by permissions matrix, a typed data model, contracts derived from your sequence diagrams and acceptance criteria that cite branch ids, vertical-slice milestones, a 13-section design brief, path-scoped DSL rules, hooks when the test command is known, and every ticked flow as a .runic file, checked against ten quality tells before you download.

Try it free →Read the docs

What is in the zip

The files come in a fixed order. At the root: CLAUDE.md, the project memory Claude Code reads on every turn, kept under 150 lines, and KICKOFF.md, the prompt you paste into a plan-mode session, under 40 lines. Under docs/: spec.md (the contract), plan.md (the milestone order and the Definition of Done), design-brief.md (what Claude Design reads on its own) and decisions.md, a heading, one sentence and an empty table with the columns Date, Milestone, IDs affected, Decision, Why and Alternatives rejected, where Claude Code logs what it decided without asking. Under .claude/rules/: runic-dsl.md, both reading legends plus the id legend under a YAML frontmatter paths: ["docs/flows/**", "docs/sequences/**", "docs/spec.md"], so the legends load only when Claude Code opens a flow, a sequence or the spec instead of costing context on every turn.

.claude/settings.json ships only when the spec's test command is known, from the interview or the brief. It holds two hooks on Edit, Write and MultiEdit: a PreToolUse guard that reads the tool input and exits 2 with the message “docs/flows and docs/sequences are read-only — propose the change in chat” when the file path is a .runic file under docs/flows/ or docs/sequences/, and a PostToolUse hook that runs the whole test suite after every edit, <test> >&2 || exit 2, with a 300-second timeout, so a red test reaches Claude instead of the transcript. It runs the suite, never the single-test command, because a hook only knows which file changed. Without a test command the file is left out and Milestone 0 of the kickoff adds it.

Then one docs/flows/<slug>.runic per ticked process, entry flow first, and one docs/sequences/<slug>.runic per ticked sequence diagram, each holding the text from your editor with exactly one trailing newline. Slugs use the same transliteration as the ids: lowercased, hyphenated, ı ş ğ ü ö ç mapped to i s g u o c, so Ödeme API Akışı becomes odeme-api-akisi.runic and the path the spec cites is one a search for odeme finds. Two names that collapse to the same slug get -2 and -3 within their directory, and a name with no letters or digits becomes untitled. Runic writes the zip itself, store-only with a fixed timestamp, so the same files give the same archive byte for byte, and dotted paths such as .claude/ are stored verbatim. The download is named after the project, refund-desk-build-package.zip, or runic-build-package.zip when the name has no ASCII letters or digits.

Who can build, and from what

Build is a pill in the top bar between AI chat and Map, shown only when you are signed in; the /learn tour does not have it, and both AI routes refuse an unverified email with “Verify your email to use AI features.” The window that opens is titled Build Package. Its intro reads: “Turns the flows you tick below into a developer-ready package: a full build specification, a Claude Code project folder (CLAUDE.md, kickoff prompt, milestone plan) and a Claude Design brief. Runic asks a few questions first — the flows say what happens, you know the rest.” The Project name field, 80 characters at most, is prefilled with the plan's name when you arrive from Whole system, else the first process in your sidebar, else My product. It becomes the heading of every file and the name of the zip.

Under Processes in the package you tick the processes the spec is written from, each shown with its non-blank line count; Sequence diagrams get their own list when you have any. Everything is ticked by default. When you arrive from a system Runic just drafted, only that system's documents are ticked, the samples stay out, and the entry flow is moved first so it becomes F1 and Milestone 1, provided it is ticked. The line underneath reads “P of N processes · S of M diagrams selected.” Start refuses with “Tick at least one process — the spec is built from what you select.” when no process is ticked. A package holds at most 40 processes and 20 sequence diagrams; past that both routes answer “A build package holds at most 40 processes and 20 sequences (P processes and S sequences picked) — untick some documents.” rather than sending a cut list. Within the caps, every document is cut at a line boundary at 20,000 characters, whatever the size of the set; when the set still outgrows 120,000 characters the longest are cut further, and every cut is announced as “[… N more lines not shown — ask about them rather than assuming]”.

The seed from Whole system, meaning the brief, the plan with its actors, assumptions and entities, and the entry flow's name, lives in the current session only and applies only while the document open in the editor belongs to that system. Reload the page, or press Build with an unrelated document open, and the window opens unseeded: every document ticked, the name from the first process, no brief in the spec.

Two AI calls, everything else code

Start sends the ticked documents, the brief and the plan to the questions route. It casts the model as a senior business analyst and asks for five to eight questions, one per line, in the flows' language; Runic strips numbering and keeps at most eight. This runs on the mid tier of your provider (claude-sonnet-5 on Anthropic) with extended thinking, 1,500 output tokens, 120 seconds at most. The window shows “Reading your flows…” and “Finding what a developer would still ask.” An empty reply is a 502, “The AI returned nothing usable — try again.”, and you land back on the intro with your ticks intact. The interview page describes what it asks and why.

Generate package sends the documents again, entry flow first, with your answers (at most 12 question and answer pairs, questions cut at 500 characters and answers at 2,000, a blank one sent as “(not answered)”), the brief, the plan, and the ID INDEX: every id Runic will assign, computed on the uncut documents in package order with the line it names beside it, under the heading “ID INDEX (copy these ids exactly)”. The model must return one JSON object in the typed spec shape: overview, success_metric, personas, roles, auth, permissions, user_stories with structured acceptance criteria, data_model, screens, integrations, non_functional, milestones, stack with commands, design and open_questions. This is the heavy tier, which defaults to claude-sonnet-5 as well; Opus runs here only when the operator sets ANTHROPIC_MODEL_HEAVY. Thinking is on, the output budget is 16,000 tokens and is raised once to 24,000 if the reply is cut; a reply cut a second time, or one cut when under 60 seconds of the route's time remain for the doubled retry, answers “The reply was too long to finish in one go — select the part to change, or split the document into linked processes.” instead. Invalid JSON gets one retry with “Your previous output was not valid JSON…”. The object is coerced into the exact shape, unknown keys dropped and legacy string criteria accepted; nothing usable after that gives “The AI could not produce a valid spec — try again.” and you land back on the answers with them intact. Both stages share one limit of 12 calls per hour per account; past it: “Build limit reached — try again in an hour.”

From that object on, no model is involved. Runic parses the ticked documents and assigns the ids, renders CLAUDE.md, KICKOFF.md, the spec, the plan, the brief and the small files from templates, derives the contracts from the sequence diagrams, and lints the rendered files. The files, the lint and the contract count are recomputed only when the spec, the name, the ticks or the answers change.

What the spec contains

docs/spec.md opens with the title, a line “Generated by Runic on <date>” and the id legend, then Overview: the product one-liner (the plan's summary, else the spec's goal, else the project name, the same string in CLAUDE.md, KICKOFF.md and the brief), problem, goal, scope, success metric and out of scope as bullets. When you arrived from Whole system the brief follows verbatim in a fenced block under “The brief (verbatim — the founder's own words…)”, then the plan's assumptions under a heading that calls them unconfirmed. Personas is a table of name, goals and permissions, followed by Actors (from the plan) when a plan exists. Roles × permissions is a matrix with one row per role (its R- id and name) and one column per subject, where a subject is an entity operation such as E-Order: create or a gating decision id such as F2.D1; an empty cell is deny, the others read allow, deny, own-only or approval-required with a note in parentheses. A Sign-in line with the method and the identity field follows when the spec knows them.

Flows gives each ticked process a heading with its F id, the path of its .runic file, a table of ID, Kind and Text for every decision, branch, failure, loop, wait and input, and the source in a fenced block. Data model gives each entity a heading with its E- id, a table of Field, Type, Required, Default, Constraint and Note, its relations, a Derived from list naming for every field the .input, .wait, message or screen that carries it (a field with no source is what the field-closure tell flags), and, for an entity whose lifecycle a flow draws, a State line with the closed value list and a From, To, By table naming the branch id that performs each transition.

Contracts is derived, never written by the model: per sequence diagram, a heading with its S id, the file path and the systems with their kinds, then one row per message with ID, Caller → callee (an external callee is marked “stub in tests”), Kind (sync, async or reply), Message, Payload fields (each snake_case token in the message resolved to E-Entity.field, unknown ones flagged), Only when (the innermost .alt, .else, .opt or .break section it lives in), Failures (the .else sections of the next .alt and every .break below at the same level), Retry (the innermost .loop label), Timeout (read from the nearest .note), and Test (the row id). An Alternatives & failures table lists every section with its kind, condition and the messages inside; rows under a .par get a note that they may interleave; the diagram's source closes the block. User stories keep the as-a, I-want, so-that form with one line per criterion: US-n.ACk | Given … | When … | Then … | covers F1.D2.evet, S1.M3.

Screens lists the spec's screens first, then one derived screen for every ticked process the spec gave none, with its state copy read off the flow: empty before the first .input is entered, loading while the .wait lines or the called sequence are pending, error from the .fail lines with their recovery, success when the terminal step is reached. Each block carries Purpose, Hosts (the F id), Key elements, Data displayed, Actions (label → id) and the four states plus domain states. Integrations follows, then Non-functional requirements as a table of ID, SLI, Target, How measured and Milestone, with a WCAG 2.2 AA row appended when no row mentions WCAG. Milestones is a summary table pointing at docs/plan.md. Open questions holds the spec's own, plus one for every contract payload token that is no field of any entity, one for every token two entities share, and an NF gap question for availability, latency, retention, session, sign-in and volume whenever nothing covers the topic; for sign-in, a login drawn in a flow or a sequence counts as covered. Appendix: Interview quotes every question and answer as a blockquote, so a “##” inside your answer is never read as a heading. An empty list prints None yet.; headings are fixed English, values are in the language of your flows.

The plan, the memory file and the kickoff

docs/plan.md opens with a Definition of Done every milestone shares (id-named tests green and none skipped, lint and typecheck clean, a commit that cites the ids, the Verify sentence walked with its output pasted, decisions logged), an Order list, then one block per milestone with Scope and Out of scope as ids, one Verify sentence, an Acceptance checklist of branch, criterion and NF ids, and a /goal line naming the tests an unattended run must pass. When the spec has no milestones, Runic derives them: M1 is the entry flow's happy path with its screens, the success sections of the sequences it calls and its entities; M2 that flow's failures, loops and alternatives; one milestone per further flow; one for sequences no flow calls; and Non-functional hardening last. CLAUDE.md, KICKOFF.md, the hooks and the rules file are described on the handoff page; the id scheme every file shares has a page of its own.

The design brief and the quality panel

docs/design-brief.md has thirteen numbered sections and is written to be pasted into Claude Design on its own: the product and the verbatim brief, audience, tone, platform, one journey per flow walking its happy path with ids, a screen inventory with four states each, components reused on two or more screens, copy rules, WCAG 2.2 AA numbers, what to design first, out of scope, every ticked flow embedded with the legend plus an integration touchpoints table per sequence, and the handoff. The design-brief page walks through it section by section. The Package quality panel on the done screen runs ten mechanical tells on the rendered files, shows how many pass and a score out of 100, and never blocks the download; the build-lint page lists all ten with what each checks.

Limits and gotchas

Build needs a signed-in account with a verified email; there is no plan gate. The two AI stages share 12 calls per hour per account, so a package that goes through first time uses two. On Runic's key both stages also count against the account's $5-per-month AI budget, and once it is used up either stage answers 402 “This month’s AI budget on Runic’s key is used up — add your own key under Settings → AI or wait for the 1st.” however much of the hour's 12 calls is left (the refused call still takes one of them, as the hourly check runs first); a key of your own under Settings → AI is not budgeted. More than 40 processes or 20 sequence diagrams is refused, not cut. Esc, the ✕ and a click outside close the window between stages, not while Runic is reading flows or writing the spec, so an in-flight request is never orphaned. The quality checks read the rendered files, so a tell that fails because a flow has no .fail path is fixed in the editor, not in the interview. The seed from Whole system is gone after a reload. A generated spec is not stored: close the window and the object is lost, so download the zip or copy what you need before you close it.

How to use it

  1. Open Build
    Click Build in the top bar, between AI chat and Map. The Build Package window opens with the project name prefilled from the plan when you arrive from Whole system, else from the first process in your sidebar.
  2. Name the project
    Edit the Project name field if you like, up to 80 characters. It becomes the heading of every file and the name of the zip.
  3. Tick the documents
    Under Processes in the package, tick the processes the spec should be written from. Sequence diagrams get their own list when you have any; their messages become the contracts table. The line underneath counts what is selected. At most 40 processes and 20 diagrams go into one package.
  4. Start
    Click Start. Reading your flows… shows while the questions are written; Esc and ✕ are inert until they arrive.
  5. Answer and generate
    Type what you know in the answer boxes, then click Generate package. Writing the specification… shows while the spec is produced.
  6. Read the quality panel
    The done screen says Package ready with the counts of files, stories, roles, contracts and milestones, then Package quality with the ten tells and the score. A cross names what is missing; fix it in the flows or the answers and run Build again if you want it green.
  7. Download or copy
    Click Download .zip, or use the Copy by hand chips: Copy kickoff prompt, Copy CLAUDE.md and Copy spec for Claude Code, Copy design brief for Claude Design. Each flips to Copied ✓ for a moment.
  8. Unzip and hand off
    Unzip into an empty folder, run claude --permission-mode plan there, and paste the kickoff prompt. For Claude Design, paste the brief; it stands alone, the designer never sees the repo.

Commands & shortcuts

BuildTop-bar pill between AI chat and Map that opens the Build Package window; signed-in accounts only.
StartReads the ticked documents, the brief and the plan and returns up to eight questions.
Generate packageSends documents, answers and the ID INDEX to the spec stage, assigns the ids, renders every file and runs the ten checks.
Download .zipSaves <project-name>-build-package.zip with every emitted file, .claude/ included.
Copy kickoff promptCopies KICKOFF.md to the clipboard, for Claude Code.
Copy CLAUDE.mdCopies CLAUDE.md to the clipboard.
Copy specCopies docs/spec.md to the clipboard.
Copy design briefCopies docs/design-brief.md to the clipboard, for Claude Design.
Esc / ✕Closes the window, except while Runic is reading flows or writing the spec.

Tips

  • Put the process everything else depends on first in the sidebar, or arrive from Whole system: the entry flow becomes F1 and Milestone 1, and its happy path is what Claude Code builds first.
  • Give every decision a .fail path before you build. Branch coverage counts .fail lines, and a flow that never fails produces a spec with no error states to design.
  • Draw the integration as a sequence diagram with .alt and .else sections. Each message becomes a contract row and each .else its failure condition; a process step saying call the payment API becomes nothing.
  • Answer the stack question with the exact commands. They land in CLAUDE.md and in the test hook; an unknown one prints TODO(M0) and costs Claude Code a milestone to find out.
  • Keep the window open until you have the zip. The spec object lives in the window; closing it means running both stages again, which costs two of the twelve hourly calls.
  • Commit the unzipped files. Markdown and .runic are plain text, so a later package diffs cleanly against them in git.

Questions

Does the AI write the files?

No. The AI returns one JSON object with the spec content. Runic assigns the ids from the parsed documents, renders every markdown file from fixed templates, derives the contracts from the sequence diagrams and embeds your flows verbatim.

Are sequence diagrams part of the spec?

Yes. They are sent to the AI with the processes, they ship under docs/sequences/ as .runic files, every message becomes a row of the Contracts table with its failures, retry and timeout, and the design brief lists what each message needs on screen.

What does the score mean?

Ten mechanical checks on the rendered files, ten points each, listed one by one with what fails. A failed check does not block the download; it tells you what the package is still missing.

Which language is the spec in?

The section headings are fixed English. The prompt tells the model to write the values in the language your flows are written in and to keep the JSON keys, ids and state keys exactly as given.

Which model writes the spec?

The questions run on the mid tier, claude-sonnet-5 on Anthropic. The spec runs on the heavy tier, which also defaults to claude-sonnet-5; Opus is used only when the operator sets ANTHROPIC_MODEL_HEAVY. With your own key, the model you chose for that tier applies.

Why does my CLAUDE.md say TODO(M0)?

The stack or one of the install, dev, test, lint and typecheck commands was not given in the brief or the interview. The package never guesses a command; the kickoff's Milestone 0 has Claude Code propose them, scaffold and replace the TODOs.

Is Build a paid feature?

No plan gate exists for it in the code. It needs a signed-in account with a verified email address. What does gate it on Runic's key is the account's $5-per-month AI budget: once that is used up both Build stages answer 402 “This month’s AI budget on Runic’s key is used up — add your own key under Settings → AI or wait for the 1st.” A key of your own under Settings → AI is not budgeted.