Mainline

From a specification to a story map

See also: Ticket Museum, Coding agents

You have a specification, a plan or a pile of research. A model will turn it into stories in a minute. Mainline lets it propose them, and leaves the deciding to you.

What it does

A model reads your document and writes a Mainline file: a list of proposed stories. Each one says where in the document it came from, why it matters, where it might sit on the map, and how it might be checked. You upload the file to the Ticket Museum, where each proposal waits as an exhibit marked as proposed.

Nothing becomes a story, and no draft becomes a scenario, until a person reads it and promotes it.

Mainline never calls a model. You use the one you already have.

The loop

  1. Copy the instructions from the museum.
  2. Give them to a model with your document.
  3. Upload the file it writes.
  4. Review each proposal: promote it, send it to storage or leave it on display.
  5. Send corrections back and upload the revised file.

1. Copy the instructions

In the Ticket Museum, choose Acquire, then A Mainline file, and press Copy instructions. They explain how to break work into stories, show an example and include the schema the file must pass.

The acquire page with A Mainline file chosen, showing the Copy instructions button and the place to drop a file

If your team already has maps, the instructions list their activities and steps, so the model can suggest places that exist.

A coding agent connected over MCP can ask for the same text with get_import_format. See Coding agents.

2. Give them to a model

Paste the instructions and attach your document. The instructions hold nothing about your project, and a model given no document is told to ask for one. Any model that can write JSON will do: a chat window, a coding agent or one running on your own machine. Ask for a file, not a reply.

Save the file as the JSON alone. A chat window prints it inside a code fence, and a file saved with the fence round it is turned away.

Two things help. Give it a document that says what people can do with the product, not how it is built. And tell it which part comes first. A file holds at most 200 entries.

3. Upload the file

Drop the .json file on the acquire page, or anywhere on it. Mainline checks it first. A file that passes is staged: nothing has entered the museum yet, and a staged file left alone is turned down after 24 hours. The preview shows:

The preview of a staged file: one new exhibit, the proposed map with its activity and steps ticked, and the Acquire button

Choose a new map or one your team already has. Untick any activity or step you do not want. Only what is ticked is created, and the exhibits arrive either way. Then press Acquire.

4. Review what it proposed

This is the part that matters. Open an exhibit and read where it was proposed from and why. Check them against your document. Then choose:

An open exhibit showing where it was proposed from and why, beside the form to rewrite it as a story with its draft scenario

Signs a proposal is not a story yet:

Promote in the order you would build, thinnest working version first. You do not have to promote everything. What stays in the museum costs nothing.

5. Revise

Tell the model what was wrong and ask for a revised file. The instructions tell it to keep every entry's key, so acquiring the new file refreshes the exhibits and adds none twice. An exhibit you have already promoted or sent to storage is left as it is.

When a file is turned away

A file with anything wrong is turned away whole, and nothing enters the museum. Mainline lists every problem as a sentence that names the entry and the field, such as:

Entry SHOP-GUEST-01, scenario 2 has no then

Press Copy problems, give the list to the model and ask it to correct the file.

A file is also turned away when it uses a key twice, uses a key that an exhibit from somewhere else already has, or was saved with a code fence round it.

Changing your mind

The latest acquisition can be returned. The exhibits it added leave the museum, and any it refreshed go back as they were. Anything you have promoted or stored since stays, and so does any map it laid out. Acquiring another file makes the earlier ones final.

The file

FieldRequiredLimitWhat it is for
mainlineyesmust be 1The version of the format
mapwith personas or activities100 charactersThe story map these stories are for
personasno20, each 100 charactersThe kinds of people the product is for
activitiesno30The proposed backbone, left to right
activities: nameyes100 charactersWhat people do
activities: personasyesat least 1, each listed under personasWho does this activity
activities: stepsno30, each 100 charactersThe steps within it
entriesyes1 to 200The proposed stories
entries: keyyes50 characters, like SHOP-GUEST-01Yours to choose. Keep it when you revise
entries: titleyes200 charactersThe story, as what someone can do or see
entries: sourceyes255 charactersWhere in the document it came from
entries: whyno2,000 charactersWhy it is worth building
entries: suggestednoactivity and step, 100 characters eachA place on the map
entries: draft_scenariosno10. Aim for one to threeHow it might be checked
draft_scenarios: nameyes80 charactersWhat the scenario shows
draft_scenarios: given, when, thenyes100 characters eachOne short line each

A file is at most 10 MB and may hold no other fields.

An example Mainline accepts:

{
  "mainline": 1,
  "map": "Online shop",
  "personas": [
    "Shopper"
  ],
  "activities": [
    {
      "name": "Check out",
      "personas": [
        "Shopper"
      ],
      "steps": [
        "Enter details",
        "Pay"
      ]
    }
  ],
  "entries": [
    {
      "key": "SHOP-GUEST-01",
      "title": "Guests can check out without an account",
      "source": "Checkout specification, section 4.2",
      "why": "A third of baskets are abandoned at the sign-up page.",
      "suggested": {
        "activity": "Check out",
        "step": "Enter details"
      },
      "draft_scenarios": [
        {
          "name": "Guest pays with only an email address",
          "given": "I have items in my basket and no account",
          "when": "I choose to continue as a guest",
          "then": "I can place the order with only my email address"
        }
      ]
    }
  ]
}

The file is checked against the published schema.

What it will not do