Story workflow

These are the commands you use most. You pick up a story, prove its acceptance criteria pass, and mark it done. All of them need a connected checkout (see intentdocs init).

Note: Changing a story (starting it, finishing it, stopping it, adding one) needs edit rights on the project. The server also refuses these changes when the map owner's trial has ended without an upgrade.

intentdocs status

Shows progress for the connected story map.

intentdocs status

No arguments or options. Prints the map title, a progress bar with the percentage done, counts for done, in progress and todo, the done count for each activity, and the five most recent events from the project's activity feed.

  Checkout app
  ████████░░░░░░░░░░░░ 40%
 
  ✅ Done:        12
  🔨 In progress: 2
  ⬜ Todo:        16
  ── Total:       30
 
  Sign up: 4/5 (80%)
  Checkout: 6/15 (40%)

intentdocs stories

Lists stories, grouped by activity or as a kanban board.

intentdocs stories [options]

intentdocs stories --status wip
intentdocs stories --filter checkout --kanban

Each line shows a status icon, the title (first 70 characters) and the story's key, or the first eight characters of its ID when it has no key.

Behaviour to know:

• When you pass both, --status wins and --filter is ignored.
• An unknown --status value exits 1. An unknown --filter value is treated as search text.
• Text search ignores case.

intentdocs next

Shows the next story to build. It does not change anything.

intentdocs next [options]

intentdocs next
intentdocs next --story-id PB-42 --open

How it chooses:

1. With --story-id, it shows that story.
2. Otherwise, if any story is in progress and you did not pass --skip-wip, it lists those stories and stops. Finish them first.
3. Otherwise, it takes the todo stories that are in the build order and whose dependencies are all done, and sorts them by build step, then release, then priority (must, should, could), then effort (S, M, L, XL). It shows the first.
4. When no todo story qualifies, it tells you why: stories are unsequenced, blocked by unfinished dependencies, or everything is done.

It prints the title, activity, priority, effort, release, build step, the acceptance criteria, the full ID, the spec URL, whether an implementation plan is ready, and the implement command to run next.

Note: next never offers a story that is not in the build order. Sequence it on the Plan view first, or name it with --story-id. When you name an unsequenced story, next tells you that starting it adds it to the end of the build order.

intentdocs implement

Marks a story in progress and writes its context file.

intentdocs implement <id> [--stub]

intentdocs implement PB-42
intentdocs implement PB-42 --stub

What it does, in order:

• If the story is done, it says so and stops.
• If the story is already in progress, it says so, prints the done command, and stops. It does not rewrite the context file.
• If the story has unfinished dependencies, it lists them and stops.
• If the story is sized XL, it suggests breaking it down and asks you to confirm. Without a terminal to answer, it skips the story.
• If the story has no acceptance criteria, it warns you and continues.
• It sets the story to in progress and clears any earlier stop signal. A story that is not yet in the build order is added to the end. If the server refuses, it prints the server's reason and Not picked up, writes nothing, and exits 1.
• It writes .intent/stories/<id>.md with the story, its criteria and checks, its implementation plan when one is ready, and sections for your approach, notes, decisions and relevant files. If the file already exists, what you wrote in those four sections is kept.

With --stub, it asks IntentDocs to suggest a command that would verify each criterion without an executable command. The suggestions run on the Anthropic key saved with intentdocs keys set, or on your plan, like complexity and research. It prints the suggestions and writes them to .intent/stories/<id>.checks.md. It does not change the criteria; copy the commands you want into each criterion on the web, then run them with intentdocs check.

When the server can't run the suggestions (no paid plan and no saved key), the CLI uses ANTHROPIC_API_KEY from your environment if it is set, and calls the Anthropic API directly. Otherwise, or when the request fails, it prints a warning and skips this step. The story is still picked up.

Note: Some projects require a person to mark a story ready for dev, or to approve its plan, before it is built. The server then refuses to move the story to in progress, and implement prints its reason and exits 1.

intentdocs check

Runs a story's executable acceptance criteria on your machine and prints pass or fail for each.

intentdocs check [idPrefix] [--report]

intentdocs check
intentdocs check PB-42 --report

