← agilemarkdown
Tutorial

Walkthrough tutorial

One scenario end to end. Every scene shows the same moment on three surfaces: the am shell, the VS Code extension, and Claude Code with the coach skills. Switch any screenshot below, and the rest of the page follows.

Video · overview
[ YouTube embed: agilemarkdown overview ]

Chapters

Before you start

Five steps, plus two optional extras. Same setup whichever surface you favor.

VS Code

Install VS Code if you do not have it. Any modern release works.

Claude Code in VS Code

Install Claude Code. The official extension is at claude.com/claude-code; the same page covers the JetBrains plugin and the standalone CLI for users on Cursor or Zed.

Other agents that read project files (Cursor, Codex CLI, Copilot) work too. The am init step below ships an instruction file for each.

The am binary

A single static binary that runs on Linux, macOS, and Windows for both amd64 and arm64.

shell · macOS arm64
# macOS arm64
$ curl -L -o /usr/local/bin/am \
    https://github.com/mreider/agilemarkdown/releases/latest/download/agilemarkdown_darwin_arm64
$ chmod +x /usr/local/bin/am
$ am --version

Or build from source with Go 1.23+: go install github.com/mreider/agilemarkdown@latest.

Add it to your repo

Open your existing code repo in VS Code, then run am init at the project root.

shell · adopt in an existing repo
$ cd ~/code/my-app
$ am init

This drops the coach-mode files into your repo: an agent-instruction body, the four agent-format projections (Claude, AGENTS, Copilot, Cursor), the five Claude Code skills, and a PreToolUse hook that blocks rule-violating tool calls. Existing files are never overwritten. For a brand-new repo, use am create-backlog instead; it does the same install plus drops a backlog folder. More in the reference.

Wire the MCP server

Claude Code reads MCP config from .mcp.json at the workspace root. Add the agilemarkdown server:

.mcp.json
{
  "mcpServers": {
    "agilemarkdown": { "command": "am", "args": ["mcp"] }
  }
}

For Claude Desktop, the same shape goes in ~/Library/Application Support/Claude/claude_desktop_config.json (or your OS equivalent). For Cursor, paste the JSON into Settings → MCP. For Codex CLI, paste into ~/.codex/config.toml.

Optional: VS Code extension

A board view inside VS Code (current and icebox columns, drag-and-drop reorder, story detail panel, KPI tab) is available as a separate extension. Same MCP server underneath. Install from the marketplace once it ships, or build from vscode/ in this repo.

Optional: bash alias and completion

shell · alias
$ $(go env GOPATH)/bin/agilemarkdown alias am

What this covers

A small product team adopts agilemarkdown for an internal tool. They run one full iteration and start the second. Every command and gesture below maps onto the fixture from tests/fixtures/build-sample.sh, so you can build the same project locally with ./scripts/build-demo.sh and follow along.

The lifecycle is four phases. Inception is rare (once per project). Iteration planning happens at the start of every iteration. The iteration itself is where stories flow through states, and PM acceptance happens continuously, not in a single demo at the end. Retro closes the iteration.

This is the XP cadence, not the Scrum cadence. The iteration plan is a forecast, not a commitment; the team finishes what it finishes. Acceptance is continuous; there is no end-of-sprint demo. Retro is a Friday conversation, not a status report.

Each scene below carries the same screenshot triptych. Pick the surface you actually use; the choice carries across every figure on the page and across pages.

Inception

am inception

Seeds inception.md from the template. Edit the six sections in any editor.

Open inception.md

The extension shares inception.md with every surface. Open it in VS Code and edit the six sections.

/am-inception

Claude walks the six questions one at a time, captures the answers, writes inception.md via inception_doc.

Inception on each surface. Same artifact lands on disk.

The team is starting a new internal tool. They could just start writing stories, but they choose to spend twenty minutes on an inception first. The output is one page with six headed sections: user, goal, reason, success, constraints, out of scope. The PM types; the dev pair (or Claude Code) asks the questions.

What lands on disk

inception.mdOne page. Six headed sections: user, goal, reason, success, constraints, out of scope.

That is the whole inception artifact. No backlog yet. No stories. Stories come from the inception, but they get written once the team is ready to plan the first iteration.

Backlog and stories

am create-backlog / am create-item

am create-backlog product, then am create-item "Login flow". Edit each story's ## Acceptance section.

Board · Add story

Click + in the Current column, type the title, hit Enter. Click the points pip; click the card to edit acceptance.

