Integrating parallel work

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: Worktrees · Evidence checks

Parallel work saves time on independent parts; integration still has an order. Two completed workers may mean only that each branch is done. A page using both changes needs acceptance on their combined version and environment. This exercise represents the deliverables with heading and footer text files, without calling those checks full website tests. Apply the workflow to your project's real build/browser checks afterward.

Step 1: Prepare shared acceptance fixtures

Create a new integration-lab in your practice area and open its terminal. The Git/Node commands below are the same on Windows, macOS and Linux. Verify the path and ensure sibling names integration-heading, integration-footer, integration-review and integration-conflict are unused. Choose and consistently substitute different names if necessary instead of overwriting existing work.

git init -b main
git config user.name "Codex Learner"
git config user.email "learner@example.test"

Create the three complete files below. Initially heading.txt contains Title: Small Steps and footer.txt contains Footer: Local exercise, each with a final newline. The tests describe two new requirements that are not yet implemented, so the baseline deliberately has zero passes and two failures. This isolated, remote-free lab is not an unexplained failure on a production main branch.

Title: Small Steps

Footer: Local exercise

import test from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';

const read = name => readFileSync(new URL(name, import.meta.url), 'utf8').trim();
test('heading includes the practice label', () => {
  assert.equal(read('heading.txt'), 'Title: Small Steps Lab');
});
test('footer identifies practice-only material', () => {
  assert.equal(read('footer.txt'), 'Footer: Practice only');
});

node --test integration.test.mjs
git add -- heading.txt footer.txt integration.test.mjs
git commit -m "Add integration exercise and acceptance cases"
git status --short

Step 2: Assign two separate deliverables

git worktree add -b codex/heading ../integration-heading main
git worktree add -b codex/footer ../integration-footer main
git worktree add -b codex/integration ../integration-review main
git worktree list

A may change only integration-heading/heading.txt to Title: Small Steps Lab. B may change only integration-footer/footer.txt to Footer: Practice only. Make these exact edits manually, or explicitly delegate two workers in a supported Codex task with full paths, branches, exclusive writable files and report format. Reference verification uses equivalent deterministic edits without claiming two model runs.

Use two subagents with separate checkouts. Do not create more agents.
Agent A owns only <ABSOLUTE_HEADING_CHECKOUT>/heading.txt on codex/heading.
Set that file to 'Title: Small Steps Lab' with a final newline.
Agent B owns only <ABSOLUTE_FOOTER_CHECKOUT>/footer.txt on codex/footer.
Set that file to 'Footer: Practice only' with a final newline.
Neither agent may edit tests, merge, push, deploy or touch the other checkout.
Return the actual file diff and blockers. Leave staging and integration to the parent.
Wait for both agents before reviewing their results.

Inspect any change to integration.test.mjs before accepting it; workers must not weaken acceptance.

git -C ../integration-heading diff -- heading.txt
git -C ../integration-footer diff -- footer.txt
node --test ../integration-heading/integration.test.mjs
node --test ../integration-footer/integration.test.mjs

Step 3: Commit and integrate in sequence

Wait until both writers stop, inspect full statuses and commit only the specified files. If a worker already committed, verify that commit/diff instead of duplicating it. Record both SHAs. For real collaboration, use verified commits or pause ongoing branch changes so acceptance does not target a moving result.

git -C ../integration-heading add -- heading.txt
git -C ../integration-heading commit -m "Label the practice heading"
git -C ../integration-footer add -- footer.txt
git -C ../integration-footer commit -m "Label the practice footer"
git rev-parse codex/heading codex/footer

git -C ../integration-review status --short
git -C ../integration-review merge --no-ff codex/heading -m "Integrate practice heading"
git -C ../integration-review merge --no-ff codex/footer -m "Integrate practice footer"
node --test ../integration-review/integration.test.mjs
git -C ../integration-review diff main...HEAD -- heading.txt footer.txt

Expect both checks to pass in the review checkout, both new values in its diff and unchanged baseline text on original main. If the first merge conflicts, stop before the second. A green individual branch does not replace combined acceptance. --no-ff preserves visible integration records for teaching; real repositories should follow their own merge policy.

git -C ../integration-review rev-parse HEAD

Record this full SHA with the two passing checks. After the conflict and abort below, run the same command from the original folder: require the identical SHA, clean status and both tests passing. Do not substitute the heading branch or main SHA for the integration commit.

Step 4: Create a deliberate conflict and abort

git worktree add -b codex/conflict ../integration-conflict main

Change only integration-conflict/heading.txt to Title: Another direction and commit it. Starting from old main, it edits the same line differently from the integrated branch. Before merging it, confirm the review checkout is clean and both tests pass. That gives --abort a clear pre-merge state instead of practicing on unsaved work.

git -C ../integration-conflict add -- heading.txt
git -C ../integration-conflict commit -m "Create a conflicting practice heading"
git -C ../integration-review merge --no-ff codex/conflict -m "Attempt conflicting integration"
git -C ../integration-review status --short

The conflict file contains both headings and Git markers. For this exercise, record the error/status and abort instead of choosing a side. Tests should return to two passes with a clean status. With pre-existing uncommitted edits, abort may not reconstruct all earlier work, which is why the clean-state check matters. Real conflict resolution requires choosing behavior section by section and retesting rather than always taking ours or theirs.

git -C ../integration-review merge --abort
node --test ../integration-review/integration.test.mjs
git -C ../integration-review status --short

Cleanup, problems and delivery

If tests cannot locate text files, confirm all three files belong to the same checkout. The test reads relative to its own file URL, preventing the caller's directory from selecting another copy. Identify unexpected changes, trace missing branches to creation/commits and inspect combined diffs after a merge that fails acceptance. Do not let workers weaken tests or split dependent interface work without a shared contract.

Stop practice workers and close checkout windows, then verify full paths and clean statuses for all four copies from integration-lab. Remove only the new, committed, unused copies, investigating refusals without force. The original repository and codex/integration branch remain, so git show can still retrieve the combined result. No production main merge or PR occurs.

git worktree list
git worktree remove ../integration-heading
git worktree remove ../integration-footer
git worktree remove ../integration-review
git worktree remove ../integration-conflict
git show codex/integration:heading.txt
git show codex/integration:footer.txt

Record both input SHAs, merge order, integrated SHA, two-test result, conflict/abort result and preserved main state. Reference Git/Node checks prove neither model delegation nor full website acceptance. Mark unoperated platforms as officially documented. Continue to Browser and images before preparing delivery for a real project.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex