reference

Items live as .md files. _priority.md and _icebox.md hold the stack-rank order; every active item appears in exactly one of the two, and am sync enforces this invariant.

my-backlog/
├── .am/config.yaml         iteration · velocity · story-type rules
├── .am/iterations.yaml     per-iteration team-strength + length
├── CLAUDE.md               coach stance · Claude Code reads automatically
├── AGENTS.md               coach stance · Codex CLI + AGENTS.md convention
├── .github/copilot-instructions.md  coach stance · GitHub Copilot
├── .cursor/rules/coach.mdc coach stance · Cursor
├── .claude/skills/         five skills: am-accept, am-decompose, am-inception, am-plan, am-retro
├── .claude/hooks/coach-gate.sh  PreToolUse hook · blocks hard-rule violations
├── .claude/settings.json   wires the gate to set_status and set_estimate
├── index.md                generated · all backlogs
├── velocity.md             generated · velocity links
├── timeline.md             generated · timeline links
├── users.md                generated · user index
├── team-agreements.md      team rules; coach reads as nudges
├── learnings.md            one-line learnings (record_learning appends)
├── users/
│   └── alice.md
├── tags/                   generated · per-tag pages
├── timeline/               generated · per-tag ASCII Gantt
│   └── q2.txt
└── product/                a backlog folder
    ├── product.md          generated · project overview
    ├── archive.md          generated · archive page
    ├── _priority.md        stack-rank · top = next iteration
    ├── _icebox.md          stack-rank · not yet committed
    └── build-login-flow.md the actual item

Files in orange are regenerated on every sync. Don't hand-edit them.

Two ordered files per backlog. Top = highest rank.

• _priority.md. Items committed for an iteration window, or queued just behind it.
• _icebox.md. Stack-ranked but not yet committed. Pre-sprint planning typically sorts the icebox top-down, then bulk-promotes a chunk into priority.

Render with iteration bands sized by rolling velocity:

$ am show priority

Priority (product)   velocity 13 / iteration

── Iteration 47  Mon May 11   0 / 13 pts ──
   1. ★  Build login flow                          started     5p
   2. ●  Reset password bug                        unstarted   1p
   3. ★  Search relevance                          unstarted   3p

── Iteration 48  Mon May 18   0 / 13 pts ──
   4. ★  Saved searches                            unstarted   5p
   5. ⚙  Split OrderService                        unstarted

── Backlog (untimed) ──
   6. ★  Notifications                             unstarted   8p

── Icebox (12 items) ── see `am show icebox`

Single-item promote vs. bulk:

$ am unice "saved-searches.md" --top      # single item, lands wherever you want
$ am unice --all                          # whole icebox to bottom of priority,
                                          # order preserved (the Pivotal pre-sprint move)

The state machine matches Pivotal Tracker. Only stories that reach accepted contribute to velocity.

State definitions

• finished. Dev says "code is done."
• delivered. Deployed to staging or shown to PM.
• accepted. PM signs off. Velocity counts only this state.
• rejected. Sent back. The next move (usually started) clears the completion timestamps.

Story types

• type: feature (default) feeds velocity.
• type: bug and type: chore do not feed velocity unless story_types.bug_estimable or chore_estimable is enabled in config.
• type: release is a marker with a release_date. Used for projecting whether the release will hit given current velocity.

Average accepted points per iteration over the last velocity.lookback completed iterations.

• Iteration windows align to iteration.start_day in iteration.timezone and span iteration.length_weeks weeks.
• An item lands in iteration N when its accepted timestamp falls inside [start, end).
• rolling averages the last N. strict drops high and low first. manual pins a constant.
• New projects bootstrap to velocity.initial_velocity.

The Pivotal velocity formula

per_week  = SUM(points_i / strength_i) / SUM(length_weeks_i)
displayed = floor(per_week * default_length_weeks)

Iterations with team_strength: 0 are excluded from both sums.

Charts are ASCII. Same text in the terminal, in velocity.md and timeline.md on GitHub, and in MCP responses. No images, no binary diffs.

$ am velocity 8

Velocity  last 8 iterations of 1 week

    8 |                ▇▇
    6 |          ▇▇    ▇▇
    4 |    ▇▇    ▇▇    ▇▇
    2 |    ▇▇    ▇▇    ▇▇
      +────────────────────────────
       04/01     04/15     04/29

Per-tag timelines render the same way: ASCII Gantt printed by the CLI, returned by the timeline_chart MCP tool, and embedded in timeline.md by am sync.

An item is YAML frontmatter plus a markdown body.

---
title:     Build login flow
project:   product
type:      feature
status:    started
assigned:  alice
estimate:  5
epic:      auth-rewrite
tags:      [q2, auth]
hypothesis: Login conversion lifts when reset-password is one click
            instead of three.
created:   2026-04-15T09:00:00Z
modified:  2026-05-07T14:02:00Z
finished:  2026-05-09T17:00:00Z
delivered: 2026-05-10T10:00:00Z
accepted:  2026-05-10T16:30:00Z
timeline:
  start:   2026-04-15
  end:     2026-05-10
---

## Problem statement

…

finished, delivered, and accepted timestamps are auto-stamped by am finish / am deliver / am accept. They are not edited by hand.