Seed from inception

"Make a product backlog and seed three stories with acceptance criteria." Claude calls create_backlog, create_item, set_description.

Each surface lands the same files; the difference is whether you type or point.

The team needs a backlog folder and a few stories. Create a product/ folder alongside the code; it gets a product.md overview and three sample stories (a feature, a bug, a chore) you can delete if you do not want the onboarding examples.

Then write the iteration's stories from the inception. The team adds three features: Login flow, Search relevance, Saved searches. Each story's body has sections for Problem statement, Possible solution, Acceptance, Comments, and Attachments. The ## Acceptance section starts with placeholder bullets.

Write real acceptance criteria

Replace the placeholder bullets with concrete criteria. Two to four bullets per feature. Each is something the PM can check; not a property of the code. Bullets ship as GitHub-style checkboxes: [ ] open by default, [~] when the dev pair claims the bullet is satisfied, [x] after the PM verifies it at acceptance time.

product/Login-flow.md
## Acceptance

- [ ] a registered user can sign in with email + password
- [ ] a wrong password produces a recoverable error, not a 500
- [ ] the session persists across a page reload

Without this section in the body the agent has no target, and coach_check action=pull refuses. Writing the criteria up front is what keeps the PM ceremony from falling back to "review the diff."

Estimate

Estimating in Pivotal is about uncertainty, not effort. The Fibonacci scale (1, 2, 3, 5, 8) maps to confidence: 1 is well-trodden, 8 is the hard cap above which the story is an epic.

"A 2-point story for design should equate to the same amount of effort as a 2-point story for a developer. Don't estimate using time. If we find a story is above 3 points, or requires a huge amount of effort, this is a red flag that the story should be broken down."

Pivotal Tracker help center · estimating stories

Login flow is a 5. Search relevance starts at 3 (the team will revise this mid-iteration). Saved searches is a 5.

Iteration planning

am sprint plan

Promote stories with am unice ... --top, then am sprint plan renders the committed set, the below-line backlog, and warnings.

Plan tab

Drag from Icebox into Current. Click the Plan tab in the topbar: committed stories, below-line backlog, warnings rail.

/am-plan

"Plan the iteration." The skill calls sprint_plan and renders the same plan inline.

The Monday-morning view. Same numbers, same warnings, three surfaces.

It is Monday morning. The PM has been ranking the icebox in the days leading up to today, so its top is the order the team will work. Promote the top features from icebox into the priority list, plus a bug and a chore the team plans to slot in if they have slack.

Plan output Velocity reads as 8 (rolling, from the last few iterations). Login flow (5) and Search relevance (3) fit. Saved searches (5) is right at the top of the below-line set; the team flags that it might creep in if Login flow finishes ahead of schedule. Bug and chore stay below the line.

"Tracker auto-plans the future iterations of the Backlog by stuffing them with stories from the top down until each iteration's accepted points reach the project velocity. The current iteration is filled the same way and then shifts to whatever the team has actually started."

Pivotal Tracker help center · planning with velocity

The commit moment There is no separate "commit" file. The act of leaving the rank order in _priority.md as-is and starting to pull stories is the commit. Pivotal Tracker worked this way too.

The iteration

The dev pair (Claude Code, or the developer at the keyboard) works the priority list from the top. Each story moves through unstarted → started → finished → delivered → accepted (or rejected, then back through started). The dev pair never accepts its own work; that seam belongs to the PM.

Story 1 · Login flow · clean accept

am pull → deliver → accept-prompt

am pull claims the top story. After the code lands, am deliver. Then am accept-prompt renders the PM ceremony; am accept flips the status once you say yes.

State machine + ceremony panel

Click started, then finished, then delivered on the detail panel. Clicking accepted does not flip the status: it opens an inline PM ceremony with the bullets and a Yes / Cancel pair.

/am-align → /am-accept

The agent restates the story before pulling, writes the code, claims each bullet at delivery, then renders acceptance_prompt and walks the bullets one by one.

The same ceremony shows up wherever you work: PM seat, bullet by bullet.

The dev pair pulls Login flow. The acceptance bullets are concrete (sign-in with email + password, recoverable error on wrong password, session persists across reload). Code lands; tests pass. The story moves to delivered with each bullet claimed: [~] with a short note about how the claim was met.

The acceptance prompt renders. The PM walks each bullet, verifies it, and approves. Status flips to accepted. The velocity ledger gains 5 points.

