Updated 8 October 2026

A markdown issue tracker your coding agents can work from

Keep each issue as one markdown file in a folder, with the status and priority in a few lines of frontmatter at the top. An agent can then read the backlog, change a status, comment on an issue and file a follow-up using nothing but file access, which every coding agent already has.

This page shows the file format and the rules that keep it safe to edit, whether or not you use Agency. Further down it says what Agency does with the same files, and one thing about them that is not what you might expect. Disclosure: Agency is ours, and this site is its home.

Why agents cannot work from your tracker

A hosted tracker lives behind a login and an API. An agent in a terminal does not see it unless you wire up a connector, and even then it works through a handful of tool calls rather than reading the backlog the way it reads code. A folder of markdown files has no such gap: the agent lists the folder, opens a file and edits it, the same as any source file.

The file format

This is the format Agency uses for its own backlog (the project's .agency/issues/README.md, as of October 2026). One file per issue, named for its key, with the title as the H1:

---
key: AGE-14
uid: 8fbc9e2a-3d41-4c7e-9a10-5b6d2f8e04c3
status: in_progress        # backlog|todo|in_progress|in_review|done|cancelled
priority: 2                # 0-4
created: 2026-07-27T09:30:00Z
updated: 2026-07-27T14:02:00Z
---
# Issue title

Body markdown, wikilinks allowed.

## Sam · 2026-07-27T15:10:00Z

A comment.

• Change status by editing status:. Closing an issue is status: done.
• File an issue by adding <KEY>-<n>.md with the next unused number for the key. Numbers are never reused or renumbered, even after a deletion, so a reference to AGE-14 keeps meaning the same issue.
• Comment by appending a ## <author> · <UTC RFC3339> section to the end of the file. The description is everything between the H1 and the first heading of that shape, so a comment never overwrites it.
• Link issues with links: AGE-12, LBH-3. Links are undirected: the other issue gets the link too.
• Attach files under assets/ and reference them by relative link, such as ![](assets/AGE-14-shot.png), so the same link works in any markdown editor.
• Timestamps are UTC RFC3339, and updated is bumped on every edit.

The uid is written by the app. It identifies the issue if the folder is ever copied somewhere the numbering is not shared, so you do not copy one between issues or edit it. Agency reads frontmatter strictly: a file whose key does not match its name, or whose status is not one of the six, is skipped rather than guessed at.

Set it up by hand

1. Make the folder and one file

   Create issues/ (or .agency/issues/, the path Agency uses) and add PRJ-1.md with the frontmatter above. Pick a short key for the project and keep it.

2. Tell the agent where it is

   An agent only knows what is in its context. Put the absolute path of the folder and the rules above into the file your agent reads at start, such as CLAUDE.md or AGENTS.md, and say outright that "file an issue" means this folder. If you have a hosted tracker connected as well, an agent asked to file an issue will otherwise pick whichever it sees first.

3. Decide who owns the numbers

   "Next unused number" is a race if two agents file at once. With one writer it is fine. With several, give the numbering to a script, or accept an occasional collision and renumber by hand.

What Agency does with the same files

Agency is a free, open-source desktop app for macOS and Linux that runs coding agents each in its own git worktree. Its issue board is an index over these files: the files are the tracker, and editing one by hand or from an agent updates the board. It adds three things.

It moves the status for you

When an issue is linked to a run, Agency changes status: at each step, always forward and never into or out of cancelled:

An issue you already set to done stays done when a later run merges, and one you cancelled stays cancelled.

It tells the agent how to file

Each run gets the absolute path of the tracker and the format, as a generated skill named agency-issues and, for Claude Code, a rules file at .claude/rules/agency-issues.md in the run's worktree (excluded from git so it never appears in a diff). The rules file says the folder is in the project's checkout and not in the worktree, that it is untracked, and to read the folder's README.md before filing a follow-up, commenting or changing a status. The wording also says that a bare "issue" means this tracker, because a run once filed an issue in a hosted tracker whose tools were in its context.

So a follow-up is one new file. An agent finishing AGE-260 and spotting a loose end writes the next free number, say AGE-301.md, without a uid:

---
key: AGE-301
status: todo
priority: 2
created: 2026-10-08T09:41:00Z
updated: 2026-10-08T09:41:00Z
links: AGE-260
---
# Handle an empty issues folder in the board

Found while working AGE-260: ...

Agency picks the file up, writes the uid in, and the issue appears on the board.

It can sync the folder without committing it

See the next section.

Is it versioned next to the code?

Not in Agency's case, and it is worth being plain about it. Agency's .agency/issues/ is untracked by git. There is one copy, in the project's own checkout, and every agent worktree reads and edits that same copy by absolute path. An edit takes effect when it is written; nothing is committed or merged.

Agency used to track the files. It stopped because the app rewrites issue state in the main checkout on every dispatch and every merge, which kept that checkout permanently dirty (a merge refuses to start on a dirty checkout) and put the same frontmatter lines on both sides of every agent merge. A project that already tracked them gets a one-time commit, "Stop tracking issue files", and the files stay on disk.

What is true instead:

• The files are plain markdown on your disk. You can back them up, grep them, or commit them yourself if you accept the dirty-checkout cost.
• You do not get git log or git blame on an issue through the project's branches.
• Moving them between machines or teammates is a setting. Agency can sync the whole folder over a git ref of its own, refs/agency/issues, which is never checked out and never appears on a branch or in a diff. Syncing is configured per project, and the automatic trigger is opt-in per machine; otherwise you press Sync.

If versioned history in the project's own branches is what you want, the by-hand setup above gives you that: track the folder, and keep one writer at a time.

Who should not use it

Teams that need cross-project reporting, assignees, notifications, an audit trail or a public form for customers to file bugs are better served by a hosted tracker. Agency's tracker is a file folder with a board on top, built for the person dispatching agents. Agency also runs on macOS and Linux only; on Windows or an Intel Mac, use the by-hand setup.

Questions

Can an agent edit an issue while I have it open in the app?

Yes. The board follows the files, and a change on disk shows up there. The folder's rule is that an edit takes effect as soon as it is written.

What stops an agent breaking the format?

The frontmatter is parsed strictly: a malformed file is skipped, not guessed at. That is why the agent is handed the format up front. Unknown frontmatter keys are kept as they are when the app rewrites a file.

Do the agents have to be Claude Code?

No. The format needs only file access. The generated rules file is a Claude Code mechanism, so with another agent you point it at the folder yourself, as in the by-hand steps.

For running the agents themselves, see how to run coding agents in parallel.