Optional fields

You don't have to add users manually. am sync reads git config user.name and walks git log. Anyone who has committed gets a users/<name>.md file generated automatically. am create-user stays as an optional override for renaming, aliasing multiple emails, or pre-adding people who haven't committed yet.

A user file is just frontmatter:

---
name:   Alice Example
emails: [alice@example.com, alice@personal.org]
---

The am sync step also writes a generated work view in the body, listing the user's items grouped by project and status. That part is regenerated every sync. Don't edit it by hand.

Items reference users by name, nickname, or email. The lookup is forgiving: assigned: alice, assigned: alice@example.com, and assigned: Alice Example all resolve to the same user file.

Project settings live at .am/config.yaml. Auto-created with sensible defaults on first am create-backlog.

estimation:
  scale:        fibonacci         # linear | fibonacci | powers | custom
  values:       [0, 1, 2, 3, 5, 8]
iteration:
  length_weeks: 1                 # 1 / 2 / 3 / 4
  start_day:    monday
  timezone:     UTC
velocity:
  strategy:         rolling      # rolling | strict | manual
  lookback:         3            # iterations to average
  initial_velocity: 10           # bootstrap
story_types:
  bug_estimable:   false
  chore_estimable: false

Per-iteration team strength and length overrides live separately in .am/iterations.yaml, mirroring Pivotal Tracker's iteration_override resource:

overrides:
  - number:        12
    team_strength: 0.5           # half-team week (vacation, offsite)
  - number:        17
    team_strength: 1.4           # surge week
    length_weeks:  2             # this one iteration is two weeks

am mcp runs a stdio MCP server with 53 tools. Any MCP client connects.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "agilemarkdown": {
      "command": "am",
      "args":    ["mcp"],
      "cwd":     "/absolute/path/to/your/backlog"
    }
  }
}

Restart Claude Desktop. cwd must be a directory inside a git repo containing your backlogs.

Claude Code

$ claude mcp add agilemarkdown -- am mcp

Run from inside the backlog repo. Claude Code uses the current working directory.

Tool reference

The agent is the dev pair, the human is the PM. Hard rules refuse, agreements nudge, acceptance belongs to the human.

The agent writes code, drafts stories, points them, and runs the state machine through delivered. It does not accept its own work. The Pivotal workflow has always run on that two-sided check; the AI-paired version keeps the same seam.

How it ships

am create-backlog writes four files into your repo, one per agent convention. Same body in each. Different filename so each agent reads its native location.

Existing files are never overwritten. The full-body projections (AGENTS.md, copilot-instructions, cursor coach.mdc) share the body in .claude/agilemarkdown-coach.md; a CI drift check compares them after stripping per-format frontmatter.

Two layers, two behaviors

Hard rules. The agent refuses to break these: features are capped at 8 points, bugs and chores are not estimated, the dev pair never accepts its own work, a feature without an ## Acceptance section cannot be pulled, an iteration cannot silently overcommit beyond rolling velocity, and releases stay as date markers rather than going through the state machine.

Working agreements (project-local). The agent reads team-agreements.md at the project root every session. Conflicts surface as nudges, not refusals. The human can override with a reason.

Three seams

The agent pauses at three moments. At pull, the agent restates the story and asks the PM to confirm before code is written; coach_check(action="pull") refuses when a feature has no acceptance bullets. At delivery, the agent flips claimed bullets to [~] with optional claim notes. At accept, the agent renders acceptance_prompt and walks the PM through the bullets one by one. On a hard-rule violation at any seam, the agent prints the rule, its slug, and the next move, then stops. All three are walked end to end in the tutorial.

Coach tools

Three MCP tools and three CLI mirrors back the ceremony so any agent gets the same primitives:

Enforcement (Claude Code hooks)

Words alone are advisory. To make the hard rules enforced rather than encouraged, agilemarkdown ships a PreToolUse hook that gates two MCP tools.

When Claude Code is about to call mcp__agilemarkdown__set_status or mcp__agilemarkdown__set_estimate, the hook fires first, runs am coach-check against the planned action, and exits 2 if the verdict is refused. The tool call aborts and the refusal message surfaces in the conversation. The dev pair can no longer flip accepted on its own work or sneak a 13-point estimate past the cap.

The hook is plain bash. It reads the standard PreToolUse JSON envelope from stdin, picks out tool_name and tool_input, runs the matching am verb, and exits accordingly. Edit it freely; future am init runs do not overwrite an existing file.

Working agreements stay nudges by design. The hook only refuses hard-rule violations. Agreements live in team-agreements.md and the agent surfaces them as warnings, not as blocked tool calls.

Solo mode

One human paired with the agent is the common case. The same person wears both hats: dev's pair and PM. The acceptance prompt still renders, and the human still answers. That pause is what turns "did it run?" into "is this what the user needed?". The agent does not enforce a mode toggle; it trusts the human to answer the second question with care.

Use git. Concurrent edits, attribution, history, access control, and audit are whatever your git host already does for code.

Generated views (index.md, velocity.md, timeline.md, users.md, tags/*.md) regenerate every am sync. Set merge=ours on those paths in .gitattributes if the merges get noisy.