Client wrote down what they wanted, programmers translated it to code, testers validated that against what clients had written down.
Now we have tickets, where BA's (but most of the time developers, really) write down the lore that is told in numerous meetings.
Tickets are supposed to be ephemeral but never really are, that's why we keep some of the lore in Wikis. Except Wikis are good for text, not so good for everything else, that's why the lore spreads to Figma, Excalidraw and Google Sheets (if you are lucky, xls documents on Sharepoint if you are not).
Now we start coding. Some of the lore get's solidified into code, which is good, some turns into
tests which is good too, if you are lucky some turns into formal spec a tool can check.
But, there is always something left that gets spread evenly - more or less - across regular comment, doc comments, commit messages and various md files, most notoriously the README.md.
Which brings me to user documentation which again is often spread over the whole oeuvre of documents and systems we mentioned. Not to mention the confusion of most documentation about its intended target group. Is it user documentation for the enduser, really? Rarely!
Oh, and then the CHANGELOG that really wants to be release notes, but isn't, at least not entirely. Which is generated automatically, but isn't, at least not entirely.
Finally comes QA (but most of the time developers, really) but it doesn't have anything to validate against, so all they do is compare the faint memory of the lore they had heard in numerous meetings against what they have written down themselves in numerous places and are mostly content with the results most of the time.
Yeah, when I used to work with a company that religiously followed ticketing systems, it was always developers being forced to larp as the user. All to satisfy the "scrum master", as far as I could tell, because nobody else cared about the larp.
"As a user, I want a damn fine software product that just works, and I wish I didn't have to go through 10 layers of indirection to communicate that to the devs..."
That is often said and there is truth to it, but not universal truth.
I worked with many clients that knew exactly what they wanted and (very importantly) could write it down in a way that they
could validate. That is often not the perfect spec from an implementation point of view but by and large a solid aporoach.
I'm curious in what is the value of this kind of solution. Having run my own software factory for just a week or two, I'm at well over 1000 agent jobs (; a more flexible variant of what a swimlane on a scrum board represents). If I did a year of having the factory running, I would end up with 10~50K tickets across my repo's, then what? Do you keep them forever?
I don't follow what the value is in putting all that in a Git repo, let alone putting everything through a cycle of git/commit/push. The source of truth is the code, so if you're capturing this for additional context about why things were built, then you may as well follow the path of Entire; former GitHub CEO's company, and record the entire agent session to get the full context.
I assume with 1000 agent jobs you mean completed jobs, not jobs running in parallel.
My solution for keeping the historical context of my projects: In docs/plan/, I have plans currently being executed. They get deleted when the work is done, and their contents gets folded into the permanent documentation in docs/.
I have the rule for the agents to put into the long-living documentation only that which is
1. not obvious from the source code (surprisingly much is obvious for agents),
2. information that an experienced engineer would not to rebuild the project (ignoring if it would look different).
Your 1000 changes in a few weeks matches the order of magnitude of changes that I did in a recent project of mine. It's a tool for managing agents, so a bit of a circular example, but anyway, if you want to take a look at the layout and CLAUDE.md instructions, it's open source: https://github.com/sadilek/obeya
I used to use this approach as well for managing many agents and myself. I do think the bloat problem is real as well as the need to handle multiple disjoint workstreams.
I built an issue tracker that persists issues as code, which you can run in a separate, linked repo, so you don't need to litter your code repo. If you do run it the same repo it puts it in a state branch, so it isn't really in the way.
One benefit of persisting issues as code is traceability of intent and keeping track of vision drift. Epiq enables this via time travel, so you can trace the board evolution by going back in time, filtering for specific sessions, etc.
This is a milestone on the journey for sure. If people could jump all the way to the end right into Software Factory Mode, they would. But people must practice the skill to get there. Part of that practice for me was tasks within the repository.
It's a way to share the context between team members and agents before it is built. You can refine it and transform it as you adjust it. I do the same thing now, even with a software factory, at an epic/initiative level. The only difference is the altitude at which we operate.
There is also something to say about having git history that shows the tasks change from scaffold -> refinement -> pristine. Frontier agents can see how the human in the loop operated during that period and translate it into human-on-the-loop policy.
Yep, this isn't a great solution for software factories.
As I see it - you need to track spec (a declarative process) and also tasks/progress (an imperative process). You do need to manage blockers so tasks should largely be a dependent graph.
There's also a third thing which emerges - which is "design decisions along the way". I do actually keep this in the repo as well, but I'm not sure this is correct.
Beads combines all three, which I'm not sure is correct, but seems quite brilliant.
This doesn’t work in an org with stakeholders that don’t have access to the code base, I.e. most of the other company. You still need tickets, a way for stakeholders to follow, update, etc. those tickets, and a way to prioritize the tasks those tickets represent.
Totally agree that stakeholders need access, but I think that’s solvable with an interface layer on top of the repo rather than a reason to avoid the workflow.
While I understand the appeal of having local files that agents can read, I think the best way to do it might be pulling the needed files from a database.
By its nature, tasks are linked in relationships of parenthood and sequence, so databases are naturally suited for storage. Plus, they need ownership relations.
So, something like Jira but please oh god not Jira, where you can pull a subset of the DB (for example a project) locally and have some script generate the needed files (requirements) from what would be a Jira description.
Counterpoint, many updates would also cause many commits just for keeping tasks updated, adding noise to the project history.
Nothing stopping people from keeping tasks in a separate repository, of course - this would also make it simpler to just allow commits straight to `main`.
Just shooting from the hip, I don’t see this scaling super well. As the number of tickets grows you’ll need some way to efficiently track WIP, filter tickets by status, etc. Jamming it all into LLM context won’t do, and relying on the agent harness to automatically sort it out will be unreliable.
So you’ll eventually want a more formal way to track and query everything, and to route the coding agents through that API to ensure consistency and reliability. At which point you’ve basically just reinvented the ticketing system that you originally sought to eliminate. Only it might still be flaky because every source control branch introduces a secondary source of truth for ticket status.
For a multi-dev team, I tried it and ended up migrating to GitHub issues: They are easily queryable/filterable from the cli, can be attached to milestones, and automatically closed by attaching a PR to it. No need for expensive mcps, just the github cli tool.
When someone sells hammers, they want you to hammer screws. Typemill is a document product and naturally, they want you to use that. It looks very polished and nice though, shame not packaged for distro though.
That's true, but it might also be the case that they think this is a good way to work and that's why they built the product in the first place. (I don't agree, though, I think tasks are more suited for DB storage).
Typemill is open source with some paid plugins, I totally agree that a Markdown CMS is not the right solution, but it is an easy way to experiment with new workflows like this. I guess we will see other software in future if tasks will make the journey into the repos.
Relational databases exist for a reason. Every effort that starts with “I really want to use this tool so let me shove a use case into it” always ends in disaster. Git has a purpose, and building an information management system is not one of them.
To start, how are you going to run queries on this bug tracker? How are you going to make sure it stays up to date for everyone at the company with sub-second latency? How are you managing access control? How do you keep the size under control over time?
I had very similar thoughts to this piece at the beginning of the year but I took a bit of a different approach with the tool I built, Kan [0]. Rather than markdown files in directories like OP went with, I went for plain json files stored in a `.kan` directory, with the primary interface being not the files themselves but the CLI and an embedded frontend which could be run with `kan serve`. Agents work really well with the CLI and the frontend provides a nice snappy UI for humans to interact with and manage their tasks in a kanban format, all offline and acting entirely on files in the repo's VCS (somewhat like Typemill).
Overall it's been a great workflow and it works great with agents, it's the main way I manage tasks with agents, I agree the 'tickets in the repo' approach works really well.
Nah. There's a manager at my company that's pushing this, and it sucks for pretty much everyone except him. I suppose it's fine if you're delegating sprint management to AI agents, but everyone except the manager is going to be using this tool to manage sprints.
These kinds of things are an EM’s wet dream. Especially an EM who knows they are not adding anything to the team but are capable of putting together a slide, mentioning “productivity reached X” without mentioning the baseline, and still being able to sell that improvement.
Tangibly related - I use Linear for ticket management and I'm in love with this. After being defiled by Jira in my $dayjob, I couldn't believe I'll find a ticket management app I would love so much I literally advertise for free.
I actually did something similar with my team a few months ago. We exported all our confluence articles and all our Jira tasks into Obsidian and then made a few simple extensions to replace the functionality we needed from them (sharing links to pages, ability to make comments on pages, creating new tasks, using bases as a way to organize our todo tasks, use git for file history), for a DevOps team of 4 it has gone very well and it has made an massive improvement for giving our AI agents up to date docs on whatever we're working on.
Yes! There are some existing projects and posts on the idea of tickets in-the-repo.
Usually the problem is that it's not very friendly for Product Folks and SMEs so I've been working on a local first, git backed project management and documentation tool (Think Jira and Confluence).
So as to not hijack this post, I won't paste a link here (not to mention it's ready for prime time yet) but send me a message if you're interested (it's open source and visible so it's not too hard to find either)
I guess the benefit would be that agents could catch future or related tasks via the codebase "greps" and could theoretically design toward the future or keep them fresh? Is that worth the obvious downside? Keeping old tasks seems like a bad idea. How do folks address stale tasks without this tight coupling? A stale task description isn't a problem for people, but agents are so literal.
"AI coding agents work best when everything they need lives in the repository" honestly not true, they work best if they have all the information up front, local filesystem is pretty cheap path to that.
Better path is an orchestration agent that composes a short spec with the slice of the details for a slice of the work. Tickets end up being too verbose as people try to cover every potential aspect / use LLMs to generate them.
I wanted to implement a similar tool in 2011, Ditz IIRC. The Redmine issue tracker was too finicky, it promised using a self-hosted and reliable repo as the source of truth and Netbeans as its frontend. I implemented Mercurial VCS and designated one machine as remote (a hghub) for ssh cloning and web interface, we didnt have any pesky subscriptions.
It's a very bad idea! ticket managers do more than just store ticket text! also duplicating a ticket text in the repo it's just wrong.. then why don't you put your db data into the repo too ?
Just use BDD. Gherkin has existed for a long time. Sync the features between the tracker and repo, and use the tools to ensure features are accurately implemented. Been doing wonders for me.
A lot of the tools we have to use are designed for meat proxy's (JIRA etc...) yes, you can allow the agents access to the task repo via api or MCP, but at the end of the day, the tool starts to become the bottleneck, Iike the idea of putting the tasks and issues into git, it means all info for why a change was made is in one place, accessable forever, just need to expand agents to non-software dev world.
I was doing something like this manually, but for my own solo-dev projects. I wonder if your opinion is still the same for this case. I totally understand this is not really working when working on a team, but for planning -> delegating to LLMs this works really well for me
Better to keep tasks in a separate repo imo, or at least make sure they aren't committed.
I always follow one rule: looking at the git history should tell me what each change did, and the commit message alone should be enough to understand what actually changed.
If you mix tasks with code changes, you will just confuse your future self.
Moreover, you can set up something like beads to handle task delegation and status updates for your agents.
Terrible idea because these two artifacts (ticket and code) have different lifecycles, different participants, different rates of churn, different needs from a reporting perspective, and different rules/workflows.
Tickets being external to source decouples the systems, parties, and lifecycles.
Life used to be simple.
Client wrote down what they wanted, programmers translated it to code, testers validated that against what clients had written down.
Now we have tickets, where BA's (but most of the time developers, really) write down the lore that is told in numerous meetings.
Tickets are supposed to be ephemeral but never really are, that's why we keep some of the lore in Wikis. Except Wikis are good for text, not so good for everything else, that's why the lore spreads to Figma, Excalidraw and Google Sheets (if you are lucky, xls documents on Sharepoint if you are not).
Now we start coding. Some of the lore get's solidified into code, which is good, some turns into tests which is good too, if you are lucky some turns into formal spec a tool can check.
But, there is always something left that gets spread evenly - more or less - across regular comment, doc comments, commit messages and various md files, most notoriously the README.md.
Which brings me to user documentation which again is often spread over the whole oeuvre of documents and systems we mentioned. Not to mention the confusion of most documentation about its intended target group. Is it user documentation for the enduser, really? Rarely!
Oh, and then the CHANGELOG that really wants to be release notes, but isn't, at least not entirely. Which is generated automatically, but isn't, at least not entirely.
Finally comes QA (but most of the time developers, really) but it doesn't have anything to validate against, so all they do is compare the faint memory of the lore they had heard in numerous meetings against what they have written down themselves in numerous places and are mostly content with the results most of the time.
> Client wrote down what they wanted
I have never seen this. Most of the time clients don't know what they really want.
Yeah, when I used to work with a company that religiously followed ticketing systems, it was always developers being forced to larp as the user. All to satisfy the "scrum master", as far as I could tell, because nobody else cared about the larp.
"As a user, I want a damn fine software product that just works, and I wish I didn't have to go through 10 layers of indirection to communicate that to the devs..."
That is often said and there is truth to it, but not universal truth.
I worked with many clients that knew exactly what they wanted and (very importantly) could write it down in a way that they could validate. That is often not the perfect spec from an implementation point of view but by and large a solid aporoach.
> Most of the time clients don't know what they really want
I know this happens but it shouldn't. If the client doesn't know what they want then they shouldn't be wasting money on developers.
And then you get enterprise search to tie them all. Slap an MCP on it and all your tools can talk to each other again.
> The gods confound the man who first found out how to distinguish hours!
I'm curious in what is the value of this kind of solution. Having run my own software factory for just a week or two, I'm at well over 1000 agent jobs (; a more flexible variant of what a swimlane on a scrum board represents). If I did a year of having the factory running, I would end up with 10~50K tickets across my repo's, then what? Do you keep them forever?
I don't follow what the value is in putting all that in a Git repo, let alone putting everything through a cycle of git/commit/push. The source of truth is the code, so if you're capturing this for additional context about why things were built, then you may as well follow the path of Entire; former GitHub CEO's company, and record the entire agent session to get the full context.
I assume with 1000 agent jobs you mean completed jobs, not jobs running in parallel.
My solution for keeping the historical context of my projects: In docs/plan/, I have plans currently being executed. They get deleted when the work is done, and their contents gets folded into the permanent documentation in docs/.
I have the rule for the agents to put into the long-living documentation only that which is
1. not obvious from the source code (surprisingly much is obvious for agents), 2. information that an experienced engineer would not to rebuild the project (ignoring if it would look different).
Your 1000 changes in a few weeks matches the order of magnitude of changes that I did in a recent project of mine. It's a tool for managing agents, so a bit of a circular example, but anyway, if you want to take a look at the layout and CLAUDE.md instructions, it's open source: https://github.com/sadilek/obeya
I used to use this approach as well for managing many agents and myself. I do think the bloat problem is real as well as the need to handle multiple disjoint workstreams.
My solution was to put tasks and their dependencies in a sqlite db. https://github.com/mhalstrom/maximizepm take a look if you're interested
Why not use Linear/Plane/Paperclip?
I built an issue tracker that persists issues as code, which you can run in a separate, linked repo, so you don't need to litter your code repo. If you do run it the same repo it puts it in a state branch, so it isn't really in the way.
https://ljtn.github.io/epiq/
One benefit of persisting issues as code is traceability of intent and keeping track of vision drift. Epiq enables this via time travel, so you can trace the board evolution by going back in time, filtering for specific sessions, etc.
I like it, especially the name :)
This is a milestone on the journey for sure. If people could jump all the way to the end right into Software Factory Mode, they would. But people must practice the skill to get there. Part of that practice for me was tasks within the repository.
It's a way to share the context between team members and agents before it is built. You can refine it and transform it as you adjust it. I do the same thing now, even with a software factory, at an epic/initiative level. The only difference is the altitude at which we operate.
There is also something to say about having git history that shows the tasks change from scaffold -> refinement -> pristine. Frontier agents can see how the human in the loop operated during that period and translate it into human-on-the-loop policy.
Yep, this isn't a great solution for software factories.
As I see it - you need to track spec (a declarative process) and also tasks/progress (an imperative process). You do need to manage blockers so tasks should largely be a dependent graph.
There's also a third thing which emerges - which is "design decisions along the way". I do actually keep this in the repo as well, but I'm not sure this is correct.
Beads combines all three, which I'm not sure is correct, but seems quite brilliant.
But someone still has to write the requirements? I am not familiar with software factories like this to be honest...
>The source of truth is the code
this doesn't feel true anymore
This doesn’t work in an org with stakeholders that don’t have access to the code base, I.e. most of the other company. You still need tickets, a way for stakeholders to follow, update, etc. those tickets, and a way to prioritize the tasks those tickets represent.
Nothing a front-end can't solve. To the end user it doesn't matter if data is stored in a database or git, as long as it just works.
But counterpoint, an AI / machines can talk to Jira and other ticket management systems just fine, they have REST APIs and MCP servers nowadays.
[flagged]
Totally agree that stakeholders need access, but I think that’s solvable with an interface layer on top of the repo rather than a reason to avoid the workflow.
Or the other way around. An API for the robot to read tickets
[dead]
While I understand the appeal of having local files that agents can read, I think the best way to do it might be pulling the needed files from a database. By its nature, tasks are linked in relationships of parenthood and sequence, so databases are naturally suited for storage. Plus, they need ownership relations. So, something like Jira but please oh god not Jira, where you can pull a subset of the DB (for example a project) locally and have some script generate the needed files (requirements) from what would be a Jira description.
Tickets change faster than code. Having to create a PR to update a ticket sounds like a bureaucratic nightmare.
It works great as a solo developer. I've been doing the same thing for the past several months. I couldn't imagine doing it with a team.
This is a problem of requiring PRs for everything, not of putting tasks in the repo.
Counterpoint, many updates would also cause many commits just for keeping tasks updated, adding noise to the project history.
Nothing stopping people from keeping tasks in a separate repository, of course - this would also make it simpler to just allow commits straight to `main`.
PRs or not, git workflows are always going to be many orders of magnitude slower than simple database reads/writes.
Then you go the nanoservice route, with double the repos!
Just shooting from the hip, I don’t see this scaling super well. As the number of tickets grows you’ll need some way to efficiently track WIP, filter tickets by status, etc. Jamming it all into LLM context won’t do, and relying on the agent harness to automatically sort it out will be unreliable.
So you’ll eventually want a more formal way to track and query everything, and to route the coding agents through that API to ensure consistency and reliability. At which point you’ve basically just reinvented the ticketing system that you originally sought to eliminate. Only it might still be flaky because every source control branch introduces a secondary source of truth for ticket status.
For a solo dev, this solution works great.
For a multi-dev team, I tried it and ended up migrating to GitHub issues: They are easily queryable/filterable from the cli, can be attached to milestones, and automatically closed by attaching a PR to it. No need for expensive mcps, just the github cli tool.
[flagged]
When someone sells hammers, they want you to hammer screws. Typemill is a document product and naturally, they want you to use that. It looks very polished and nice though, shame not packaged for distro though.
That's true, but it might also be the case that they think this is a good way to work and that's why they built the product in the first place. (I don't agree, though, I think tasks are more suited for DB storage).
Typemill is open source with some paid plugins, I totally agree that a Markdown CMS is not the right solution, but it is an easy way to experiment with new workflows like this. I guess we will see other software in future if tasks will make the journey into the repos.
Relational databases exist for a reason. Every effort that starts with “I really want to use this tool so let me shove a use case into it” always ends in disaster. Git has a purpose, and building an information management system is not one of them.
To start, how are you going to run queries on this bug tracker? How are you going to make sure it stays up to date for everyone at the company with sub-second latency? How are you managing access control? How do you keep the size under control over time?
I had very similar thoughts to this piece at the beginning of the year but I took a bit of a different approach with the tool I built, Kan [0]. Rather than markdown files in directories like OP went with, I went for plain json files stored in a `.kan` directory, with the primary interface being not the files themselves but the CLI and an embedded frontend which could be run with `kan serve`. Agents work really well with the CLI and the frontend provides a nice snappy UI for humans to interact with and manage their tasks in a kanban format, all offline and acting entirely on files in the repo's VCS (somewhat like Typemill).
Overall it's been a great workflow and it works great with agents, it's the main way I manage tasks with agents, I agree the 'tickets in the repo' approach works really well.
[0] https://github.com/amterp/kan
Nah. There's a manager at my company that's pushing this, and it sucks for pretty much everyone except him. I suppose it's fine if you're delegating sprint management to AI agents, but everyone except the manager is going to be using this tool to manage sprints.
Funny that you and vhodges say basically the same thing, mirrored. :)
[dead]
These kinds of things are an EM’s wet dream. Especially an EM who knows they are not adding anything to the team but are capable of putting together a slide, mentioning “productivity reached X” without mentioning the baseline, and still being able to sell that improvement.
Tangibly related - I use Linear for ticket management and I'm in love with this. After being defiled by Jira in my $dayjob, I couldn't believe I'll find a ticket management app I would love so much I literally advertise for free.
I actually did something similar with my team a few months ago. We exported all our confluence articles and all our Jira tasks into Obsidian and then made a few simple extensions to replace the functionality we needed from them (sharing links to pages, ability to make comments on pages, creating new tasks, using bases as a way to organize our todo tasks, use git for file history), for a DevOps team of 4 it has gone very well and it has made an massive improvement for giving our AI agents up to date docs on whatever we're working on.
Yes! There are some existing projects and posts on the idea of tickets in-the-repo.
Usually the problem is that it's not very friendly for Product Folks and SMEs so I've been working on a local first, git backed project management and documentation tool (Think Jira and Confluence).
So as to not hijack this post, I won't paste a link here (not to mention it's ready for prime time yet) but send me a message if you're interested (it's open source and visible so it's not too hard to find either)
[dead]
I guess the benefit would be that agents could catch future or related tasks via the codebase "greps" and could theoretically design toward the future or keep them fresh? Is that worth the obvious downside? Keeping old tasks seems like a bad idea. How do folks address stale tasks without this tight coupling? A stale task description isn't a problem for people, but agents are so literal.
"AI coding agents work best when everything they need lives in the repository" honestly not true, they work best if they have all the information up front, local filesystem is pretty cheap path to that.
Better path is an orchestration agent that composes a short spec with the slice of the details for a slice of the work. Tickets end up being too verbose as people try to cover every potential aspect / use LLMs to generate them.
I wanted to implement a similar tool in 2011, Ditz IIRC. The Redmine issue tracker was too finicky, it promised using a self-hosted and reliable repo as the source of truth and Netbeans as its frontend. I implemented Mercurial VCS and designated one machine as remote (a hghub) for ssh cloning and web interface, we didnt have any pesky subscriptions.
It's a very bad idea! ticket managers do more than just store ticket text! also duplicating a ticket text in the repo it's just wrong.. then why don't you put your db data into the repo too ?
Just use BDD. Gherkin has existed for a long time. Sync the features between the tracker and repo, and use the tools to ensure features are accurately implemented. Been doing wonders for me.
A lot of the tools we have to use are designed for meat proxy's (JIRA etc...) yes, you can allow the agents access to the task repo via api or MCP, but at the end of the day, the tool starts to become the bottleneck, Iike the idea of putting the tasks and issues into git, it means all info for why a change was made is in one place, accessable forever, just need to expand agents to non-software dev world.
Nope, you're breaking Git history with that.
You should think about what your history represents. Just move the task manager somewhere else and track it there.
I was doing something like this manually, but for my own solo-dev projects. I wonder if your opinion is still the same for this case. I totally understand this is not really working when working on a team, but for planning -> delegating to LLMs this works really well for me
Better to keep tasks in a separate repo imo, or at least make sure they aren't committed.
I always follow one rule: looking at the git history should tell me what each change did, and the commit message alone should be enough to understand what actually changed.
If you mix tasks with code changes, you will just confuse your future self.
Moreover, you can set up something like beads to handle task delegation and status updates for your agents.
https://github.com/gastownhall/beads
I have a rest API client for linear and the robot can read the ticket this way ? And comments made by Products and Design folks.
I kind of fear this would cause agents to get lost in previous outdated context, ultimately wasting time and tokens.
I'm not a beads user - but it rather brilliantly solves a lot of problems in this space
Terrible idea because these two artifacts (ticket and code) have different lifecycles, different participants, different rates of churn, different needs from a reporting perspective, and different rules/workflows.
Tickets being external to source decouples the systems, parties, and lifecycles.
[flagged]
[flagged]
[flagged]
[flagged]
[flagged]
[flagged]
[flagged]
[flagged]
[flagged]