# AI-ready roadmap

> Kwark's own model for a creative-app team adopting the system - six stages, seventeen steps, a "ready enough" line and an AI readiness check for each, statuses instead of scores, and the order the steps depend on.

Source: https://kwark.space/designSystem/agents/roadmap

## What this is for

A team adopting the Kwark system for a creative app (a script tool, an editor, a storyboard, a scheduler, a sound or grading tool, a production office) has to do two things at once: make the product consistent, and make it something an agent can build on without inventing. This roadmap is the order Kwark does both in.

It is written for creative tools on purpose. A general product can get away with tokens and a component library. A creative tool cannot, because the hard parts are elsewhere: the person's work on the page, a timeline with a playhead, media that is large and offline, a writer's chosen room, and a printed artefact the industry has used for decades. An agent that knows your buttons but not your script model will still break the script.

**[Download the roadmap context file (markdown)](https://kwark.space/designSystem/agents/roadmap-context.md)**. Put it in your repository as `docs/roadmap.md`, keep the statuses current, and tell your agents to read it before they start work. It lets an agent say "saving is not ready enough yet, so I will not build the export" instead of building on sand.

## How the model works

### Stages and steps

Six stages, seventeen steps. A stage is a kind of readiness; a step is one piece of work with a clear end. Stages are not phases of a project plan: you will work in several at once. What matters is the dependencies between steps, shown below.

### Ready enough

Each step has a **ready enough** line: the point where the step is good enough for the steps that depend on it, and for an agent to use. It is not "finished". A step can be ready enough and still improving.

The line exists because creative tools are never done, and teams that wait for done never start the next step. It also stops the opposite: building the export on a document model that still changes every week.

### AI readiness check

Each step has a check: a task you give an agent in a fresh conversation, with only your published context, that it can do correctly only if the step is ready enough. If the agent fails, the step is not ready, whatever the team thinks. The checks use the same method as the [readiness tests](https://kwark.space/designSystem/agents/readiness.md) on every page.

### Statuses, not scores

| Status | Meaning |
|---|---|
| **Not started** | Nobody owns it yet. |
| **Working** | Someone owns it and it is below the ready-enough line. |
| **Ready enough** | It meets the line and its AI readiness check passes. Steps that need it can start. |
| **Revisit** | It was ready enough, and something it depends on changed. Run its check again. |

There is no maturity level and no percentage. A score hides which step is the problem, invites a team to raise the number rather than fix the work, and says nothing an agent can act on. A status per step does. (Kwark does not score people's scripts either; it would be odd to score a team.)

## The dependency order

| Step | Needs before it can be ready enough |
|---|---|
| 1 People and artefacts | nothing |
| 2 Principles you adopt | 1 |
| 3 Screens and parts inventory | 1 |
| 4 Tokens | 3 |
| 5 Themes, rooms and accent | 4 |
| 6 Type and scripts | 4 |
| 7 The work model | 1 |
| 8 Saving, sync and offline | 7 |
| 9 Undo, trash and revisions | 7, 8 |
| 10 Shared parts and shells | 3, 4 |
| 11 Creative-tool parts | 7, 10 |
| 12 The printed artefact | 6, 7 |
| 13 Your AGENTS.md and context | 2, 4, 10 |
| 14 Authorship rules for machines | 2, 7, 9 |
| 15 Readiness tests and review | 13 |
| 16 Enforcement in the build | 4, 10 |
| 17 Versioning and release | 13, 16 |

Two chains matter most. **The work chain** (1, 7, 8, 9, then 11, 12, 14) decides whether people can trust the product with their work. **The system chain** (3, 4, 10, then 13, 16) decides whether the product stays consistent. They can run side by side, and they meet at step 13, where an agent is given both.

> The most common mistake is to start at step 10, a component library, because it is the visible part. A library built before the inventory (3) and the tokens (4) encodes today's inconsistencies. A library built before the work model (7) gets a timeline component that cannot hold the real data.

## Stage 1 · Ground: know the work

### Step 1 · Name the people and their artefacts

Write who makes what in your product, in what situation, and the artefact the industry already uses for it: the screenplay page, the stripboard, the call sheet, the edit decision list, the cue sheet, the shot list, the colour report. The digital version will be that artefact, not a table beside it.

- **Ready enough:** every main screen maps to a named person and a named artefact, and the team agrees on the words.
- **AI readiness check:** give an agent only this document and ask it to name the screen a 2nd AD uses at 6am on a shoot day, and what that screen must print. It answers with your artefact and your words, not generic "dashboard" language.

### Step 2 · Record the principles you adopt

Kwark's principles (the writer first, private and safe, no judgement of the work, nothing compulsory, structure not teaching, paper and digital as one act) are opinions. Decide which you keep, which you change, and write each as a decision record with its reason. See [Principles](https://kwark.space/designSystem/foundations/principles.md) and [Decision records](https://kwark.space/designSystem/method/decision-records.md).

- **Ready enough:** each principle you keep has a record with a test ("Does this measure the work, or evaluate it?"), and the ones you drop are written down too.
- **AI readiness check:** ask an agent, with only your records, to design a "progress" feature for writers. It refuses or reshapes anything your principles rule out (streaks, scores, public counts) and cites the record.

### Step 3 · Inventory the screens and parts

List every screen, and every part on it: each button style, each dialog, each badge, dot and count, and what it means. Kwark keeps two lists: a map of components and the screens that use them, and an element register that gives every dot and badge a meaning and a reason. Anything with no reason is a candidate for removal.

- **Ready enough:** you can say for every visible element which component it should be, and every dot, badge and count has a written meaning.
- **AI readiness check:** give an agent a screenshot of one screen and the inventory. It names each part's component and flags the elements not in the register.

## Stage 2 · Foundations: tokens, rooms and type

### Step 4 · Adopt the tokens

Replace values with roles: `--k-*` tokens from `kwark.css`, or your own names mapped onto them through `tokens.json`. Map every colour, size, radius, space and duration you found in step 3 to a role. Two values doing the same job become one. See [Developing](https://kwark.space/designSystem/developing.md).

- **Ready enough:** new code uses only tokens, and the old values are mapped (even if not yet replaced everywhere).
- **AI readiness check:** ask an agent to restyle one panel with only `tokens.json` and `AGENTS.md`. It uses no hex, rgb or px font sizes, and names each role it used.

### Step 5 · Themes, rooms and the project accent

Dark and light, the rooms people choose for their working surface, and a project's own colour. In a creative tool the working surface is the person's space: a writer in Midnight at 2am, a colourist in a neutral room for accurate judgement. Decide which surfaces follow a room and which never do (a grading viewer must stay neutral). See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md).

- **Ready enough:** every token has a light and a dark value, each room passes contrast for text and controls, and a pale and a dark project accent both read.
- **AI readiness check:** ask an agent to add a "Scene notes" panel inside the working surface. It uses roles that follow the room, sets `--k-on-accent` with any accent, and checks contrast in every room without being told to.

### Step 6 · Type and scripts

The UI type scale, and the type of the work itself: screenplay geometry (Courier Prime at 12pt, the industry's page), timecode, music notation, whatever your artefact uses. Then every script your people write in. Kwark writers type in Hindi, Tamil and other Indian scripts, and the PDF route for those scripts is different from the Latin one (see [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md)).

- **Ready enough:** the work's type matches the industry's page measurements, and a line in each supported script displays, edits, wraps and prints correctly.
- **AI readiness check:** ask an agent to add a bilingual dialogue line (English and Hindi) to a script view. It keeps the work's font role, does not shrink the Indian script below the scale, and says how the line will print.

## Stage 3 · The work is safe: data, saving and offline

### Step 7 · The work model

Write down the shape of the person's work so a person and an agent read it the same way: a script as scenes and elements (heading, action, character, dialogue, parenthetical, transition); a timeline as tracks, clips, in and out points in timecode; a board as panels tied to shots; a schedule as strips tied to scenes, cast and locations. Say which fields are the person's words and which are derived. Say how big it can get (a feature film, a 200-strip schedule, an hour of media).

- **Ready enough:** a written model with field names, types, limits and which fields a machine may never write; existing data loads into it, including old records with missing fields.
- **AI readiness check:** give an agent the model and ask it to add a "runtime per scene" display. It reads only derived fields, writes nothing into the person's text, and handles a scene with no dialogue.

### Step 8 · Saving, sync and offline

The person's biggest fear is losing work. Autosave, one calm word for the state, work kept on the device when the network goes, and a clear choice when two sessions disagree. Media is large: say what is on this device and what is not. See [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md) and Decision 0013.

- **Ready enough:** every state has a fixed word, no message says "failed", offline edits survive a reload, and a conflict never overwrites either copy without the person choosing.
- **AI readiness check:** ask an agent to add an import for a storyboard image set. Its design says what the person sees when the files reach the device but not the cloud, in your words, and what happens if the import stops halfway.

### Step 9 · Undo, trash and revisions

Undo instead of "Are you sure?". A trash that can be restored. Versions people can name and return to. Where the industry numbers revisions (a revised call sheet, coloured script pages), the product numbers them the same way. See [Destructive actions](https://kwark.space/designSystem/patterns/destructive-actions.md).

- **Ready enough:** every destructive action can be undone or restored, and issued artefacts keep numbered revisions that do not change once issued.
- **AI readiness check:** ask an agent to add "Delete Act 2". It offers Undo, names the object and its contents in any confirmation, and keeps the scenes recoverable.

## Stage 4 · Parts and shells

### Step 10 · Shared parts and the two shells

The shared components, used everywhere, and the two shells: desktop with File, Edit, View, Tools and Help menus and real shortcuts; phone with one header line, content first and one floating control. See [Components](https://kwark.space/designSystem/components.md), [Phones](https://kwark.space/designSystem/patterns/phones.md) and [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md).

- **Ready enough:** every new screen is built from shared parts, every control has a word or a named icon, and the phone layout of each main screen starts its content by about y = 200.
- **AI readiness check:** ask an agent to build a settings screen for desktop and phone. It uses only listed components, puts menus in a bottom sheet on the phone, and labels every control.

### Step 11 · Creative-tool parts

The parts only creative tools need: the page view, the timeline and playhead, scrubbing, index cards, boards, the stripboard, waveforms, the revision mark for machine suggestions. Each is built on the work model (step 7), not on a mock-up. See the [Creative app kits](https://kwark.space/designSystem/kits.md).

- **Ready enough:** each part handles the real data at its real size (a feature-length timeline, a long scene, an empty board) with keyboard control and a phone form.
- **AI readiness check:** ask an agent to add markers to the timeline. It uses the timeline component and the model's timecode fields, gives each marker a name for screen readers, and keeps the phone strip readable.

## Stage 5 · Paper and print

### Step 12 · The printed artefact

Print or export the artefact at the industry's geometry from the start: the screenplay page, the call sheet a crew reads on paper, the shot list on a clipboard. Paper and digital are made as one act; the printout is not an afterthought. See [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md).

- **Ready enough:** the printout matches the industry page (margins, page breaks, numbering), every supported script prints correctly, and a printed revision shows its number.
- **AI readiness check:** ask an agent to add a field to the call sheet. It adds it to the printed sheet in the same change and says where it falls on the page.

## Stage 6 · Agents in the loop

### Step 13 · Your AGENTS.md and context

Write your product's own `AGENTS.md`: Kwark's rules plus yours (your work model, your principles, your artefacts). Publish markdown twins for your docs, and install the [MCP server](https://kwark.space/designSystem/agents/mcp.md) and [skills](https://kwark.space/designSystem/agents/skills.md). See [AI context files](https://kwark.space/designSystem/agents/ai-context.md).

- **Ready enough:** a new agent, given only your published context, builds a small screen that passes review without a correction.
- **AI readiness check:** the check is the ready-enough line: one fresh conversation, one small screen, graded against your rules.

### Step 14 · Authorship rules for machines

If any part of the product proposes words, frames, cuts or schedules, decide how it is marked, accepted and refused. In Kwark a machine suggests and a person writes: suggestions carry a revision mark until accepted, are never saved into the work on their own, and never score or judge it. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md) and Decision 0002.

- **Ready enough:** every machine proposal is visibly marked, needs a person's action to enter the work, can be refused, and nothing anywhere rates the person's work.
- **AI readiness check:** ask an agent to add "suggest a scene heading". It shows the suggestion with a revision mark, writes nothing until accepted, and offers no quality judgement.

### Step 15 · Readiness tests and review

Add a readiness test to every page you publish, and run the review ladder on every change: a UI reviewer and a UX reviewer who did not build it, review-only, before anything is called done. See [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) and [Contributing](https://kwark.space/designSystem/contributing.md).

- **Ready enough:** every page has a test, the tests are run in each agent tool the team uses, and a failed test leads to a page change.
- **AI readiness check:** run three tests from different pages in a fresh conversation. All reliable items are met, or the failing page has been rewritten.

### Step 16 · Enforcement in the build

Tests that stop drift: a scan that counts colour literals, px font sizes, font names and icon sizes per file and fails when a file gets worse. Kwark's version is described on [Developing](https://kwark.space/designSystem/developing.md).

- **Ready enough:** the suite fails on any new violation, and the baseline only goes down.
- **AI readiness check:** ask an agent to make a change that would be easier with a hex value. It uses a token, and if it does not, the test fails before review.

### Step 17 · Versioning and release

One version number for the system and its files, release notes that name every changed token and component, and agents told which version they are reading. See [Releases](https://kwark.space/designSystem/releases.md).

- **Ready enough:** each release has notes, token names do not change inside a major version, and your context files carry the version.
- **AI readiness check:** ask an agent what changed between your last two versions and what it must update. It answers from the release notes only.

## Kwark against its own roadmap

Kwark is on this roadmap too. Where it stands at v4.0, plainly:

| Step | Status | Why |
|---|---|---|
| 1 People and artefacts | Ready enough | Writers and crew roles, and the artefacts (script, breakdown, stripboard, call sheet, budget) are named in the decision records. |
| 3 Screens and parts inventory | Ready enough | A component map and an element register exist, written from the code. |
| 4 Tokens | Working | Tokens are in one file; older names still work alongside them while code moves over. |
| 5 Themes, rooms and accent | Working | Five writing rooms and the project accent ship; the light theme is unfinished, so the app opens in dark. |
| 6 Type and scripts | Working | Indian scripts can be typed and print through the browser; the built-in PDF export is Latin only. |
| 8 Saving, sync and offline | Ready enough | Fixed save words and calm sync copy (Decision 0013). |
| 12 The printed artefact | Working | Screenplay and call sheet print; some page sizes are still being measured against industry PDFs. |
| 13 AGENTS.md and context | Ready enough | This site, its twins, the MCP server and the skills. |
| 16 Enforcement in the build | Working | Checks in the build fail any change that adds a raw colour, font, size or a stray breadcrumb. |

Steps not listed have not been assessed for this page.

## AI readiness test

**Task:** A team building a sound-mixing app asks where to start adopting the Kwark system and what an agent can safely build first.

**Give the agent:** This page and the roadmap context file.

**Constraint:** Use the steps and statuses here. No maturity levels or scores.

**A reliable answer:**
- Starts with step 1 and the work model (7), not a component library
- Names the sound industry's artefact (a cue sheet or mix notes) in step 1
- Gives the ready-enough line and the AI readiness check for the first steps
- Says an agent should not build export or machine suggestions until the steps they depend on are ready enough
- Uses the four statuses only
