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.
Setup (Claude Code)
- Make a personal token under Profile, then Coding agents, ticking the teams it may read.
-
Run this in your project directory:
claude mcp add --transport http mainline \ https://mainline.dev/mcp \ --header "Authorization: Bearer YOUR_PERSONAL_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",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer YOUR_PERSONAL_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
.featurefile: 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 alanguage(kotlin,java,ruby,typescript,pytest-bddorbehave), 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
- The LLM calls
list_mapsthenget_mapto see the work. - You tell it which story to work on (or it picks the next active one).
- It calls
get_storyto read the acceptance criteria, andget_feature_filefor them as a feature file. - It writes the tests and code, guided by the scenarios.
- The code deploys, and your pipeline reports the deploy.
- 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
A personal token gives an agent read access to the teams you ticked, as you, until it expires or you revoke it. The deploy webhook token is separate and belongs to your pipeline. Tokens are shown only once when made.