{"slug": "my-coding-agents-don-t-need-a-project-management-tool-they-need-markdown-files", "title": "My coding agents don't need a project management tool. They need markdown files.", "summary": "A developer built board.md, a local kanban board that reads and edits markdown task files already stored in a repository, after finding that coding agents only needed readable text files rather than a hosted project tracker. The tool derives in-progress and in-review states from git branches and pull requests, and a card drag rewrites only the single status line in a file's YAML frontmatter to avoid noisy diffs. It also exposes four CLI commands — list, new, set and check — so agents get the same guarantees as the board.", "body_md": "My coding agents used to read their tasks from a hosted tracker. They never needed one. They needed a folder of markdown files, and I needed a small board to look at them.\n\nThis is how I worked that out, and the tool that came from it: [board.md](https://www.npmjs.com/package/board.md), a local board for the markdown task files already in your repo.\n\nI was about to pay for a database when the only reader of the data was an agent that reads text.\n\nI run several projects with coding agents. The tasks lived in Notion, on the free plan, and the agents pulled task details through its MCP server. It worked. But with a few projects I was close to the free plan's limit, and the next step would have cost me about $40 a month. It would have gone the same way with Jira, Monday or ClickUp: the limit and the price differ, the problem doesn't.\n\nBefore paying, I looked at what the agents actually did with a task. They read the title, the notes and a few fields. Then they changed a status. That was all.\n\nAn agent needs a file it can read and edit. One markdown file per task, in the repo, with the fields in YAML frontmatter and the notes below:\n\n```\n---\nid: DEMO-4\ntitle: \"Projects CRUD\"\nstatus: todo\nphase: P2\nmodule: projects\npriority: P0\nsize: M\nbranch:\npr:\n---\n\n# DEMO-4 Projects CRUD\n\nSoft delete. Names unique per account, ignoring case.\n```\n\nThat format beats a hosted tracker for an agent in four ways:\n\n`main` always shows what is merged.`git log` on the file is the task's history.\nOne of my projects already worked this way, with 88 task files. The agents were happy. I was the problem.\n\nI needed to see 88 files as columns and drag a card from one to the next. Nothing more.\n\nMy first plan was something bigger, with a database behind it. I didn't need any of that: the files were already the database. The markdown kanban tools I looked at each wanted their own file layout, and I didn't want to convert files my agents already understood.\n\nSo board.md reads the files you have. `npx boardmd init` looks at them and works out a config: the id format, the statuses, which fields become badges or filters. `npx boardmd serve` shows the board on localhost.\n\n[image: Demo: a card dragged from Todo to In progress changes one line in its file; boardmd new creates a task and its card appears on the board]\n\n\"In progress\" and \"in review\" are not written in any file. The board reads them from git each time it loads.\n\n`task/demo-4-projects-crud`, shows that task as in progress.` todo` gets a badge, so you can see the file is behind.\nThis matters most with agents. My agent creates a branch, does the work and opens a pull request. The card moves across the board by itself, and nobody edits a status until the pull request sets it to done.\n\nWhen I drag a card, exactly one line of one file changes:\n\n```\n-status: todo\n+status: in-progress\n```\n\nThis is the rule the tool is built around. The files belong to the agents and to code review. A board that re-serialises the YAML reorders keys, changes quotes and turns a status change into a noisy diff that conflicts with the next branch.\n\nSo a drop does very little, on purpose:\n\n`status:` line is replaced. The key, spacing, quotes, any comment and the line ending stay as they were.\nA file with no `status:` line is refused, not given one. The board never commits or pushes; a banner lists the files you changed so you can.\n\nAn agent gets the same guarantees as the board, through four commands.\n\n| Command | What it guarantees | \n|---|---|\n| `boardmd list --json` | Every open task with its fields, its file and its live state from git. | \n| `boardmd new \"<title>\" --set phase=P2` | The next id, the right folder and file name, and frontmatter in the same order as the other files. | \n| `boardmd set DEMO-4 status=done pr=41` | Only those lines change. It warns if git shows the task in progress or in review. | \n| `boardmd check` | Every file is validated: ids, file names, folders, required fields, allowed values. | \n\nBefore these existed, creating a task meant the agent guessed the next id, the folder and which fields to fill. Now a wrong guess gets an answer it can act on:\n\n``` bash\n$ npx boardmd new \"Half a task\" --set priority=P9\nCan't create the task: priority must be one of: P0, P1, P2; set phase (P1, P2),\nmodule, size (S, M, L) with --set <field>=<value>.\n```\n\nAn agent also can't use a tool it doesn't know is there. So `boardmd init` offers to add a short section to `CLAUDE.md` or `AGENTS.md`, and a Claude Code skill. Both point at `boardmd guide`, which prints this repo's own rules from the config: where tasks live, the next id, the allowed values for each field and how branches are named.\n\nFor Claude Code there is also a plugin. `/plugin marketplace add anojanst/board.md`, then `/plugin install boardmd@board-md`, adds `/boardmd:setup` to set a repo up and `/boardmd:board` to open its board.\n\nThree commands, from the root of a repo that has task files:\n\n```\nnpm install --save-dev board.md\nnpx boardmd init\nnpx boardmd serve --open\n```\n\n`init` shows what it found and asks before writing anything. With no task files yet, it offers to create a `tasks/` folder with an example. You need Node 20 or later. git and the GitHub CLI are optional: without them the board works, just without branch and pull request state.\n\nIt is free and open source (MIT): [npm](https://www.npmjs.com/package/board.md), [GitHub](https://github.com/anojanst/board.md).\n\nboard.md is deliberately small, and these are the edges:\n\n`boardmd set`, or in your editor.\nIf a team needs comments, assignments and reports, a hosted tracker earns its price. If your agents already keep tasks in markdown, point board.md at them and tell me what breaks.", "url": "https://wpnews.pro/news/my-coding-agents-don-t-need-a-project-management-tool-they-need-markdown-files", "canonical_source": "https://dev.to/anojanst/my-coding-agents-dont-need-a-project-management-tool-they-need-markdown-files-2m0i", "published_at": "2026-10-10 02:16:53+00:00", "updated_at": "2026-10-10 02:29:10.061975+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Notion", "Jira", "Monday", "ClickUp", "git"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/my-coding-agents-don-t-need-a-project-management-tool-they-need-markdown-files", "markdown": "https://wpnews.pro/news/my-coding-agents-don-t-need-a-project-management-tool-they-need-markdown-files.md", "text": "https://wpnews.pro/news/my-coding-agents-don-t-need-a-project-management-tool-they-need-markdown-files.txt", "jsonld": "https://wpnews.pro/news/my-coding-agents-don-t-need-a-project-management-tool-they-need-markdown-files.jsonld"}}