Two Developers, Many Agents: Spec Kit in a Shared Repo

History

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 see specs/020-… as the highest, and both create 021-…. 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: Approved because 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:

  1. One branch per checkout, and no agent works in main. main is only ever landed on.
  2. One feature has one owner. The other developer approves it.
  3. 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 local main. Nothing moves the local main pointer, and one day it was 25 commits behind.
  • switch rather than create for 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 plain git checkout inside 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. rm on a branch someone is mid-change on destroys their databases.
  • Per-checkout Spec Kit pointer. .specify/feature.json is gitignored and says which feature directory the speckit commands write to. After a switch you must rewrite it. A missing pointer fails loudly. A stale one succeeds, and the next /speckit.clarify writes 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:

  • Approved is 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, and bin/land refuses to land code behind an unapproved spec or plan.

  • Specs-only branches land at any status. A spec that is still Draft can land on main as 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 own Owner line, 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, in git log and 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 announce then 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/land runs it again, so no on-behalf tick reaches main untold.
  • 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 gate refuses a diff with stray paths under specs/.
  • Shared stories carry an owner tag. (@dev-b) on a story heading in tasks.md means only that developer's sessions implement it. tasks.md is 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 that bin/worktree, bin/land and pre-push all ask.
  • pre-commit: the checkout's .worktree marker must name the current branch, no staged secret, no two migrations at one version.
  • pre-push: main only 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 Approved lines. 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 main without 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