{"id":49737595,"url":"https://github.com/mreider/agilemarkdown","last_synced_at":"2026-05-14T13:02:18.172Z","repository":{"id":79213261,"uuid":"129934534","full_name":"mreider/agilemarkdown","owner":"mreider","description":"Run your backlogs in markdown","archived":false,"fork":false,"pushed_at":"2026-05-07T13:28:33.000Z","size":4906,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-07T13:38:08.752Z","etag":null,"topics":["agile","markdown","product-management","scrum"],"latest_commit_sha":null,"homepage":"http://agilemarkdown.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mreider.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-17T16:31:06.000Z","updated_at":"2026-05-07T13:29:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"a882ae6c-1e08-4820-bfa4-9c9bf12f71c2","html_url":"https://github.com/mreider/agilemarkdown","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/mreider/agilemarkdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mreider%2Fagilemarkdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mreider%2Fagilemarkdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mreider%2Fagilemarkdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mreider%2Fagilemarkdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mreider","download_url":"https://codeload.github.com/mreider/agilemarkdown/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mreider%2Fagilemarkdown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33026049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agile","markdown","product-management","scrum"],"created_at":"2026-05-09T11:21:54.771Z","updated_at":"2026-05-14T13:02:17.674Z","avatar_url":"https://github.com/mreider.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/apple-touch-icon.png\" alt=\"agilemarkdown\" width=\"180\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eagilemarkdown\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eA backlog manager that stores in markdown so any LLM reads it natively, and coaches you through the Pivotal-style XP workflow.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/mreider/agilemarkdown/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/mreider/agilemarkdown/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nA tool for managing backlogs efficiently. Three pieces fit together.\n\n**The backlog lives in git as markdown.** Each story is a plain file with YAML frontmatter on top and a body underneath. Priority is a ranked list; the icebox is a capture pile, not ranked. Velocity is computed from accepted points across a rolling window. The repo is the database, and any text editor works on it.\n\n**The LLM sees what the human sees.** `am mcp` is a stdio MCP server with 55 tools, and any MCP-aware client connects (Claude Desktop, Claude Code, Cursor, Codex CLI). LLMs read markdown natively, so the agent and the human are looking at the same files at the same time.\n\n**The Pivotal way ships as a coach.** The agent is the dev pair and the human is the product manager. The hard rules block real violations: features are capped at 8 points, bugs and chores are not estimated, the dev pair never accepts its own work, an iteration cannot silently overcommit beyond rolling velocity, and releases stay as date markers. Working agreements layer on top as nudges, and acceptance is the moment the human owns.\n\n## Lineage\n\nagilemarkdown is the way Pivotal built software, encoded in plain files for the AI era.\n\nI worked at Pivotal Software for six years. Pivotal Labs was the consulting practice; [Pivotal Tracker](https://github.com/pivotaltracker) was the opinionated SaaS the team built for itself and shipped to anyone who wanted to work the same way. The two went hand in hand: Tracker only made sense if you also followed the workflow it assumed. This project is biased toward Pivotal Tracker on purpose. The original help center, captured by the [Internet Archive on 2017-05-03](https://web.archive.org/web/20170503214450/https://www.pivotaltracker.com/help/), is quoted inline throughout the site.\n\n## Documentation\n\n[https://agilemarkdown.com](https://agilemarkdown.com)\n\n- [Tutorial](https://agilemarkdown.com/tutorial.html). End-to-end walkthrough of the Pivotal lifecycle (inception, plan, iteration, retro) on the same fixture as the test suite. Three surfaces: CLI, Claude Code, VS Code extension.\n- [Reference](https://agilemarkdown.com/reference.html). Repository layout, item schema, state machine, velocity formula, MCP tools, CLI verbs, coach-mode wiring, and configuration.\n\n## Install\n\nThe intended workflow is: VS Code with Claude Code installed, your code repo open, agilemarkdown added to the repo, the MCP server wired up. After that the agent reads the backlog and writes the code in one place.\n\n**1. VS Code.** Install [VS Code](https://code.visualstudio.com).\n\n**2. Claude Code.** Install [Claude Code](https://claude.com/claude-code) in VS Code. Other agents that read project files (Cursor, Codex CLI, Copilot) work too; the install step below ships an instruction file for each.\n\n**3. The `am` binary.** Single static binary, available for Linux, macOS, and Windows on amd64 and arm64.\n\n```\n# macOS arm64 example\ncurl -L -o /usr/local/bin/am \\\n  https://github.com/mreider/agilemarkdown/releases/latest/download/agilemarkdown_darwin_arm64\nchmod +x /usr/local/bin/am\nam --version\n```\n\nOr build from source with [Go 1.23+](https://go.dev/dl/): `go install github.com/mreider/agilemarkdown@latest`. See the [latest release](https://github.com/mreider/agilemarkdown/releases/latest) for prebuilt binaries.\n\n**4. Add agilemarkdown to your code repo.** Open your repo in VS Code and run:\n\n```\ncd ~/code/my-app\nam init\n```\n\nThis drops the coach-mode files (source body at `.claude/agilemarkdown-coach.md`, a thin `CLAUDE.md` that `@`-imports it, AGENTS.md, copilot-instructions, cursor rule, the six Claude Code skills, and the PreToolUse hook with settings.json). Existing files are never overwritten. Greenfield repos can use `am create-backlog` instead, which adds a backlog folder on top.\n\n**5. Wire the MCP server.** Claude Code reads MCP config from `.mcp.json` at the workspace root. Add:\n\n```json\n{\n  \"mcpServers\": {\n    \"agilemarkdown\": { \"command\": \"am\", \"args\": [\"mcp\"] }\n  }\n}\n```\n\nFor Claude Desktop, paste the same JSON into `~/Library/Application Support/Claude/claude_desktop_config.json` (or the equivalent for your OS). Cursor: Settings \u0026rarr; MCP. Codex CLI: `~/.codex/config.toml` per the codex docs.\n\n**6. Optional: the Agile Markdown VS Code extension.** A board view inside VS Code (Current, Icebox, Epics, detail panel, drag-and-drop, KPI tab, ⌘K search). The extension shells out to the same `am` CLI per click, so anything the board does is reachable from your shell too. Install from the marketplace once it ships, or build from `vscode/` in this repo.\n\n**7. Optional: bash alias.**\n\n```\n$(go env GOPATH)/bin/agilemarkdown alias am\n```\n\n## Start a backlog\n\nA backlog is a git repo. Empty or shared:\n\n```\nmkdir my-backlog \u0026\u0026 cd my-backlog\ngit init\nam create-backlog product\ncd product\nam create-item \"Build login flow\"\nam sync\n```\n\n`am create-backlog` drops three sets of files into the repo: the backlog folder itself with sample stories, the agent-instruction projections so any AI agent inherits the coach stance, and the Claude Code skills + PreToolUse hook under `.claude/` so the hard rules can actually block tool calls. Existing files are never overwritten.\n\nThe source coach body lives at `.claude/agilemarkdown-coach.md`. `CLAUDE.md` is a thin file that pulls it in via `@.claude/agilemarkdown-coach.md`, so a project that already has its own `CLAUDE.md` instructions can keep them and add a single import line. `AGENTS.md`, `.github/copilot-instructions.md`, and `.cursor/rules/coach.mdc` carry the same body inline since those formats do not support the `@` import.\n\nAlready have a backlog repo from before v4.4? Run `am init` in it to install or refresh the same set. Idempotent.\n\nUsers auto-discover from `git config` and `git log`. For a team-shared backlog, push the repo to GitHub. Each contributor clones it, runs `am` locally, and pushes their changes. Repo permissions are the access model; branch protection plus required reviews give backlog changes an approval flow.\n\n`am sync` regenerates derived views (`index.md`, per-tag pages, `velocity.md`, `timeline.md`, `users.md`), validates each item against the JSON Schema, then commits and pushes if a remote is configured.\n\n## Editing\n\nAny markdown editor works. Items are YAML frontmatter on top with a markdown body underneath, so VS Code, Obsidian, nvim, Cursor, and the rest read them out of the box.\n\n## AI integration\n\n`am mcp` exposes the backlog as a Model Context Protocol server with 55 tools across read, write, run, and coach categories. Wire it into Claude Desktop, Claude Code, Cursor, or any MCP-aware client and the agent can:\n\n- Read and write items, change status, run sync, validate the schema\n- Stack-rank `_priority.md` and `_icebox.md`, bulk-promote icebox to priority preserving order\n- Render velocity, iteration, burnup, and epic-burnup charts as ASCII inline in the chat\n- Capture rejection reasons, hypotheses, learnings, and team agreements as plain markdown\n- Run the coach: preflight an action against the hard rules (`coach_check`, including `action=pull` for pre-pull alignment), render the PM ceremony for a delivered story (`acceptance_prompt`), check whether the iteration fits rolling velocity (`iteration_fit`)\n- Walk acceptance bullets: `list_acceptance`, `set_acceptance_state` (open / claimed / verified), `append_acceptance_bullet`\n\nThe same surface is reachable from the shell. Every read view has a `--json` sibling (`am dashboard --json`, `am show priority --json`, `am sprint plan --json`, `am show cfd --json`), and ten data-export verbs (`am list-backlogs`, `am list-items`, `am get-item`, `am get-comments`, `am type-mix`, `am cfd`, `am whoami`, `am history`, `am search`, `am set-description`) emit the same JSON shapes the MCP server returns. Pipe through `jq` for shell scripts, CI checks, or status-bar widgets without standing up an MCP client. See the [Data API reference](https://agilemarkdown.com/reference.html#data-api).\n\n## Coach mode (AI as dev pair, human as PM)\n\nThe coach is the part of agilemarkdown that turns an MCP-aware agent into a practitioner of the Pivotal way. It ships in four layers.\n\n**Words.** `am create-backlog` writes the source coach body to `.claude/agilemarkdown-coach.md` and projects it across the four agent-instruction formats: `CLAUDE.md` is a thin `@` import (so an existing CLAUDE.md is not overwritten), and `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/coach.mdc` carry the same body inline. The body says: the agent is the dev pair, the human is the PM, here are the hard rules, here is how to run the acceptance ceremony.\n\n**Tools.** Three MCP tools and CLI mirrors back the ceremonies: `coach_check` returns a structured verdict with the rule, its slug, and a suggested next move; `acceptance_prompt` renders the PM ceremony from a story file; `iteration_fit` reports whether the iteration overcommits.\n\n**Skills.** Six Claude Code skills under `.claude/skills/` auto-fire on the right phrases: `am-inception` runs the kickoff, `am-plan` runs IPM, `am-align` runs the pre-pull restatement so the agent does not confidently build the wrong thing, `am-decompose` breaks a problem into Pivotal-sized stories, `am-accept` runs the PM acceptance ceremony bullet-by-bullet, and `am-retro` runs the end-of-iteration retro.\n\n**Hooks.** A PreToolUse hook at `.claude/hooks/coach-gate.sh`, wired through `.claude/settings.json`, gates `set_status` and `set_estimate`. When Claude Code is about to flip a story to `accepted` or estimate a feature above 8 points, the hook intercepts and exits 2; the tool call aborts with the refusal message in the conversation. Words become teeth.\n\nRun `am coach` in any agilemarkdown repo to see the coach's read on the project right now.\n\n## Multi-user\n\nGit provides the multi-user model. Concurrent edits across different items merge cleanly, attribution comes from the git author of each commit, and history is read with `git log path/to/item.md`. Access control is the repository's permissions. Generated views regenerate every sync; configure `.gitattributes` with `merge=ours` on those paths if their merges become noisy.\n\n## Inspired by\n\nThe workflow comes from [Pivotal Tracker](https://github.com/pivotaltracker). agilemarkdown follows the same six-state machine, the same acceptance gate, fixed iteration windows, velocity computed from accepted points, the same story-type rules (features pointed by default, bugs and chores not), the icebox as the single intake list, and the bulk-promote step from icebox to backlog. See [\"Why do we miss Pivotal Tracker?\"](https://dwf.bigpencil.net/why-do-we-miss-pivotal-tracker/) for the rationale that drove the design.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmreider%2Fagilemarkdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmreider%2Fagilemarkdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmreider%2Fagilemarkdown/lists"}