v1.5.0 · August 17, 2026

Two agents, one repo: concurrent instances via git worktrees

The problem

AIDLC could only do one thing at a time. Start a feature, and the next idea waited — not because the work conflicted, but because the framework had one working directory, one checked-out branch, and one place to put an instance's state. Two agents in the same repository would write over each other's files.

The obvious fix is git worktrees: each instance gets its own directory and its own branch, so two agents never share a working tree. The complication is what happens to the framework's own bookkeeping when the working tree stops being singular.

Research on the way into this feature overturned the starting assumption, which is worth stating plainly because it changed the design. The original idea assumed .aidlc/state/ was untracked — scratch data the framework could freely relocate into git's shared internals. In this repository it is tracked and committed deliberately: the artifacts are the historical record, they appear in pull requests, and they survive a re-clone. Moving them would have destroyed the thing the lifecycle exists to produce.

So the real problem was narrower and harder than "support worktrees". Some state is a durable artifact that belongs to a branch and must stay in git. Other state is live coordination data — who currently holds this instance — that is meaningless per-branch and must be visible to every worktree at once. The feature had to separate those two kinds of state without disturbing the first.

How it could be solved

Three decisions carried this feature, and the first was load-bearing: where coordination state lives.

Putting everything in git's shared internals — .git/aidlc/, with the state directory symlinked to it — solves visibility in one move. It was rejected because it untracks state this repository deliberately commits. Artifact history would vanish from pull requests and would not survive a re-clone. Keeping everything tracked, the status quo, fails the other way: worktree branches fragment claims, so instance visibility breaks by construction — an agent on one branch simply cannot see that another branch holds a claim.

What shipped splits by semantics, in the most minimal form that works. Durable artifacts stay tracked per-branch. Coordination data — claims, and only claims — moves to git's common directory, shared by every worktree. The session log stays tracked, because cost attribution reads its history and relocating it would lose that history on re-clone. There was precedent for the mechanism: the cost stash already resolved identity through the git common directory. The price is a schema change, since claims leave the instance file, and the fact that instance existence remains per-branch.

The second decision was when a worktree gets created. Creating it at instance start, the moment concurrency is detected, means every write for that instance lands in its own directory from minute one. Deferring until the implementation phase was rejected for a specific reason: early-phase state files would be written into whatever branch happens to be checked out in the primary directory, so under concurrency one instance's artifacts tangle into another's working tree — and git worktree add will not carry uncommitted files over afterwards. Isolation has to start before the first write, not before the first line of code.

The third was staleness. Rather than introduce a parallel timeout, the existing claim timeout was reused. That left one genuine gap the ideation phase could not close: a claim cannot be declared stale until claim renewal is a defined obligation, and it was not. That went to Requirements to pin down.

How AIDLC solves it

Feature "concurrent instances via git worktrees" on branch feat/20260816-git-worktree, targeting the next minor release v1.5.0 (new CLI surface: start --worktree/--no-code, status --prune, concurrency: config block; no breaking changes — legacy claim behavior is a transparent migration + fallback).

Both packages ship in lockstep as always:

• @rasensio/aidlc 1.5.0 — the concurrency module and rewired commands
• @rasensio/aidlc-content 1.5.0 — updated skills (00-overview, 03-entry-point, 81-continue)

$ aidlc start full-feature --name dark-mode
✓ instance created: dark-mode
✓ branch: feat/20260821-dark-mode
→ phase: ideation▊

name: dark-mode
template: full-feature
current_phase: ideation
scope: full