I’ve just had one of those nerdy, slightly giddy moments: realising that a single prompt plus a handful of shell scripts has quietly turned my laptop into a small AI software house.
Until now, my “AI workers” were clever but cramped. I had a Product Manager, an Architect, a Developer, and a Test Manager — each with carefully crafted prompts and clear responsibilities for my ClubHub project.
But they were effectively hot-desking in one working tree. I could only really let one of them go wild at a time before Git conflicts and context confusion started piling up.
The breakthrough was simple and obvious in hindsight:
Give every AI worker their own git worktree and branch, and wire that into the scripts and prompts.
Suddenly it feels like the next point of departure for AI workers: not just answering questions or editing a file, but managing collaborative change, at scale, between a bunch of eager little robot colleagues.
1. From Single Worker to AI Studio
The ClubHub project already has a strong “AI worker” backbone:
-
A system context that explains the architecture, domain model, CI/CD story, and worker protocols.
-
Specialised prompts for:
-
Technical Architect – reviews code, identifies technical debt, proposes architectural epics.
-
Technical Product Manager – curates the backlog, fills gaps, keeps epics and acceptance criteria coherent.
-
Test Coverage Worker – focuses purely on nudging coverage upwards on specific handlers and validation paths.
-
-
A backlog with locks in YAML front-matter so AI workers don’t stomp on the same story file.
-
A sweeper prompt whose job is to clear stale locks if a worker died or got bored.
On top of that, there is a set of shell scripts:
-
codex-developer.sh
-
codex-architect.sh
-
codex-product-manager.sh
-
codex-test-manager.sh
Each script roughly does the same pattern:
-
Resolve the repo root.
-
Source git branch helpers and task lock helpers.
-
Use the backlog to pick a high-priority, unlocked task.
-
Acquire the lock and log the activity.
-
Spin up the right prompt and launch the AI session.
So the “team” was there already: PM, Architect, Dev, Tester, Sweeper.
The bottleneck was the filesystem and Git workflow.
2. The Core Problem: Local Concurrency Without Chaos
Running multiple AI workers in parallel on the same working tree is like asking four junior developers to all SSH into the same server and “just coordinate amongst yourselves”.
You get:
-
untracked files everywhere,
-
half-applied edits,
-
and a constant background hum of “wait, what did you just change?”
Even with task locks in the backlog, the codebase itself remained a shared, mutable mess. The prompts were disciplined; the git workflow wasn’t.
What I really wanted was:
-
Per-worker isolation for experiments and edits.
-
A clean path to main once build/tests pass.
-
A protocol that AI workers can follow reliably without me hand-holding every step.
That’s exactly where git worktrees shine.
3. The New Worker Flow: One Worktree and Branch Per Task
Here is the new flow I am using now. It is what I want each worker (and script) to follow:
-
Pick and lock a task
The worker script reads the backlog, ranks tasks by priority (High > Medium > Low), checks dependencies, and acquires a lock in the story file.
It writes an entry to a task log like:
2025-12-02 11:03:23 UTC | codex-dev | A32 | started | picked from backlog
-
Create a dedicated worktree and branch
The script calls a helper (for example setup_worker_branch) that:
-
Fetches from origin.
-
Creates a branch named something like:
ai/codex-dev/A32-member-event-registrations
-
Adds a worktree at:
.worktrees/ai/codex-dev/A32-member-event-registrations
The worker’s session runs only inside that directory.
-
-
Make changes in isolation
-
The Developer worker edits Go or React files for the specific task.
-
The Architect might be in a different worktree, adjusting documentation and adding technical-debt epics under an “Architecture” epic.
-
The Product Manager could be in another worktree, reorganising an epic or adding acceptance criteria.
Each worker has their own sandboxed view of the code, connected to its own branch.
-
-
Run build and tests as a pre-merge gate
Each worker is told explicitly in its prompt and script: do not merge until build and tests pass locally.
For ClubHub, that means commands such as:
-
make test for Go services
-
npm test or lint checks for the frontend
-
and whatever pre-commit hooks I add over time
-
-
If green, commit the changes
The worker creates a conventional commit tied to the task, for example:
feat(A32): add event registrations list endpoint
These commits live on the ai/... branch inside that worker’s worktree.
-
Push and merge to main
This is the crucial part of the protocol that I want crystal clear:
-
First, push the feature branch:
git push -u origin ai/codex-dev/A32-member-event-registrations
-
Then call a helper such as merge_to_main that knows how to:
-
fetch and update main,
-
merge the ai/... branch into main,
-
push the updated main branch,
-
and optionally clean up the worktree.
-
The worker doesn’t need to know every low-level Git command. It just needs to know that “if tests pass, run the merge helper” and trust the convention.
-
-
Update the task log and unlock
On success, the worker:
-
sets the story to “done” (or the next appropriate state),
-
clears the lock,
-
and appends a final log entry.
If work is only partially complete, it can leave a note in the story and the log. The sweeper worker can later clean up any stale locks that remain.
-
That’s the loop: each AI worker has its own branch, its own directory, and a clear graduation ceremony into main.
4. Why Git Worktrees Are Perfect for AI Workers
Git worktrees are a natural fit for this kind of AI concurrency:
-
Multiple checkouts, one history
Each worktree is a separate directory with its own index and working copy, but they all share the same .git data. That makes them lightweight and fast, perfect for a “team of bots” workflow.
-
Cheap to create and destroy
A worker picks up a task and gets a worktree. When the task is done, the worktree can be removed. No heavy-weight cloning or awkward local repo juggling.
-
Natural mapping to tasks and locks
There is a simple mapping:
-
task ID
-
branch name
-
worktree path
-
lock entry in the backlog
If something goes wrong, it is easy to see: “Task A32 is locked by codex-dev, worktree is at .worktrees/ai/codex-dev/A32-member-event-registrations.”
-
-
Safer merges
Every worker starts from a fresh origin/main, and merges are gated on local tests. If two workers touch the same files, Git gives a normal merge conflict instead of silent overwrites. That’s much easier to reason about.
5. Scripts as Protocol and Prompts as Roles
The magic here is not just the prompts, but the combination of prompts plus scripts as a protocol.
Each worker script explains the contract to the AI in plain language, for example:
-
Your task is already locked and logged.
-
Always work in your own worktree. Never commit directly to main.
-
After successful build and tests, merge to main using the helper.
-
Update the task log when you are done or blocked.
Each role prompt then describes how that worker should behave inside that sandbox:
-
The Architect looks for structural issues and creates or updates architectural epics and technical debt items.
-
The Product Manager maintains the backlog structure, dependencies, and priorities.
-
The Test Coverage worker focuses purely on raising coverage on specific handlers and validation functions, following concrete success criteria.
-
The Developer implements features and fixes in the code.
Together, prompts plus scripts form a social contract for AI workers:
-
what they are allowed to touch,
-
how they prepare changes,
-
and how those changes enter the shared codebase.
6. Why This Feels Like a New Departure Point
Most conversations about AI coding focus on a simple question: can the model write good code?
I’m starting to think the more interesting question is different:
Can we organise several AI workers so they can change a real codebase together, in a safe and meaningful way?
This new workflow with git worktrees feels like a small step in that direction.
-
Multiple workers, less chaos
The Developer, Tester, Architect and Product Manager can all work at the same time, each in their own worktree and branch. They don’t trip over each other’s edits, but they still contribute to the same main branch in a controlled way.
-
Human-sized tasks, machine-sized stamina
The backlog is still written for humans: epics, stories and acceptance criteria. The AI workers just take those tasks and push them forward with a lot of patience and consistency.
-
Every change is traceable
Each piece of work is tied to a task ID, a branch name and a short log entry. If something odd appears in the code, I can follow the trail back to the worker, the branch and the task that caused it.
-
A pattern that can travel
This setup is not specific to my ClubHub project. Any repository with a backlog, some simple scripts and a bit of Git discipline can use the same structure to host its own “AI team”.
Instead of a single AI sitting in one editor window, I now have a group of coordinated workers. The worktrees and scripts give them just enough structure so that collaboration becomes possible, not chaotic.
7. How You Could Steal This Pattern ('cause I want you to)
If you want to experiment with your own AI worker studio, here’s a minimal recipe:
-
Define roles as prompts
Architect, Product Manager, Developer and Tester are a good starter set.
-
Introduce a backlog with IDs and locks
A simple backlog.md plus per-task markdown files with YAML front-matter works fine.
-
Write small shell scripts per role that
-
select a task,
-
acquire the lock,
-
create ai/<worker>/<task> branches and worktrees,
-
assemble the prompt (system context + role + task context),
-
launch your AI client.
-
-
Define a shared Git protocol
Something like: run tests, then commit, then push the branch, then merge to main via a helper script, then push main, then clean up.
-
Add a sweeper
A tiny job that walks the backlog and clears stale locks so the system cannot clog up if a worker dies halfway through.
Once that is in place, you are not just “using AI”; you are managing a small AI studio that works inside your repo, under your rules.
8. Closing Thought
Putting it all together — roles, prompts, scripts, task locks, and now git worktrees — feels like a genuine step up in how I collaborate with AI.
I’m not babysitting a single chat window anymore. I’m coordinating a team of eager workers, each in their own branch, each accountable to a task ID, and each contributing to a shared main branch in a way that’s auditable and sane.
And honestly, this is one of the most interesting prompts I’ve ever written — because it isn’t just a prompt. It’s the blueprint for how I want my future AI teams to work.
No comments:
Post a Comment