I wrote my last ticket

Ticket systems have served software teams well for decades. But as AI coding agents became part of my daily workflow, I started to question whether I still needed a separate system to manage my tasks. So I stopped writing tickets. Now I write tasks as Markdown files and manage them with Git, right next to my code and my docs.

Docs like Code

Documentation made this journey some time ago. Today, it often lives in a /docs folder inside the code repository. This is known as docs-like-code approach, and it is gaining even more traction with the rise of AI agents. Agents can read the docs, understand the code, make changes, and update the documentation as part of the same workflow.

Tasks like Code

For my software project Typemill, I applied the same idea to tasks:

1. Each task is a Markdown file with a short description of what needs to be done.
2. The agent reads the task and analyzes the code.
3. It adds an implementation plan to the same file.
4. I review the plan and give the go-ahead.
5. The agent implements the changes and appends an implementation report.

The task description, implementation plan, and report stay together in one file in the task repository. I can look back at what I wanted, how the change was planned, and what the agent actually did. The review step in the middle keeps me in control.

I later learned that this workflow shares ideas with Spec-Driven Development (SDD), where specifications define what the software should do before an agent implements it. My task files are simpler than formal specifications, but they follow the same basic idea: describe the intended change, agree on a plan, and then let the agent implement it.

My Setup

Many projects keep their documentation in a docs folder inside the code repository. I prefer to maintain documentation in a separate repository, including developer docs, user guides, and admin manuals. I clone that repository locally into the docs folder of my code repository.

I initially put my tasks in a /docs/tasks folder. But that created a problem: It expose unfinished security-related work, internal planning, or features that had not yet been announced.

So I moved the tasks into a separate, private Git repository. I clone that repository locally into a /tasks folder inside my code repository, just as I do with the documentation. Both folders are listed in the code repository's .gitignore file, so the code repository does not track their contents. Each cloned repository retains its own Git history and can be committed, pushed, and synchronized independently.

My local directory structure looks like this:

/repository
  /src
  /tests
  /docs                 # Separate documentation repository
    /user-guides
    /admin-manuals
    /developer-docs
  /tasks                # Separate private task repository
    /release-123
      task-551-something-descriptive.md
      task-552-something-descriptive.md

This gives me a convenient local workspace where the code, documentation, and tasks are all available to the agent, without mixing their Git histories or access permissions. I can keep the code repository public, the documentation repository public or private as needed, and the task repository private.

When the agent implements a task, it can update the documentation as part of the same workflow. When all tasks of a release are finished, the agent can use completed tasks and Git history to draft the changelog and release notes in the appropriate release folder. I can also reference the filename of the task in my Git commit to trace the relationship between the task and the code changes.

Adding an Interface

So far, this setup needs nothing but Git repositories and a coding agent. But if you want to go further, you can add an interface for the documentation and tasks.

I use my Markdown-based CMS that synchronizes the documentation and tasks with Git. Typemill can connect to multiple Git repositories, so I created a separate project for tasks in my Typemill instance next to my documentation. This lets me manage the documentation and private tasks through the same interface, even though they live in separate repositories.

The tasks:

The docs:

This setup gives me three ways to work with the same files:

• In my IDE, while I develop.
• On GitHub, although I rarely use it for editing.
• In the browser, through the CMS running on my own server.

Where This Could Go

I think the core idea is right: tasks should be files managed through Git and connected to the code and documentation. If an agent reads the task, writes the plan, changes the code, and updates the docs, there is little reason to keep the task in a closed database in a separate ticket system.

That raises a question: what kind of software and interface does this workflow need, and which ticket features do we still want, such as assignments, comments, collaboration, boards, or an overview of everything in progress?

A Markdown CMS is certainly not the final answer, but it is a simple and practical way to test these ideas and explore what such an interface could look like. In my view, an interface should follow a few principles:

• Repository-native: tasks and specifications are readable files managed through Git and connected to the code and documentation.
• Docs and tasks together: one interface for documentation and task management.
• Connected to Git: changes can be versioned, reviewed, and synchronized.
• File-based: Markdown stays readable, portable, and independent of a specific platform.
• Self-hosted: full control over your data, privacy, and infrastructure.
• Open to any AI service: no lock-in to a proprietary AI tool.

I wrote my last ticket. Now let's find out what comes next.