Working With Multiple Developers

Blueprint supports parallel work through normal Git isolation. Each developer or coding agent gets a separate checkout, a dedicated branch, and one active Blueprint work item. The default single-checkout workflow does not change.

This is not a separate team mode. Blueprint does not create shared locks, assign tasks, or coordinate agents. Git and your pull-request provider remain responsible for branch isolation, review, and conflict resolution.

When parallel work fits

Use parallel checkouts when the work items can be built and reviewed independently. Stay serial when one feature depends on another unfinished feature, both require the same migration, or the merge order changes product behavior.

Every checkout still follows the normal loop:

/feature -> /implement -> /check -> /audit current -> /complete

Configure pull-request landing

Set git.landing to pull-request in blueprint/config.json before creating the parallel checkouts:

"git": {
  "landing": "pull-request"
}

Land that configuration on the default branch first so every new checkout sees the same policy. Pull-request landing applies to regular Complete runs. Continuous Mode remains serial and local-only.

Create one checkout per work item

Start each checkout from the current default branch. The examples below use main; replace it if the repository uses another default branch.

For local Git worktrees:

git switch main
git pull --ff-only
git worktree add -b feature/export-reports ../project-export-reports main
git worktree add -b feature/share-reports ../project-share-reports main

For developers using separate clones, create each branch from the current remote default branch:

git fetch origin
git switch -c feature/export-reports origin/main

Use the configured feature/, fix/, or rollback/ prefix. A pre-created feature branch must match the planned work item’s lowercase kebab-case title. Feature accepts that branch only when it is the current pristine branch at the local default commit.

Start Blueprint inside each checkout

Open a separate AI session in each checkout, then run Feature for the work item assigned to that branch:

Checkout A: /feature 4
Checkout B: /feature 5

Each checkout now has its own current-feature.md, findings ledger, and review state. Do not run two active work items in the same working directory. Never replace another developer’s active spec.

The build plan remains shared. Two branches can update it at the same time, so the later branch may need a normal Git conflict resolution after the earlier feature lands.

Complete through pull requests

Run /complete in the checkout where the work was built. Complete runs the normal verification and review gates, archives the work, and creates the single work-level commit.

In pull-request mode, Complete then:

1. Confirms the remote and default branch.
2. Shows the branch push and proposed pull request.
3. Requests approval to push the branch and open the pull request.
4. Stops before merge.

Creating the pull request never approves its merge. Use squash merge so the default branch receives one commit for the work item. After the provider reports the merge, run /complete again in that checkout so it can verify the exact result and guide local cleanup.

Update branches after another feature lands

Before continuing work that depends on a newly merged feature, update the remaining checkout from the remote default branch:

git fetch origin
git merge origin/main

Resolve conflicts on the work branch, then rerun the relevant checks. For a build-plan.md conflict, preserve the completed checkbox from the merged work and the still-active item from the current branch.

Status permits an active feature to differ from the next unchecked build-plan item only when git.landing is pull-request. Missing plan items, completed targets, and branch-prefix mismatches still produce warnings.

Clean up only after verified merge

Keep the checkout until Complete verifies the provider’s squash merge. Then follow its branch-cleanup instructions and remove the finished worktree from the base checkout. Never remove a worktree that contains uncommitted work or an open pull request.

What Blueprint does not coordinate

This workflow deliberately stays lightweight. It does not provide:

• A shared task-assignment service
• Per-item state folders inside one checkout
• Automatic dependency scheduling
• Automatic conflict resolution
• Agent-to-agent messaging

Those capabilities can be added later if real team usage requires them. The current model handles parallel implementation while keeping Blueprint’s normal files, review gates, and history format.

See Project Configuration for every setting and Complete for the full landing contract.