Git even more things done
Almost half a year ago I wrote about my little development helper, githingsdone. It has been my daily driver for development work since then and also subject to massive changes and refactorings. Specifically because it was built on Pi, using my company-provided Claude Max subscription, but Anthropic killed that, so I needed a different solution. On our family vacation, I worked on it during my relaxed morning coffees in front of our tent, talking to Claude Code Web via Wispr Flow. This was a wild experience. After two weeks I came back to a largely working but completely different product 🤯
But recently the changes have become smaller and the surface more stable. I feel it's time to give an update and maybe get more interested eyes on it.
Core concept#
At the fundamental level gtd is a workflow orchestrator, driven by the git
commit history. The gtd next command derives the next action based on the last
commit and the current changeset and emits it to be consumed by whoever is
driving the process: Claude, a bash loop or your unpaid intern. When the changes
are done, gtd land is there to persist them to history so a new gtd next can
proceed with the next step.
By design, both commands never mutate anything — they only provide instructions for the next thing to do. Those instructions have three primary types:
Technically a human could just manually run the commands and follow all steps they emit. Not efficient, but possible. That is the design principle at work. To make things faster, one should build[1] a small loop around it:
while :; do
case "$(gtd next --json=kind)" in
# A deterministic script to execute.
script) gtd next --json=content | sh ;;
# A prompt for an agent.
prompt) gtd next | claude -p --dangerously-skip-permissions ;;
# A message printed for a human. Stop the loop.
message) gtd next; exit 0 ;;
# Nothing left to do, abort.
stalled) gtd next >&2; exit 1 ;;
esac
gtd land --json=script | sh
doneOver many iterations I converged to this design, trying to make it as unix as
I could. There is a gtd install command that will print all necessary
information for your agent to build this loop, with added bells and whistles. I
myself switched my implementation of this from terminal-notifier to cmux to
my current driver herdr. And I am not naive enough to think that nothing new
is going to catch my fancy next week. It should also be possible to run this
inside a coding agent using stop-hooks, but I did not try that yet.
The built-in workflow#
Enough fundamentals. Over the last three years I have done a lot of work with
coding agents and built a rhythm of planning, implementing, testing and
reviewing. The initial magic has faded and the work bores me enough that I
want it to go away. gtd ships with a default workflow that codifies the whole
flow and puts it on autopilot.
1. Requirements#
It simply starts with me dropping anything into the repository:
When I start the loop, it will first of all run the test suite to make sure
everything is green before any changes. Then it will commit my input verbatim,
then revert it and consolidate it in a .gtd/REQUIREMENTS.md. It looks at the
changes from a consumer perspective and fleshes them out. It will leave "open
questions" in the requirements file that I have to address, very similar to
Claude's planning mode or the grill-me skill by Matt Pocock. I can also add
new content anywhere else in the requirements document.
When I run the loop again, any changes to the requirements document will be factored in. When there are no more changes and all questions are answered, it will automatically proceed to the next phase.
2. Architecture#
This is very similar to the "Requirements" phase, but it will look at the
requirements through a technical lens and build a plan for how to meet them. The
output document is stored in .gtd/ARCHITECTURE.md and again, I will be
prompted to answer open questions and am allowed to leave any comments.
3. Decomposition#
Based on the agreed architecture, the work will be split into sensible
sub-packages that can be tackled one at a time. Their specification files are
stored in a .gtd/packages directory, but I do not really look at them. The
agent tries to split packages by files touched and separate concerns. Also each
package has to be able to deliver a green test suite.
4. Implementation loop#
The process will guide the agent through the packages one by one[2]. For each package it will apply a sub-workflow.
5. Review#
After the full implementation is done and all tests are green, the last step
will prepare a .gtd/REVIEW.md file for me. It contains all changed hunks,
grouped into semantic concerns to make reviews easier. Each review section and
hunk has a brief explanation of what it is supposed to do. This works as a
checklist for me, and I can leave comments within the .gtd/REVIEW.md file as
well as right in code to provide feedback. If I do so, all my feedback is
consolidated again, and the process goes back up into the "Requirements" phase,
with my comments as input. Otherwise it concludes.
That's the whole workflow. If you dare, you can run gtd visualize to see it in
detail. Also, the whole workflow is just configuration and can be adapted to any
project or requirement. But that story is not yet fully developed and requires
some more polish.
Additional helpers#
Aside from next and land, gtd has a couple more noteworthy commands.
gtd summary prints a prompt that tasks the agent to look at the commit history
since the process started and create a summary of the intent and important
decisions that were taken. gtd leaves quite a messy git history that is not
intended for human eyes. I use the summary for pull request descriptions that
are then squash-merged.
gtd lsp starts a local LSP server for the project[3]. It latches onto the
internal files (requirements, architecture, review ...) and provides symbols and
quick actions to jump to open questions and pick answers.
gtd next --entry ... allows me to start the process at a certain point. I use
this to start right at the fix-loop if the codebase is currently broken or at
the human review step when I get a colleague's pull request to review.
gtd review emits the commit hash of changes since the last review. This can
be used with difftools like hunk. I have set up a little gtd-review script
instead that switches the current git head, so neovim shows the changes
nicely.
gtd install prints the installation prompt, which tells your agent how to set
everything up. It will look into the system to get your favorite editor — no
judgment[4] — coding agent and shell to build out helper commands and settings
for you:
Why not use Claude's planning mode, /grill-me or superpowers?#
First of all, I like files and my editor. And I like focused bursts of work. I do not like chat interfaces that blurb walls of text at me and ping me every 45 seconds with a new question. I built my workflow here to consolidate and collect as much information as possible and then let me work through one file and leave my feedback in there.
Also, Claude is sometimes dumb about when to run tests. It only runs a subset of
tests because it doesn't feel like also running the expensive e2e suite. And the
other day, after I asked it to fix spelling errors in the README.md, it ran
the full test suite. Just to be safe. I want determinism where it counts, and
I want to be able to trust that it did its homework.
Then there is the context window problem. The state machine allows me to control exactly when the agent uses its conversation context, and when it only hands over an artifact to the next invocation. Yes, there are subagents, but then control is again not guaranteed.
Resumability is also a big factor. It becomes easy to start work on one machine and finish it on another. Without relying on cloud services. And a product manager could just go through the requirements phase themselves and then hand off to an architect.
I strongly believe that code is the ultimate source of truth, and redundant documentation doubles token consumption at best and - in most cases - leads to mistakes because it's outdated. That's why solutions like SpecKit and BMad are ruled out.
And ultimately, the workflow becomes fully portable. Should Anthropic pull another stunt à la "We make you pay extra for automation. You have to stare at our chat interface eight hours a day!", I can just swap out Claude Code for Pi with another subscription and carry on. Technically it is even possible to write the loop to use a different coding agent for certain steps. Adversarial reviews come to mind.
When not to use it?
I still use chat interfaces, but only when I don't know the task list and next steps anyway. For example exploration and research tasks or when doing quick rounds of UI feedback. That's when I want the conversational experience. Everything has its place.
Future considerations#
Right now I am using gtd full time and it does a wonderful job. I have a
couple of ideas for how it can be improved, like a UI for design processes and
better workflow configurability. But I want to know if this is interesting to
other developers and worth pursuing further. Have a look at the repository and
try it! The issues and discussions are open.