A criterion runs when its verification method is executable and it has a command. The command runs in your shell from the current directory, with a 30-second timeout. Exit code 0 is a pass; anything else is a fail. Every other criterion prints as manual and is skipped.

  Checking: Password reset
  ────────────────────────────────────────
  ✅ [must][executable] Reset link works once
  ❌ [must][executable] Expired links are rejected
       exit 1
  ⬜ [should][founder] The email reads clearly — manual

Each line shows the criterion's priority (must, or should when none is set) and its method (executable, self-check, visual or founder). A failure prints the first line of the command's output.

Behaviour to know:

• With no idPrefix, it exits 1 when no story or more than one story is in progress.
• It exits 1 when any criterion fails, with or without --report.
• --report sends only the criteria it ran, with up to 1,000 characters of output each. Manual criteria are not reported.
• Run it from the directory the commands expect, usually the repository root.

intentdocs show

Prints a story's full spec and refreshes its context file.

intentdocs show <id>

intentdocs show PB-42

Prints the status, title, activity, type, priority, effort, release, full ID and spec URL; the user story as "as a", "I want" and "so that"; the acceptance criteria; design references; notes; and evidence. It then refreshes .intent/stories/<id>.md from the live story, keeping what you wrote under Approach, Implementation notes, Decisions and Relevant files. Exits 1 when no story matches.

intentdocs done

Marks a story done.

intentdocs done <id> [--screenshot <path>] [--pr <url>]

intentdocs done PB-42
intentdocs done PB-42 --screenshot ./checkout.png
intentdocs done PB-42 --pr https://github.com/acme/app/pull/128

What it does, in order:

1. Checks the criteria. It prints each criterion with its priority and last result. A must criterion blocks when its last result is not pass, including when it was never reported. Cancelled criteria and should criteria never block. When something blocks, it lists the criteria and asks Mark done anyway?. Answer y to override, or anything else to stop without changes.
2. Collects your notes. It reads the Implementation notes and Relevant files sections from .intent/stories/<id>.md, if the file exists, and attaches them to the story.
3. Attaches a screenshot. It uses --screenshot when you give one. Otherwise, when the project has an app URL, it captures that page with Playwright from your project's own dependencies (npm i -D playwright). A missing, oversized or failed screenshot is skipped and never blocks.
4. Marks the story done, then reads it back to confirm the server saved it. With --pr, the pull request is linked to the story in the same update. When GitHub is connected, IntentDocs adds the "Spec → Code via intentdocs.com" footer to the PR body; when it is not, the CLI prints the footer line for you to add.
5. Reports releases. When this was the last open story in a release, it prints that the release is ready to close. A person closes it on Validate › Release; the CLI does not.
6. Offers to log a decision or lesson learned, linked to the story.

Behaviour to know:

• With no terminal to answer (piped input, CI, an agent), the override is never granted and the decision prompt is skipped. A blocked story then exits 1 with a message, rather than looking like success. Report the criteria first, with intentdocs check --report or the report_criteria MCP tool.
• The server applies the same must check, so a request that skips the CLI's prompt is still refused.
• It exits 1 when the server does not confirm the story is done.
• A story that is already done prints Already done and exits 0.
• --pr needs a full URL. Anything else exits 1 before the story is touched. The MCP tools complete_story and link_pr link a PR the same way. See Tools and resources.

intentdocs stop

Stops an in-progress story and tells any agent working on it to stop.

intentdocs stop <id>

intentdocs stop PB-42

Sets the story back to todo and records when it was stopped. The local MCP server then refuses every tool call that names the story, except list_stories and get_status, and tells the agent to stop work. Running intentdocs implement on the story again clears the stop.

If the story is not in progress, stop says so and changes nothing.

intentdocs add

Creates a story.

intentdocs add <title> [options]

intentdocs add "Password reset"
intentdocs add "Password reset" --activity Account --priority must --effort L

Prints the new story's title, activity and the first eight characters of its ID.

Behaviour to know:

• The activity name matches regardless of case. A name that matches no activity creates a new activity.
• The story starts as todo in release 1, with no acceptance criteria and no place in the build order. next does not offer it until it is sequenced on the Plan view. You can still start it with intentdocs implement.