Working with agents
Hand work to agents from the web app, from the in-app assistant and copyable prompts to one-tap handoffs, claims, blockers and the rules for what agents may build.
Two kinds of agent work on your project. The assistant lives in the web app and helps you shape the spec. Your coding agent, such as Claude Code or Cursor, connects over MCP and builds. The web app hands work to both, and keeps track of which agent is doing what.
The assistant
The assistant reads your project and proposes changes to it. Nothing it proposes is saved until you accept it.
- On the map, the Spec Assistant proposes stories and changes. Review proposed changes lists them: accept what you want, then Save. Every deletion needs its own approval.
- On a story, the Spec Agent can reword criteria, add or remove them, add tests, publish, reorder stories and update statuses. Each change it proposes is a draft until you publish it.
On desktop, the assistant opens as a column beside the page, or as a thread under it when the window is narrower. On a phone, tap the circle beside the tab bar. It reads "Ask about this spec…" once you scroll.
One field: search, then ask
The assistant's field does two jobs. As you type, the stories on screen filter to match, so #14 or "checkout" finds a story at once. Press return to send the question to the assistant, with the stories you filtered to as its context. For example, filter to one activity and ask "what's missing here?".
Help me and Copy prompt
When a tab spots a gap, it asks one question at the top of the page:
- On Spec's story map: Does this cover everything?
- On Plan, while stories have no place in the build order: No build order yet — how should we start?, or the offer to slot new stories in.
- On Plan, once they do, if some stories aren't ready to build: Need help defining implementation detail?
Answer it yourself, choose Help me to hand the job to the assistant, which works through it with you one question at a time, or choose Copy prompt to take the same job to your own coding agent. The build order question has no Help me, because the assistant can't write a build order.
Dismiss a question and it comes back when the answer could have changed, for example when stories are added.
The Prompt library
Every prompt the app hands out is in the Prompt library, in the ⓘ menu in the header. Each says what you get out of it. Prompts the app fills in for one story show the template, with the parts to replace in angle brackets.
| Prompt | What it does |
|---|---|
| Check my spec covers everything | Interviews you about gaps, then writes the missing stories back. |
| Make my stories ready to build | Works through unready stories: criteria, dependencies, phase. |
| Put my stories in build order | Proposes the order, release by release, and saves it once you agree. |
| Design screens from my spec | Designs against the stories for one activity. |
| Build a story from its plan | The story and its plan, and how to report back. |
| Hand a story to Claude Code | One line pointing the agent at a story. |
| Build a story in a chat builder | For Lovable, Bolt, v0 and similar: no git or terminal. |
| Map an existing codebase | Writes the brownfield report. |
| Take a story through the loop | Plan, wait for your approval, build, test, and hand it back for review. |
| Set up test reporting | Turns on CI reporting so each test's result reaches its story. |
Hand a story to your coding agent
From a story's Plan tab:
- Send to Claude Code (no plan yet) or Build in Claude Code (with a plan) opens Claude Code with a one-line instruction, such as
Use the intentdocs MCP to build story PB-42 in Courtside.The agent reads the rest over MCP, so it's never out of date or cut short. - Copy prompt copies the story and its plan as one prompt for any agent.
From Plan, a build run gives you a prompt that sets agents working through the whole run. See The Plan tab.
Before agents build
Each project decides what a person must do before an agent may build a story:
| Before agents build | An agent may build a story… |
|---|---|
| Nothing | …once it's in the build order. |
| Spec | …once a person has marked it ready for dev. |
| Spec + plan | …once an approver has approved its plan. Agents can plan any story. |
New projects start on Spec + plan. A workspace sets it in Workspace settings → Plans. A personal project can't change it from a screen yet. An approved build run counts as the go-ahead for every story in it.
When an agent tries to start a story the setting holds back, it's refused, and told what's waiting and on whom.
Who is building what
Several agents can build at once, so each story in progress records which agent session holds it. The story card on the map shows the agent and when it was last heard from. The story page says "Being built by" that agent.
- Each agent session builds one story at a time.
- Another agent can't start a story a live session holds.
- If the session goes quiet for two hours, the story reads Stalled and another agent can take it over.
- Whoever administers the project can Release claim to free it straight away.
To stop an agent mid-build, use the run on the story's Review tab.
When an agent is stuck
An agent that can't get a must criterion to pass raises a blocker. It names what it tried, what's failing, and the one decision it needs from you. The story turns red, the card says "Blocked — the agent needs a decision", and the bell tells you. Choose Resolve →, give your answer, and the agent can carry on.
What agents remember
Agents log decisions as they work: what they chose and why. They also follow examples: patterns in your code to copy. Both appear under Agent memory on the project's Overview, with the full lists a link away. Agents use log_decision, amend_decision and retract_decision; from the terminal, npx intentdocs decide and npx intentdocs example. See CLI: Decisions and memory.