Mainline

为你的AI智能体提供故事地图和给定/当/那么验收标准。只读。

文档

Coding agents

How it works

Your coding agent connects to Mainline and reads your user story map. It sees the activities, steps, stories, and acceptance criteria. Then it works on one story at a time.

Your pipeline reports deploys through the deploy webhook in your team settings, so an agent never marks its own work as deployed. You decide when to release.

What the LLM can do

  • Read the map structure: activities, steps, stories, release slices, personas
  • Read a story's detail: description, scenarios (given/when/then, each with its verified/done state), deploy count and dates

What only you do

  • Design the user journey
  • Write the stories and acceptance criteria
  • Release stories to users
  • Decide what to work on next

Whether you are coding with LLM assistance or not, we recommend test-driving development. Start with a BDD-style scenario that describes the behaviour, then choose the right type of test for what is being verified, e.g. unit, acceptance, or contract.

  • The 4-layer test strategy (test cases, DSL, drivers, SUT) described in Humble, J. and Farley, D. (2010) Continuous Delivery. Boston: Addison-Wesley. The DSL layer works particularly well with LLMs. It keeps test context in domain language rather than low-level implementation, so the LLM writes meaningful tests without coupling to internals.
  • Behaviour-Driven Development, described in Smart, J.F. (2014) BDD in Action. Shelter Island: Manning. Scenarios written as given/when/then map directly to what Mainline stores on each story. The LLM reads the scenarios and knows exactly what to test.

ATDD with Mainline

In Mainline you write the scenarios on each story, or approve ones a model has drafted, as given/when/then. A drafted scenario becomes one only when a person has read it and promoted the story. The LLM reads them through get_story and cannot change them. It is told not to start a story that has no scenarios. It should turn each scenario into an acceptance test, run it, and show it failing before it writes any code. You then check each test against the scenario it came from and mark the scenario done on the story.

The DSL layer makes that check quick. A test written in domain language reads like its scenario, so a test that drifts from the scenario is easy to spot.

When the LLM writes the tests and the code from the same prompt, the tests only confirm what the code already does. Both come from one understanding, so a misunderstanding passes its own tests.

This works when you have acceptance criteria on your stories and a test suite the LLM can run. Without both, the LLM is guessing and you have no way to verify its work. If you don't have these yet, start with the practices above before connecting a coding agent.

Setup (Claude Code)

  1. Go to your team settings and generate an MCP token.
  2. Run this in your project directory:
    claude mcp add --transport http mainline \
      https://mainline.dev/mcp/YOUR_TEAM_ID \
      --header "Authorization: Bearer YOUR_MCP_TOKEN"
    

Setup (other MCP clients)

For editors and tools that use a JSON config file, add this to your MCP configuration:

{
  "mcpServers": {
    "mainline": {
      "url": "https://mainline.dev/mcp/YOUR_TEAM_ID",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Available tools

list_maps

Lists all maps for your team. Start here to get the map ID.

get_map

Returns the full map hierarchy: activities, steps, and stories with their status and position. Also includes personas and release slices. This gives the LLM the big picture of your product.

get_story

Returns a single story's full detail: description, scenarios (given/when/then acceptance criteria), deploy count, and first and last deploy times. This is what the LLM reads before starting work on a story.

get_import_format

Returns the instructions and JSON Schema for writing a Mainline file: stories proposed from a specification, with the activities and steps on your maps. The LLM writes the file and you upload it. Nothing is marked or changed.

get_feature_file

Returns a story's scenarios as a Gherkin .feature file: the story is the Feature and each named scenario a Scenario, tagged with the story and scenario IDs so test results can be traced back. Given a language (kotlin, java, ruby, typescript, pytest-bdd or behave), it also returns pending step definitions, one per distinct step. People get the same files from the story's Download.feature and Step stubs links.

The workflow

  1. The LLM calls list_maps then get_map to see the work.
  2. You tell it which story to work on (or it picks the next active one).
  3. It calls get_story to read the acceptance criteria, and get_feature_file for them as a feature file.
  4. It writes the tests and code, guided by the scenarios.
  5. The code deploys, and your pipeline reports the deploy.
  6. You verify the work and release the story when ready.

Deploy and release are separate events - use feature flags, dark launching, or branch by abstraction to decouple them.

Privacy

Agents can read your maps and stories but can't change anything. Every story an agent reads is recorded in the team's activity, so the team can see what it looked at. No personal information is exposed. Story assignments show a count, not names.

Security

The MCP token gives an agent read access. The deploy webhook token is separate and belongs to your pipeline. Tokens are shown only once when generated.