Two Developers, Many Agents: Spec Kit in a Shared Repo
Two Developers, Many Agents: Spec Kit in a Shared Repo
The Spec-Driven Workflow and The Agentic-Feature Workflow assume one person steering one pipeline. That model breaks the moment a second engineer joins. Now there are two humans, each running three or four agent sessions in parallel, all writing specs, plans and code into the same repository. The pipeline stays the same. What changes is coordination: who owns a feature, who approves it, what happens when two sessions pick the same number, and how work reaches main without anyone stepping on anyone else.
This article describes how we run that in practice. The repo is a Go + Rails product built almost entirely by agents, with two developers and a dozen live worktrees on a normal day. None of it depends on the stack. The mechanism is four small shell scripts, three git hooks and one constitution article.
The problem, concretely
With one developer, "the spec is approved" means "I read it and said go". With two developers and many agents, every one of these went wrong at least once before it was written down:
- Number collisions. Two sessions both run
/speckit.specify, both seespecs/020-…as the highest, and both create021-…. Every document cites features by number, so a collision poisons cross-references. - Shared runtime state. Two agent sessions in the same checkout share a database, ports and a control socket. One agent's migration breaks the other's test run. One agent commits onto the other's branch.
- Silent approval. An agent writes
Status: Approvedbecause the prompt said "proceed". Nobody else read the spec. - Cross-feature edits. Feature A's plan quietly changes a contract that feature B owns. B's owner finds out when their tests break.
- "It passed" with no proof. A session reports a green gate on a tree that was edited afterwards.
The fix is not more process in people's heads. Each rule becomes a refusal in a script, so an agent that forgets it gets stopped rather than trusted.
The shape
flowchart LR
subgraph A["Developer A"]
A1["agent: 041-feature"]
A2["agent: fix/some-bug"]
A3["agent: chore/batch"]
end
subgraph B["Developer B"]
B1["agent: 042-feature"]
B2["agent: review + approve 041"]
end
A1 --> W1[".worktrees/feat41 · slot 1"]
A2 --> W2[".worktrees/fix · slot 2"]
A3 --> W3[".worktrees/chore · slot 3"]
B1 --> W4[".worktrees/feat42 · slot 4"]
W1 & W2 & W3 & W4 --> L["bin/land"]
L --> M["main (linear, gated)"]
B2 -. "Approved commit" .-> W1
Three rules hold it together:
- One branch per checkout, and no agent works in
main.mainis only ever landed on. - One feature has one owner. The other developer approves it.
- Exactly one path onto
main:bin/ci && bin/land <branch>.
Worktrees: one checkout per branch, isolated at runtime
git worktree gives you separate working directories. That is not enough when the app has databases, dev servers and sockets. Two worktrees that share app_development are one worktree with extra steps.
bin/worktree wraps it and hands every checkout a slot (1..12, where main is 0). From the slot it derives everything the checkout needs to run alone:
bin/worktree create 041-budget-alerts feat41 # new branch off origin/main, slot N
bin/worktree switch feat41 fix/late-settle # same checkout + DBs, another branch
bin/worktree list # name, slot, port, branch, dirty count
bin/worktree rm feat41 # checkout + its databases + its socket dir
| Per-slot resource | Derived as |
|---|---|
| Web port / Vite / API / metrics | 3120+N / 3136+N / 8080+N / 9091+N |
| Databases | app_development_<name>, app_test_<name> and their queue/e2e twins |
| Control socket | /tmp/app-<name>/control.sock |
Three generated files carry that state, and nothing else does. A .worktree marker at the root (slot, name, branch) is read by database.yml and the hooks. A local YAML config is read by every app process. A .env is read only by the process manager. The reason for files instead of exports: an export only exists in the shell that made it, and a bare rails command in the wrong checkout reaches the wrong database.
Choices that turned out to matter:
- New branches start from
origin/main, not localmain. Nothing moves the localmainpointer, and one day it was 25 commits behind. switchrather thancreatefor small work. An agent keeps one standing worktree and retargets it. The databases stay, the pending migration is applied, and the marker follows, so the bootstrap cost is paid once. The pre-commit hook refuses a commit on a branch the marker does not name, which is why a plaingit checkoutinside a worktree is off the table.- When all 12 slots are full, take one whose branch is merged and 0 ahead. Never judge by name or age.
rmon a branch someone is mid-change on destroys their databases. - Per-checkout Spec Kit pointer.
.specify/feature.jsonis gitignored and says which feature directory the speckit commands write to. After aswitchyou must rewrite it. A missing pointer fails loudly. A stale one succeeds, and the next/speckit.clarifywrites into the previous feature's directory without a word.
Every agent's first tool call inside a worktree is git rev-parse --show-toplevel and cat .worktree. The launcher's working directory is not ground truth.
Feature numbers are claimed on the remote
Spec numbers stay sequential because every document cites SPEC-032, not a UUID. What changes is where a number is claimed: on the remote, by the first push, not in the local specs/ directory.
n=$(bin/spec next budget-alerts) # 041-budget-alerts: reads origin's branches AND origin/main's specs/
bin/worktree create "$n" feat41
# in the worktree: /speckit.specify … then, before anything else:
bin/spec pr # push (claims the number) + open "SPEC-041: <title>" as a draft PR
If the other developer's session pushed 041-… first, the pre-push hook refuses. There is one command to recover:
bin/spec renumber 042 # moves the directory, rewrites references, renames branch, fixes feature.json + .worktree
That is why the push happens immediately after /speckit.specify. At that moment, renumbering rewrites one commit's worth of text. After a plan, tasks and thirty code commits whose scopes say (041), it is a mess.
Specs are cited in prose as SPEC-041, never as a bare 041. The ADRs have four-digit numbers, and a bare three-digit number reads as one to anyone who just came from docs/adr/.
Ownership and the approval handshake
Every spec.md and plan.md (from the feature where the rule was ratified onward) opens with two lines the gate parses:
**Owner**: @dev-a
**Status**: Scaffold | Draft | In Review | Approved
The pull request exists from the moment the spec does, as a draft while Draft and ready at In Review. The other developer reads the spec there, not in a branch they have to fetch. The handshake happens twice:
sequenceDiagram
participant A as Owner (Dev A + agents)
participant PR as Pull request
participant B as Other developer (Dev B)
A->>PR: speckit.specify, then bin/spec pr (draft)
A->>PR: Status In Review
B->>PR: reads spec.md, commits "Status: Approved"
Note over A: speckit.plan refuses until spec is Approved
A->>PR: plan.md, data-model.md, contracts/
B->>PR: reads plan, ticks the cross-feature rows B owns, commits "Approved"
Note over A: speckit.tasks and speckit.implement refuse until plan is Approved
A->>PR: tasks + implement (tasks.md committed after each task)
A->>PR: bin/ci, then bin/land
The rules that make this hold with agents in the loop:
-
Approvedis written by the other developer, in a commit of their own. The owner's agent cannot approve its own spec. The plan, tasks and implement skills refuse to start early, andbin/landrefuses to land code behind an unapproved spec or plan. -
Specs-only branches land at any status. A spec that is still
Draftcan land onmainas a review increment. The gate only bites when the diff touches code. So the rhythm is small increments, landed often. -
Self-approval exists, and it is loud. People go on holiday. When the other developer is away, the owner may approve their own work, but only in one exact form:
**Status**: Approved — self-approved by @dev-a 2026-09-21: <reason>It is written by
bin/spec approve spec|plan "<reason>", never by hand. The command takes the handle from the file's ownOwnerline, today's date and a required reason, validates the result and commits it. The gate prints every self-approval when the branch lands, so it is visible in the file, ingit logand at landing time, not discovered months later. The other developer withdraws one by editing the status back and saying why.
Cross-feature impact: shared surfaces need the other owner's tick
Most collisions between two developers are not merge conflicts. They are semantic: feature 038 bumps a wire format that feature 017 is also bumping. Every plan.md therefore carries a mandatory section the gate checks for:
## Cross-feature impact
**Active features checked**: every open PR and remote feature branch, 2026-09-21: 017 (#71), 035 (#48), …
| Shared surface | Owned by | Change proposed | Agreed with owner |
|-----------------------|-----------------|----------------------------------------|-------------------|
| Bundle format number | 017 (@dev-a) | This takes 8; whichever lands second renumbers | ☑ same owner |
| `Attachment` contract | 028 (@dev-b) | new optional `models` key | ☐ |
- A
☐row blocks tasks, implement and landing. The row is ticked by the surface's owner in a commit of their own. - On-behalf ticks exist, and are announced. If the owner is away, the plan's owner may write
☑ on behalf of @dev-b by @dev-a 2026-09-21: <reason>.bin/spec announcethen posts a comment on the PR that @-mentions the absent owner. It is idempotent: a digest marker stops it posting twice, and a new tick still gets announced.bin/landruns it again, so no on-behalf tick reachesmainuntold. - Agreement given in conversation is not on-behalf. Tick it
☑and write where they said it. - A feature branch writes only inside its own
specs/NNN-slug/. It reads other features' directories as input to this table. It never edits them.bin/spec gaterefuses a diff with stray paths underspecs/. - Shared stories carry an owner tag.
(@dev-b)on a story heading intasks.mdmeans only that developer's sessions implement it.tasks.mdis committed after every completed task, so the other developer's agents see real progress, not a stale checklist.
Landing: one path onto main
bin/land <branch> is the only way onto main. The GitHub ruleset enforces this: it requires a PR, a linear history and a gate status. Each check is a refusal with a message that says how to fix it:
| Step | Refuses when |
|---|---|
| Branch name | not NNN-slug (spec-kit) or <type>/<slug> with a Conventional Commit type |
| Commit subjects | any subject is not a Conventional Commit, or is a fixup!/squash! (the rebase merge keeps every commit, and svu computes the release version from them) |
bin/spec gate |
number taken on origin · writes outside its own specs/ dir · code behind an unapproved spec or plan · a ☐ row. Prints every self-approval and on-behalf tick. |
| Gate receipt | bin/ci has not passed this exact tree (receipt at .git/gate-passed/<tree-sha>) |
| Push | origin's copy of the branch is not the tip after pushing (never force over someone else's push) |
| PR + status | opens the PR if none is open, announces on-behalf ticks, posts gate: success to the head commit |
| Merge | gh pr merge --rebase. If main moved and the branch no longer applies, GitHub refuses: rebase, re-run bin/ci, land again. |
| Follow-up | fast-forwards the main checkout wherever it is, and touches tmp/restart.txt so the dev server reloads |
Why a receipt per tree and not per branch: several small fixes on one chore/ branch cost one gate run and one landing. The receipt is keyed on the tree hash, so any edit after the run invalidates it, even one the agent "forgot to mention".
The gate runs on the developer's machine, for now. CI on GitHub is not switched on, so the gate status is self-reported, which is the same trust the local receipt always carried. We accept one known gap: a rebase-merge onto a main that moved since the run lands a combination nobody ran. We accept it rather than turn every busy morning into a race, and the next gate run on main catches it. This is a deliberate shortcut with a named ceiling. The upgrade trigger is turning on the CI workflow that already exists.
Gate lanes for parallel sessions
bin/ci with no arguments is the gate, and the only run a landing may rely on. With three sessions each fixing their own half, running three identical full gates is waste, so an argument narrows it:
bin/ci gateway # Go build/vet/test/fuzz, depguard, govulncheck
bin/ci ruby # rubocop, brakeman, rspec, schema dumps
bin/ci web # pnpm audit, tsc, eslint
bin/ci repo # secrets, SBOM, vulns, constitution greps, TLA+
The four lanes partition the gate: every step appears in exactly one. A step written outside a lane block runs in all four, so a misplaced new check costs redundancy, never silence. Never add a check that only CI runs. There is one entrypoint and one answer to "did it pass?".
Hooks: the same rules, earlier
The hooks are tracked in .githooks/, and bin/worktree create sets core.hooksPath for every checkout:
commit-msg: enforces Conventional Commit subjects. Called with--branch <name>, it is also the single source for the branch-name vocabulary thatbin/worktree,bin/landandpre-pushall ask.pre-commit: the checkout's.worktreemarker must name the current branch, no staged secret, no two migrations at one version.pre-push:mainonly fast-forwards, branch names follow the convention, and a feature number owned by another slug on the remote is refused.
Each rule lives in one place and several entry points call it. That means an agent that bypasses bin/land still meets the same refusal at git push.
The constitution article
All of the above is Article 12 of the project constitution, Two developers, ratified for features 021 and later (earlier features keep their headers and history). Each clause names the check that enforces it, [ci] or [review]:
| § | Rule | Enforced by |
|---|---|---|
| 12.1 | spec + plan declare Owner and Status; plan has Cross-feature impact | bin/spec headers in bin/ci |
| 12.2 | a number is claimed on the remote by the first push | pre-push, bin/land |
| 12.3 | a feature branch writes only inside its own specs/ dir |
bin/spec gate |
| 12.4 | code lands only behind approved spec + plan | bin/spec gate, speckit skill gates |
| 12.5 | Approved by the other developer, or a recorded self-approval |
bin/spec headers, bin/spec approve |
| 12.6 | shared surfaces agreed by their owner (or announced on-behalf) | bin/spec gate, bin/spec announce |
| 12.7 | shared stories carry an owner tag; tasks.md committed per task |
review |
| 12.8 | a session loads its own feature, others on demand only | review |
| 12.9 | the constitution changes only on a branch both approved | review |
12.8 matters more with agents than with humans. An agent that loads every feature directory "for context" dilutes its attention and starts designing across features it does not own. It loads the constitution, its own specs/NNN/, and what plan.md names.
One maintenance gotcha: the refusals in the speckit plan/tasks/implement skills are text inside generated SKILL.md files, and a Spec Kit upgrade rewrites them. Re-apply them from Article 12 after every upgrade. bin/spec headers and bin/land hold the line whether or not the skills do.
A day, end to end
# Dev A, main checkout
n=$(bin/spec next budget-alerts) # 041-budget-alerts
bin/worktree create "$n" feat41
# agent session in .worktrees/feat41
printf '{"feature_directory":"specs/%s"}\n' "$n" > .specify/feature.json
/speckit.specify … # Owner: @dev-a, Status: Draft
bin/spec pr # pushes, claims 041, opens draft "SPEC-041: …"
/speckit.clarify # → Status: In Review
bin/ci && bin/land "$n" # specs-only increment lands at any status
# Dev B, own session, on the PR: reads spec.md, commits "Status: Approved"
/speckit.agentic.priorart → /speckit.plan → restraint → security
# plan names a ☐ row on B's contract
# Dev B ticks the row, approves the plan in their own commit
/speckit.tasks → /speckit.implement # tasks.md committed per task
/speckit.agentic.verify # independent reviewer, never the implementer
bin/ci && bin/land "$n" # gate receipt, status, rebase-merge, main fast-forwards
bin/worktree rm feat41 # or switch it to the next branch
Meanwhile Dev A's second session is on fix/… in slot 2 and Dev B's on 042-… in slot 4. Their databases, ports and branches never touch.
What we learned
- Put coordination into refusals, not etiquette. Agents do not remember etiquette across sessions. A script that exits 1 with the fix in its message works every time.
- Make the exception loud instead of forbidding it. Self-approval and on-behalf ticks exist because humans are away sometimes. Forbidding them would just produce hand-edited
Approvedlines. A required form, a reason, a date, and a print at landing keep the escape hatch honest. - Claim shared names at the shared place. Numbers are claimed on the remote because that is the only place both developers see.
- Isolate runtime, not just source. Worktrees without per-slot databases and ports are one shared environment with a false sense of separation.
- A green report is a claim about a tree. Key the receipt on the tree hash and the question "did it pass?" has a checkable answer.
- Small increments, landed often. Specs-only landings let review happen on
mainwithout waiting for code. That keeps the two developers' views of the repo close together.
Related: Agentic Engineering · Spec-Driven Workflow · Trust but Verify · Losing Control: When the Agent Goes Off-Plan · The Compounding Layer · Installing and Running the Toolkit