The day-to-day loop

How one story goes from spec to approved in IntentDocs: what you do, what your agent does, and what the story card tells you at each step.

You and your agent take one story at a time through five steps, in the order the story page's tabs show them. At every step the card at the top of the story says where it is and what's next — so the loop is mostly a matter of reading that card and pressing its button.

1. 1 · on the Spec tab

   Spec

   You

   Write what the story is for and how you'll know it's done: a user story and acceptance criteria. Criteria are numbered cards (01, 02…); + Add puts another on the list, and a dashed card is one nobody has checked for solution detail yet.

   Your agent

   Can draft stories and criteria for you, and reads the story in full before it does anything else. create_stories, add_criteria, get_story

   The story card says

   • "To do", with Mark ready for dev — or, when the project asks for a plan first, "Waiting for the agent's plan".
   • Missing something? The card says so under the button — "It needs acceptance criteria before it can be ready. Add criteria →" — instead of greying it out.

2. 2 · on the Plan tab

   Plan

   You

   Read the plan: a summary (steps, files it touches, open questions, the risk the agent sees), then the steps as cards. Keep, drop, comment on or edit any step, and answer the agent's questions. Then Request changes — everything you wrote goes to the agent together — or Approve → Ready.

   Your agent

   Writes the plan as numbered steps, with the files each touches and anything it needs you to decide. If you request changes it replans, answering every point you made; steps you edited keep your words. get_story, save_plan

   The story card says

   • "Plan v1 ready for you" — Review plan →.
   • "Plan · changes requested · waiting for the agent", with an orange edge. The next version opens on Changes: what changed, and the agent's reply to each of your points.
   • "Ready for dev ✓ · Declared ready by you", with Undo.

3. 3 · on the Review tab, while it runs

   Build

   You

   Nothing, until the agent needs you. Review shows the run while it's going, with Stop; if the agent gets stuck it raises a blocker, which names the one decision it needs from you.

   Your agent

   Claims the story — one at a time, and only once it has what "Before agents build" asks for; a story that isn't in the build order yet is added to the end of it — and is handed the approved plan, your edits marked as yours. It builds, opens a pull request and links it to the story. start_story, link_pr, raise_blocker

   The story card says

   • "Agent building · started 12m ago" — See the live run →.
   • "Blocked — the agent needs a decision", quoting it, with Resolve →.

4. 4 · on the Tests tab

   Tests

   You

   See the tests and what each proves: every test card is tagged with the criteria it proves (AC 02 · pass), and the line at the top names any criterion with no test. On Spec, each criterion says "2 tests" or, in amber, "No test".

   Your agent

   Saves its tests linked to the criteria they prove — each with its file and full name — and reports each criterion passing or failing. A test's status comes from that report, or, once CI reporting is on, from your suite running in CI: the card then reads "passed on <sha>" with no agent involved. Turn CI reporting on with the "Set up test reporting" prompt in the Prompt library, or `intent ci`. save_tests, report_criteria

   The story card says

   • A red dot on Tests when any test fails.
   • "passed on <sha> · <time ago>" on a card once CI reports it.

5. 5 · on the Review tab

   Review

   You

   Read the verdict first — "4 of 5 criteria pass. One needs you.", naming only the one — then what the agent built (summary, PR, files, screenshot). Approve, or Request changes with a note saying what to fix; the story goes back to the agent with it.

   Your agent

   Marks the story dev complete with its pull request. It can't until every must criterion passes, and it can never approve its own work. complete_story

   The story card says

   • "5 of 6 criteria passing · built 2m ago" — Review it →.
   • "Approved by you · just now", or "Sent back for rework" with what you asked.

Before agents build

What a person must have done before an agent may start a story:

• Nothing — Agents can start any story.
• Spec — Agents build a story only once a person has marked it ready for dev.
• Spec + plan — Agents can plan any story, but only build one whose plan an approver has approved.

On a personal project you're the only approver: your Approve → Ready on the Plan tab, and your Approve on Review.

In a workspace, owners and admins always approve; an admin can switch it on for any member who can edit (Workspace settings → Plans). Everyone who can edit can comment on a plan, and the approvers send it back or approve it. The same people approve built stories on Review.

New projects start on Spec + plan. Projects from before plan review start on Nothing. A workspace sets it for every project, or one at a time, in Workspace settings → Plans; a personal project can't change it from a screen yet.

A worked example: this article

Story 6e8a72cc, “The day-to-day loop, explained in Help and the Prompt library”, went through the loop like this:

1. Spec. The story was created over MCP (create_stories) with six criteria: the help-menu link, the five steps in order, "Before agents build", this worked example, a prompt in the Prompt library, and a Markdown copy for agents.
2. Plan. The agent saved a seven-step plan (save_plan), naming the files each step touches. It had one question — should the article be public or signed-in only? — which went unanswered, so it stayed public like the other guides. The founder approved version 1 as it stood.
3. Build. The first start_story was refused because the story wasn't in the build order yet. start_story no longer refuses that: it adds the story to the end of the build order. Once the story was placed at #153, start_story claimed it and handed over the approved plan, and the agent built it on its own branch.
4. Tests. The agent wrote a test for each criterion and reported every one with report_criteria. It couldn't record them with save_tests — which files each test against the criteria it proves, so Tests can tag it AC 01 to AC 06 — because its connection to IntentDocs had been set up before save_tests existed, and still listed the old tools. The server had it; the agent's connector hadn't picked it up. Reconnecting fixes that (see below).
5. Review. The agent opened a pull request, linked it with link_pr and marked the story dev complete with complete_story. The founder read the verdict on Review and decided — approve, or send it back with a note.

When your agent can't see a tool

If your agent says a tool here doesn't exist, its connection to IntentDocs was set up before that tool was added: it lists tools when it connects and keeps that list. Reconnect the IntentDocs connector — and allow the new tool if your agent asks you to approve tools — then start a new session.

To run your agent's half of the loop, copy Take a story through the loop from the Prompt library. New to all this? Start with intent-driven development.