markdown-den as an Issue Tracker for Agentic Workflows
By Diego Guridi
TL;DR: Five numbered folders are a workflow. A markdown file is an issue, and moving it between folders is how its status changes. Add an agent to manage the backlog, a second to do the work, a third to review it, and the workspace makes progress while you are not looking at it.
You don't need a dedicated issue tracker to run a disciplined backlog. This post shows how to build one inside markdown-den using nothing but folders, markdown files, and an agent, and how to extend it so that a voice conversation is enough to file a ticket.
The folder structure #
Create five folders at the root of your workspace:
01-to-do: issues that are ready to be picked up** 02-in-progress**: issues someone is actively working on** 03-ready-for-review**: issues that are complete and waiting for a second pair of eyes** 04-done**: issues that are closed and resolved** 05-dropped**: issues that were considered and consciously set aside
An issue is a markdown file. It lives in exactly one folder at a time. Moving it is the act of changing its status. There is no status field to keep in sync, no database to update. The folder is the status.
What an issue looks like #
A file in 01-to-do/
might look like this:
When a user opens an image file, the workspace still shows the
markdown preview placeholder and the view-mode buttons. The image
is there but surrounded by controls that don't apply to it.
Reported by: @Diego
Assigned to: @dev-bot
Priority: high
That's it. No template required, though you can establish one in AGENTS.md if you want consistency.
Adding an agent #
The power comes when you add an agent to the workspace. It needs two files: its own WHOAMI.md, and the workspace's AGENTS.md.
WHOAMI.md, in the agent's private folder, tells the agent who it is and what it is allowed to touch. For example:
You are issue-bot, the issue manager for this workspace. Your job is
to move issues between folders upon request.
On each check-in:
1. Read your notifications for comments that mention you.
2. For each mention, check the requested move against the rules in
AGENTS.md and confirm the trigger is complete.
3. Move the file to the target folder, or reply in the thread saying
what is missing if you cannot.
4. Reply in the thread to confirm each move you made.
5. Scan 02-in-progress/ for issues sitting past the staleness
threshold and open a thread asking the assignee for a status
update.
You do not move issues on your own initiative, and you never decide
that an issue is done or should be dropped. Those moves happen only
when someone asks you for them.
AGENTS.md holds the rules of movement. An example:
- Issues are numbered sequentially. The filename is `NNN-short-title.md`, where NNN is a zero-padded integer that never resets: `001-fix-image-chrome.md`, `002-status-bar-word-count.md`, and so on. The agent assigns the next number on intake and never reuses one.
- An issue moves from `01-to-do/` to `02-in-progress/` when someone leaves a comment saying `@issue-bot ready to move`, with `Assigned to: @username` set in that comment or already in the file.
- An issue moves from `02-in-progress/` to `03-ready-for-review/` when the assignee has finished the work. An assignee who can move files moves it themselves; anyone else comments `@issue-bot ready for review` and issue-bot moves it.
- An issue moves from `03-ready-for-review/` to `04-done/` when a reviewer other than the assignee passes it. The reviewer moves it and comments why.
- An issue moves from `03-ready-for-review/` back to `02-in-progress/` when a reviewer fails it. The reviewer moves it and comments the reason. The assignee does not change.
- Anyone who cannot move files asks issue-bot instead, naming the move: `@issue-bot ready for review`, `@issue-bot done`, `@issue-bot back to in-progress`, `@issue-bot drop`.
- An issue moves from anywhere to `05-dropped/` when an author or workspace owner comments `@issue-bot drop`, with a one-line reason in the same comment.
- Issue-bot acts on its next check-in after receiving a mention. It replies in the thread to confirm the move, or to say what is missing if the trigger is incomplete.
- Anyone who can move files may move an issue by dragging it into the right folder. Issue-bot does not own the folders. It watches them and moves issues upon request.
- No issue is deleted. 05-dropped/ is permanent record.
Adding a developer bot #
The issue-bot manages the backlog. A second agent, the developer bot, does the work.
Give it its own WHOAMI.md in its private folder:
You are dev-bot, the developer agent for this workspace.
On each check-in:
1. Scan 02-in-progress/ for files that have Assigned to: @dev-bot
set in them. Those are your issues, and only those. Work them in
priority order, high before medium before low, and where the
priority is equal, take the lower issue number first.
2. Read the issue and any comment threads on it, including review
feedback if it has been sent back.
3. Do the work described in the file.
4. Move the issue to 03-ready-for-review/.
5. Comment on the issue summarising what you did.
You do not touch issues assigned to someone else, and you never move
an issue to 04-done/. Passing the work is the reviewer's call.
The two agents divide responsibility cleanly: issue-bot owns the workflow, dev-bot owns the work. Nothing reaches 04-done/ without a second pair of eyes at 03-ready-for-review/, and dev-bot's are not the eyes in question.
An issue in 02-in-progress/ is not always there for the first time. A reviewer can send it back with a comment saying what failed. As long as it is still assigned to @dev-bot, dev-bot picks it up on its next check-in, addresses the feedback, and moves it to 03-ready-for-review/ again.
The reviewer #
At this stage the reviewer is probably you. An issue lands in 03-ready-for-review/, you read dev-bot's summary comment, you look at the work, and then you just move the file yourself: into 04-done/ if it passes, or back into 02-in-progress/ with a comment saying what failed. No need to ask the bot to do it for you.
But nothing about the workflow requires the reviewer to be human. A third agent can hold that gate:
You are review-bot, the reviewer for this workspace.
On each check-in:
1. Scan 03-ready-for-review/ for issues you have not yet reviewed.
2. Read the original issue and dev-bot's summary comment.
3. Check the work against the acceptance criteria stated in the
issue. If the issue states none, say so and do not pass it.
4. If it passes, move the issue to 04-done/ and comment with a
one-line reason.
5. If it does not, move it back to 02-in-progress/ and comment with
the specific criterion that failed and what would satisfy it.
Leave the assignee unchanged.
You review against the issue as written. You do not widen the scope,
and you do not fix the work yourself. That is dev-bot's job.
The rejection path is the interesting one. Review-bot moves the issue back to 02-in-progress/ itself and comments the specific failed criterion. It is still assigned to @dev-bot, so on dev-bot's next check-in it reads the review comment as feedback, addresses it, and moves the issue forward again. The two agents loop without anyone in the middle, and every round trip is recorded as comments on the file. Both of them move files directly, so issue-bot is not in the path at all here: it exists for the moves that need a rule applied, not for every move.
What makes the bots check in #
Everything above says "on each check-in" without saying what causes one. There are three ways to arrange it.
Manually. You start the agent when you want it to run. Simplest, and often enough: you file a few issues, then tell dev-bot to go.
On a loop. The agent is prompted with check in
on a schedule. It wakes up, runs the check-in steps in its WHOAMI, acts, and sleeps again. The workspace becomes something that makes progress while you are not looking at it.
Reacting to events. An application watches the workspace and starts the relevant agent when something actually happens: a file lands in a folder, a comment mentions a bot. No polling, no idle runs, and the reaction is immediate.
The workflow in this post does not care which one you pick. The folders and the rules are the same either way; only the latency changes.
Intake: the human drop #
The simplest intake is a human creating a file in 01-to-do/
. Open a new file, write the issue, save it. Issue-bot picks it up on its next check-in, gives it the next number in sequence, and acknowledges it with a comment.
This works. It is low friction and leaves a clear paper trail.
Intake: voice to bot #
The upgrade is filing an issue by voice. Instead of typing, you speak. A capture bot listens, writes down what you said as a markdown file in 01-to-do/
, and reads it back to you before saving. From there it is an ordinary issue, and the same rules move it.
The conversation might go:
"File a ticket: the image tab is showing markdown chrome. High priority."
The bot creates 01-to-do/001-image-tab-markdown-chrome.md
, reads it back, and confirms it is filed. You never touched a keyboard.
This is the same setup used to draft this post: a voice session driving writes to the markdown-den workspace. The issue tracker is just another application of the same pattern.
What you end up with #
A workspace that is also a backlog. Every issue is a file, every status change is a move, every conversation about an issue is a comment thread anchored to the file it concerns. The full history of a ticket, its creation, its discussion, its resolution, is in one place and readable as markdown.
About markdown-den #
markdown-den is a collaborative workspace for markdown files where people and AI agents are both participants. You get a file tree in the browser, you write in markdown, and your agents connect to the same workspace over MCP and read and write the same files you do. Comment threads anchor to a specific sentence, agents have their own folders and can be mentioned, and everything is reachable from a desktop, a phone, or a machine running an agent somewhere else.
More from me #
The Chat Window is a Dead End. Why everything worth keeping drifts toward files, and what the file tree is actually for.AI-assisted, Spec-Driven Software Development with markdown-den. The ladder from a one-line idea to a spec with code, and how to set a workspace up for it.