Review and integrate parallel changes

Parallel agents are useful when work has separate ownership boundaries. This tutorial uses one documentation change and one test change. Do not split two mutually dependent implementation edits merely to increase concurrency.

1. Choose a common baseline

Start from a clean Git repository with a known base commit and an authenticated agent. Record the base and status using the project's Nix development environment:

nix develop -c git status --short
nix develop -c git rev-parse HEAD
agent-cli

Managed worktrees normally start from the selected remote's latest default commit, not your uncommitted files or necessarily your current branch. Read the worktree policy before relying on another checkout containing local changes. If the tasks require an unpublished change, agree on how to make that baseline available before delegating.

2. Assign bounded ownership

/agents limit 2

Use separate worktree agents for two tasks. Agent one may change documentation
for the empty-input behavior only. Agent two may add regression tests only.
Neither may modify the implementation or publish changes. Before editing, have
each report its checkout path and starting commit. Report any baseline mismatch.
When finished, each must report changed files, the exact checks run, and its diff.
Do not automatically merge or remove either checkout.

Replace “empty-input behavior” with the established contract in your project. Use /agents to inspect progress. If both agents need the same file, stop and reassign ownership rather than hoping their edits will combine safely.

3. Inspect each result before integration

Obtain the actual checkout path from each report. In a second shell, substitute it below. Run the commands from your main project's environment:

DOCUMENTATION_CHECKOUT=/absolute/path/reported/by/documentation-agent
nix develop -c git -C "$DOCUMENTATION_CHECKOUT" status --short
nix develop -c git -C "$DOCUMENTATION_CHECKOUT" diff --check
nix develop -c git -C "$DOCUMENTATION_CHECKOUT" diff HEAD
nix develop -c git -C "$DOCUMENTATION_CHECKOUT" log -3 --oneline

Repeat for the test checkout. git diff HEAD includes staged and unstaged tracked changes, but not untracked file contents. Read new files listed by git status separately. If the agent committed changes, inspect the reported commit with git show COMMIT_ID; an empty working-tree diff does not mean no work occurred.

4. Integrate only reviewed changes

Choose one integration method explicitly. One straightforward method is to ask the coordinating agent to create a separate local commit for each reviewed change, report the identifiers, and leave the checkouts intact. Review those commits before cherry-picking:

nix develop -c git status --short
nix develop -c git show DOCUMENTATION_COMMIT
nix develop -c git show TEST_COMMIT
nix develop -c git cherry-pick DOCUMENTATION_COMMIT
nix develop -c git cherry-pick TEST_COMMIT

Replace the uppercase identifiers with the actual reviewed commit hashes. Start with a clean integration checkout. If a conflict occurs, inspect it; do not automatically prefer either side. git cherry-pick --abort abandons the currently active cherry-pick if you decide not to resolve it. It does not undo an earlier successful cherry-pick.

5. Validate the combined result

Run the project's focused tests and broader checks in the integration checkout, even if each agent reported passing tests. Inspect the combined diff against the baseline commit you recorded:

nix develop -c git diff --check BASE_COMMIT HEAD
nix develop -c git diff --stat BASE_COMMIT HEAD
nix develop -c git diff BASE_COMMIT HEAD

Replace BASE_COMMIT with that actual hash. Confirm that both changes are present and that neither introduced unrelated edits. Ask for a final report distinguishing checks run in individual worktrees from checks run after integration.

6. Keep recovery paths until review finishes

Do not remove a worker checkout while it contains the only copy of uncommitted work. Use agent-cli worktree protect /absolute/path/to/managed/worktree to retain a managed checkout during external review. Preview collection with agent-cli worktree gc --dry-run. Local commits and saved conversations are not off-machine backups; publishing remains a separate, explicitly authorized action.