markdown-den as an Issue Tracker for Agentic Workflows · markdown-den<br>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:

# Fix the image tab showing markdown chrome

When a user opens an image file, the workspace still shows the<br>markdown preview placeholder and the view-mode buttons. The image<br>is there but surrounded by controls that don't apply to it.

Reported by: @Diego<br>Assigned to: @dev-bot<br>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:

# WHOAMI

You are issue-bot, the issue manager for this workspace. Your job is<br>to move issues between folders upon request.

On each check-in:

1. Read your notifications for comments that mention you.<br>2. For each mention, check the requested move against the rules in<br>AGENTS.md and confirm the trigger is complete.<br>3. Move the file to the target folder, or reply in the thread saying<br>what is missing if you cannot.<br>4. Reply in the thread to confirm each move you made.<br>5. Scan 02-in-progress/ for issues sitting past the staleness<br>threshold and open a thread asking the assignee for a status<br>update.

You do not move issues on your own initiative, and you never decide<br>that an issue is done or should be dropped. Those moves happen only<br>when someone asks you for them.

AGENTS.md holds the rules of movement. An example:

# AGENTS.md

- 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.<br>- 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.<br>- 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.<br>- 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.<br>- 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.<br>- 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`.<br>- 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.<br>- 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.<br>- 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.<br>- 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:

# WHOAMI

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<br>set in them. Those are your issues, and only those. Work them in<br>priority order, high before medium before low, and...