Tasks as Code: Move Your Tickets into the Repository
j / k
|
Down or up a comment |
h / l
|
Previous or next link |
?
|
This help |
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.
I have never seen this. Most of the time clients don't know what they really want.
"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..."
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 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.
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.
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
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
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.
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.
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 feel true anymore
But counterpoint, an AI / machines can talk to Jira and other ticket management systems just fine, they have REST APIs and MCP servers nowadays.
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`.
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.
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?
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
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)
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.
You should think about what your history represents. Just move the task manager somewhere else and track it there.
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
Tickets being external to source decouples the systems, parties, and lifecycles.