Tasks as Code: Storing Project Tickets as Markdown in Git for AI Agents

An article on typemill.net, picked up on the Hacker News front page, argues for a practice it calls "Tasks as Code": storing development tickets as Markdown files under Git version control, right next to the code, so AI coding agents can read requirements, plan work and record results without anything being exported from Jira.

From Docs as Code to Tasks as Code

The piece starts from how agents actually operate: the repository is their source of truth, yet most teams still track requirements in external tools such as Jira or Redmine. Documentation has already crossed that divide. The Docs as Code practice moved it from dedicated software into Markdown folders inside the repository, where an agent can read the docs, change the code and refresh the documentation in a single pass.

The author applies the same logic to tickets. Stored as Markdown, a task becomes something an agent consumes directly: it reads the requirement, plans against it and writes its results back into the same file, while Git versions the task's history alongside the history of the software.

The idea overlaps with Spec-Driven Development, which captures intended behavior in Markdown specifications before an agent implements it and is often supported by tooling such as Spec Kit. The author's starting point is deliberately leaner: treat the task file itself as the specification, which requires nothing beyond Git and an agent. How much detail a file needs depends on the job — a small maintenance fix may take a line or two, while a complex feature calls for acceptance criteria, technical decisions, dependencies and testing requirements.

A five-step workflow with a human gate

The proposed cycle keeps a developer in the loop at a fixed point:

1. Describe the task in a short Markdown file.
2. The agent reads it and examines the relevant code and documentation.
3. The agent writes an implementation plan, including the changes it intends to make, into the file.
4. A developer reviews the plan and approves or corrects it.
5. The agent implements the change, updates documentation where needed and appends an implementation report to the task file.

Because description, plan and report stay in one file, a reviewer can compare what was asked, what was proposed and what was actually done. The approval step is the control mechanism: the agent never runs straight from requirement to implementation.

Three repositories, one workspace

The author's own setup splits content across three Git repositories — code, documentation and tasks. The separation is deliberate: documentation may be public, while tasks can hold sensitive material such as unfinished security fixes, internal planning or unannounced features, and separate repositories allow independent access control.

Locally, the documentation and task repositories are cloned into folders inside the code repository and excluded through .gitignore, so each keeps its own history and can be pushed independently. A local assistant such as Claude Code or OpenCode then sees everything in one place. Referencing the task filename in a commit ties an implementation back to its requirement, and grouping tasks into release folders lets an agent draft changelogs and release notes from completed tasks and the Git history.

A browser layer on top of Git

According to the article, Git plus an agent is enough to run the workflow, but a browser interface can serve people who do not live in a terminal. The author uses Typemill, a flat-file CMS that synchronizes with Git repositories, so product owners and technical writers can browse and edit tasks and documentation without touching the command line. The same files end up reachable three ways — the IDE for developers and agents, GitHub for repository-level review, and the browser for content work — while Git remains responsible for history and synchronization. The guiding principle is that the interface is a convenience layer; the files stay portable and open to other tools.

Why it matters

If coding agents become the primary implementers, keeping requirements in a system they cannot read becomes a bottleneck. Moving tickets into the repository gives agents and human reviewers a single, versioned source of truth, and the explicit approval step preserves oversight of what ships. The shift also raises a question the article leaves open: which features of conventional ticket systems — assignments, comments, kanban boards, sprints — still matter when agents do most of the work. The properties the author would look for in whatever comes next are Git-native storage, documentation and tasks in one place, plain Markdown files, self-hosting, and provider-agnostic AI integration rather than lock-in to a single service.