Walkthrough tutorial
Every chapter shows the same thing three ways: the board, the am command line, and the MCP JSON-RPC an AI agent would call. By the end you'll know which surface to reach for, and you'll have seen the full mapping between them.
The Pivotal week
The workflow the tutorial walks through is Pivotal Tracker's, which Tracker had picked up from Extreme Programming. The chapters show each mechanic in detail; this page is a quick map of the week they fit into.
One ranked backlog. Different tools mean different things by "backlog." Here it is a single list of stories, ranked top to bottom. The top of the list is the current sprint, the work we expect to finish this week. A sprint is a week, not two, and it is not a contract for a fixed set of stories. Unplanned work arrives every week and the team finishes what it finishes. As people free up, they pull the next story off the top.
Velocity is a forecast. Each story carries a point estimate that the team agrees on, and agilemarkdown places markers down the backlog from those estimates, showing which stories will land this week, next week, or later. The math factors in team strength (who's sick, who's on vacation), and only estimated stories get markers. Projections get looser the further down you look.
"Velocity is the average normalized points completed across the last N iterations, where N is the project's Velocity Strategy setting (default 3, range 1-4). Velocity is computed once per iteration boundary and shown as an integer (it is floored on display and never rounded up)."
Pivotal Tracker help center · understanding velocity
Three kinds of work. A feature is a story carrying a point estimate and an acceptance check, and the dev pair pulls one off the top and works it; the PM accepts it once delivered, and the coach refuses any attempt by the dev pair to accept its own work. Bugs go to the top of the list with no estimate, so a buggy stretch shows up automatically as a drop in velocity. Chores are the work the team owes itself (CI setup, a doc fix after a customer complaint, research the team needs), and they stay unpointed because they don't ship to a customer. Release markers don't really fit, since they aren't work at all; they're dated stakes you plant in the priority list to anchor a ship date (Chapter 7).
The icebox. A backlog needs a place for ideas that are not ready to prioritize. The icebox is that place: a capture pile that is not ranked and is not being worked on. Engineers drop in features they think would be cool, the PM parks ideas before deciding, customer feedback lands there as it comes in. At planning time, items get pulled out, talked through, estimated if they are nearly ready, and ranked into the backlog at whatever position the PM decides.
The weekly rhythm.
- Monday plan. The team walks the top of the backlog together so the week is clear, estimates anything new with a quick fingers-up game called pointing poker, and slides out any story the PM cannot answer clearly. The aim is to leave ready to work, not stuck on questions.
- Daily standup. A short go-round in which each person offers either an interesting (something they learned, or something another team is doing) or a help (I am stuck on X, who can pair). Helps often resolve in the meeting itself, the PM can pass without speaking, and a standup with nothing to report is a perfectly good thing.
- Story time. On most Friday afternoons the PM and the engineering lead meet to prep for Monday, pulling icebox items out and estimating them so they can be ranked into priority.
- Friday retro. On Friday afternoon the team puts three columns on a board (good, meh, not so good) and walks through them. People add topics, the team discusses them without making it personal, and whatever action items come out get checked on at the start of the next retro.
The 8-point cap holds across all of this. Any story bigger than 8 points is an epic and gets split before it can move. agilemarkdown's coach refuses to estimate a feature above the cap; Chapter 6 covers epics directly.
Following along
The tutorial uses two project states. Chapters 1–2 start from an empty repo so you can see how an agilemarkdown project comes into being. Chapters 3 onward use a seeded fixture in the spirit of Arnold Lobel's Frog and Toad, Toad mailing letters, Frog tending a seedling, Owl planning the moon's birthday. The whimsy is the example, not the tool. (Lobel, Frog and Toad Are Friends, Harper & Row, 1970.)
If you want to follow along interactively, run the laboratory:
am serve --root /tmp/am-demo --fixture scripts/build-demo.sh
open http://localhost:8080That gives you the same web UI, CLI, and MCP console the tutorial captures from. Every action you take maps to a CLI verb in the CommandLog tab and a JSON-RPC frame in the MCP Console tab.
Chapters
How to read each chapter
Each moment is a single operation shown three ways. The table reads left-to-right: GUI screenshot, then the CLI verb you would type to do the same thing, then the JSON-RPC frame an MCP client would send.
The MCP column carries a Full envelope toggle. Open it to see the literal JSON-RPC request and response, same bytes an AI agent exchanges with the project.