Bullet states [ ] open · [~] claimed by the dev at delivery · [x] verified by the PM at acceptance · reopened to [ ] on rejection. The agent never writes [x]. That edge is the PM's.

Story 2 · Search relevance · refused estimate

am estimate → coach refusal

am estimate Search-relevance.md 13 fails: features over 8 points are epics. Use am decompose (or split by hand) to land two pieces at or below the cap.

Points pip caps at 8

The 13 pip is greyed out. Hover for the rule; click 8 if it actually fits, or open a terminal in VS Code and run am decompose.

coach_check → /am-decompose

The agent's coach_check(set_estimate=13) returns refused. /am-decompose drafts the split, you confirm, the original closes.

The 8-point cap shows up at the same seam on every surface.

Halfway into Search relevance, the dev pair realizes it is bigger than 3 points. They try to re-estimate at 13. The coach refuses with the rule and the next move: split into two pieces, each at or below 8. The dev pair proposes the split (a search index, 5 points, this iteration; typo tolerance, 3 points, into the icebox); the PM agrees. The original story closes; the new ones slot in. The dev pair finishes the index. The PM accepts.

Velocity ledger now reads 10 (8 forecast plus the bonus from finishing early). That is fine. The plan is a forecast, not a budget.

Story 3 · Dark mode · rejection with reason

am reject --reason

After am accept-prompt renders, run am reject Dark-mode.md --reason "system-prefers-dark applies at signup, not mid-session". The story flips to rejected; the reason lands in ## Rejection notes.

Inline reject form

Cancel the ceremony panel, click rejected. An inline reason form opens; type the reason, submit. The body picks up a dated rejection note.

reject_item(failing_bullet=N)

"No on bullet 2." Claude calls reject_item with the failing bullet and your reason. Bullet 2 reopens to [ ]; the story flips to rejected; the agent re-pulls.

Rejection is data, not failure. Capture the reason; the dev re-pulls.

Dark mode ships; the dev pair claims all three acceptance bullets. The PM spots a bug: the system-prefers-dark default is supposed to be the default for new users only, set at signup, but the implementation reads the OS theme at component mount. So a user who toggled their OS theme during the session got jumbled colors. Reject with the reason. The dev pair re-pulls, fixes the bug, delivers again. The PM re-accepts.

Rejection is a ritual Pivotal counted rejection as data, not as failure. A healthy rejection rate is 5–15%. Below that the PM is rubber-stamping; above it the team is shipping the wrong thing. The retro reads the latest rejection_rate and asks why.

Retro

am retro

Numbers (velocity, volatility, cycle time, rejection rate), then three questions. Capture outputs with am record-learning and am team-agreements --add.

Terminal pane

The extension does not have a Retro tab today. Open the integrated terminal, run am retro, capture outputs from there.

/am-retro

"Run the retro." The skill pulls dashboard + history, renders the summary, asks the three questions one at a time, and records via record_learning / team_agreements.

Same three questions across surfaces. Same files on disk after.

End of the iteration. Look at the numbers before the conversation: velocity (rolling), volatility (variance), cycle time (median time started → accepted), rejection rate (target band 5–15%). For this iteration: velocity 10, rejection rate 10%, cycle time around 1.6 days median. The forecast for iteration two is now 10.

Three questions. What worked? What did not? What changes for next iteration? Record one or two learnings and, if anything came up, a new working agreement. Agreements get read at the start of the next session by every agent that opens this repo, because team-agreements.md is part of the coach's onboarding.

Bootstrap state On a brand-new project the retro numbers are not meaningful yet. Velocity reads as (bootstrap) until the rolling lookback window has real iterations behind it. Rejection rate buckets only completed iterations, so a story rejected today does not show in the rate until the iteration closes. Cycle time medians on a single short iteration are likewise misleading. The numbers stabilize from iteration three onward; before that the retro is conversation, not metrics.

A second iteration

Monday morning again. The PM ranks the icebox; the team plans iteration two; the dev pair pulls the first story. The shape is identical. The rolling velocity now reflects iteration one (10 points), so the iteration-two forecast is 10.

Halfway through, the dev pair starts a story whose body has no ## Acceptance section. The coach surfaces a nudge with the rule and the next move: add the bullets, or skip with intent. The PM drafts three bullets into the body; the dev pair pulls again. By Friday the team has shipped two features and a bug. Velocity is now 11 (rolling). Yesterday's weather: tomorrow looks like today.

Where to go from here