Урок 10.3. Git Worktrees

One Task -> One Change

Parallel agents need isolated working trees.
Worktrees give each task its own directory, branch and diff.

repo/
  branch: feature/auth-reset
  working tree: one directory
  agent: one active editor

repo/
  branch: feature/auth-reset
  working tree: one directory
  Agent A edits backend
  Agent B edits UI
  Agent C edits tests

repo-main/
  branch: main

repo-auth-api/
  branch: feature/auth-api
  Agent A

repo-auth-ui/
  branch: feature/auth-ui
  Agent B

repo-auth-tests/
  branch: test/auth-e2e
  Agent C

Branch feature/auth-api  -> directory ../project-auth-api
Branch feature/auth-ui   -> directory ../project-auth-ui
Branch test/auth-e2e     -> directory ../project-auth-tests

main
 │
 ├─ worktree/auth-api
 │      branch: feature/auth-api
 │      Agent A: backend endpoint
 │
 ├─ worktree/auth-ui
 │      branch: feature/auth-ui
 │      Agent B: reset form UI
 │
 └─ worktree/auth-tests
        branch: test/auth-e2e
        Agent C: E2E regression tests

git worktree list

git worktree add -b feature/auth-api ../project-auth-api main

git worktree add ../project-auth-api feature/auth-api

cd ../project-auth-api
git status --short
git branch --show-current

git worktree remove ../project-auth-api

git worktree prune

~/codex/ai-agent-development-101
~/codex/ai-agent-development-101-auth-api
~/codex/ai-agent-development-101-auth-ui
~/codex/ai-agent-development-101-auth-tests

~/codex/ai-agent-development-101/worktrees/auth-api

<project>-<task-scope>

Agent A and Agent B both write to feature/auth-reset in two directories.

Agent A -> feature/auth-api
Agent B -> feature/auth-ui
Agent C -> test/auth-e2e

Parallel-ready means independent enough to produce separate reviewable diffs.

[ ] Task имеет один verifiable outcome
[ ] Task имеет свой branch name
[ ] Expected files/areas не пересекаются с другой task
[ ] Shared interface согласован
[ ] Acceptance criteria понятны
[ ] Verification commands определены
[ ] Integration point известен
[ ] Stop conditions указаны
[ ] Агент знает, что не должен менять shared contract без approval

Base branch:

Integration strategy:

Worktrees:
- path:
  branch:
  agent:
  task:
  expected files:
  verification:
  dependencies:
  stop conditions:

Conflict risks:

Merge order:

Base branch:
main

Integration strategy:
Merge each task through separate PR into main, then run integration tests.

Worktrees:
- path: ../app-auth-api
  branch: feature/auth-reset-api
  agent: Agent A
  task: Add reset password API endpoint
  expected files:
    - src/auth/resetPasswordController.ts
    - src/auth/resetPasswordService.ts
    - tests/auth/resetPassword.api.test.ts
  verification:
    - npm test -- resetPassword.api
  dependencies:
    - reset token repository contract exists
  stop conditions:
    - API contract missing
    - schema migration required

- path: ../app-auth-ui
  branch: feature/auth-reset-ui
  agent: Agent B
  task: Add reset password form
  expected files:
    - web/routes/reset-password.tsx
    - web/components/ResetPasswordForm.tsx
    - web/components/ResetPasswordForm.test.tsx
  verification:
    - npm test -- ResetPasswordForm
  dependencies:
    - API contract from design doc
  stop conditions:
    - API response contract changes

- path: ../app-auth-e2e
  branch: test/auth-reset-e2e
  agent: Agent C
  task: Add E2E reset password flow
  expected files:
    - tests/e2e/password-reset.spec.ts
  verification:
    - npm run test:e2e -- password-reset
  dependencies:
    - API and UI branches integrated or mocked contract
  stop conditions:
    - cannot run browser test locally

Conflict risks:
- API contract changes may affect UI and E2E
- test fixtures may overlap

Merge order:
1. API
2. UI
3. E2E
4. integration verification

Password Reset

AUTH-010:
Define reset token repository and data model.

Большая feature -> task graph -> parallel-ready branches

../app-auth-api
Agent A:
- backend endpoint
- UI form
- docs rewrite
- dependency upgrade

../app-auth-api
Agent A:
- backend endpoint only
- API integration tests
- no UI
- no dependency upgrade

Main working tree has user edits in docs.
Need to run agent on auth bug fix.

git worktree add -b fix/auth-token-reuse ../app-auth-token-reuse main
cd ../app-auth-token-reuse

Worktree isolation is filesystem and branch isolation, not full environment isolation.

Port:
Database:
Env file:
Test command:
Background services:
Generated outputs:
Cleanup:

Worktree: ../app-auth-ui
Branch: feature/auth-reset-ui
Port: 3002
Database: not needed, use mocked API
Env file: .env.local copied from template, no secrets committed
Test command: npm test -- ResetPasswordForm
Background services: none
Generated outputs: playwright screenshots in tmp/auth-ui
Cleanup: remove tmp screenshots after review

Worktree: ../app-auth-api
Branch: feature/auth-reset-api
Port: 3001
Database: app_auth_api_test
Env file: .env.test
Test command: npm test -- resetPassword.api
Background services: postgres test container
Generated outputs: none
Cleanup: drop app_auth_api_test after task

You are working in a dedicated Git worktree.

Worktree:
../app-auth-api

Branch:
feature/auth-reset-api

Task:
AUTH-012: Add reset password API endpoint.

In scope:
- backend controller/service
- API integration test

Out of scope:
- UI form
- E2E browser flow
- dependency updates
- reset token data model changes unless blocking

Rules:
- inspect git status before edits;
- keep diff scoped to this task;
- do not touch files owned by other worktrees unless required and explained;
- stop if API contract changes;
- do not commit until asked;
- report changed files and verification evidence.

You are working in a dedicated Git worktree.

Branch:
feature/auth-reset-ui

Task:
AUTH-016: Add reset password form using the documented API contract.

Assume API contract:
POST /reset-password
Request: token, newPassword
Responses: success, TOKEN_EXPIRED, TOKEN_ALREADY_USED

Do not modify backend code.
If the contract is insufficient, stop and ask.

1. Создать worktree.
2. Перейти в его directory.
3. Проверить branch/status.
4. Передать агенту task boundary.
5. Запустить agent workflow.
6. Получить diff, tests, final evidence.
7. Сделать commit или PR.
8. Интегрировать в нужном порядке.

1. Merge/review API branch.
2. Update UI branch from main.
3. Merge/review UI branch.
4. Update E2E branch from main.
5. Run full integration tests.

1. Create integration branch from main.
2. Merge API branch.
3. Merge UI branch.
4. Merge E2E branch.
5. Resolve conflicts.
6. Run integration verification.
7. Open PR from integration branch.

git switch main
git pull
git switch -c integration/password-reset
git merge feature/auth-reset-api
git merge feature/auth-reset-ui
git merge test/auth-reset-e2e

npm test -- auth
npm run test:e2e -- password-reset
npm run typecheck

Git cannot safely decide how to combine these changes.
Human or reviewer agent must inspect.

Write one Markdown lecture in one file.

Option A: enforce Plan Mode in prompt/rule layer
Option B: enforce Plan Mode in tool permission layer

git worktree add -b spike/plan-mode-prompt ../app-plan-mode-prompt main
git worktree add -b spike/plan-mode-tool-gate ../app-plan-mode-tool-gate main

Agent works in ../app-auth-api.
Inside that worktree, agent tool may create checkpoints after each edit.
Final useful state still becomes Git commit on feature/auth-api.

cd ../app-auth-api
git status --short
git branch --show-current

cd ../ai-agent-development-101
git worktree remove ../app-auth-api
git worktree prune

git worktree list

1. One worktree per task branch.
2. One agent writes in one worktree.
3. Do not let two agents write same branch.
4. Do not create worktrees inside the main repo by default.
5. Each worktree has explicit task boundary.
6. Each worktree has verification commands.
7. Shared environment must be planned.
8. Integration happens intentionally, not by copying files.
9. Cleanup only after status is understood.
10. Worktree does not replace tests, review or commits.

Password Reset

main

1. feature/auth-reset-api
2. feature/auth-reset-ui
3. test/auth-reset-e2e
4. integration verification

Main worktree:
- user is editing docs
- urgent bug fix needed in auth

 M docs/course-outline.md
 M guide/content_plan.md

git worktree add -b fix/auth-permission ../app-fix-auth-permission main
cd ../app-fix-auth-permission

../ai-agent-development-101
  user docs work

../app-fix-auth-permission
  agent bug fix branch

Implementer branch:
feature/auth-reset-api

git worktree add ../app-review-auth-api feature/auth-reset-api
cd ../app-review-auth-api

Review this branch as a reviewer agent.

Inputs:
- task spec: AUTH-012
- diff against main
- relevant code/tests

Do not edit files unless explicitly asked.
Focus on:
- bugs;
- missing tests;
- scope creep;
- security issues;
- verification gaps.

AGENT-WF-01:
Plan Mode must not edit files.

evals depend on policy names and tool trace format.

Mode:
plan

Forbidden tools:
- apply_patch
- file write commands
- dependency install
- migration execution

Expected output:
- implementation plan
- no claim of completion

Define Plan Mode tool policy contract.

Create a Git worktree plan for this feature.

Input:
<feature/task graph>

Output:
- base branch;
- candidate parallel tasks;
- worktree path;
- branch name;
- assigned agent role;
- expected files;
- verification commands;
- dependencies;
- conflict risks;
- merge order;
- tasks that must remain sequential.

You are working in a dedicated Git worktree.

Worktree path:
<path>

Branch:
<branch>

Task:
<task>

Rules:
- inspect git status before edits;
- work only on this task;
- do not modify files assigned to other worktrees;
- do not change shared contracts without stopping;
- run verification for this task;
- report diff summary and evidence;
- do not commit until asked.

Review this worktree before integration.

Check:
- branch name;
- git status;
- diff against base;
- whether changed files match task;
- tests/evals run;
- not-run checks;
- residual risks;
- conflict risk with other branches.

Do not merge yet.

Integrate these branches in order:
1. <branch A>
2. <branch B>
3. <branch C>

For each merge:
- inspect diff;
- resolve conflicts carefully;
- run tests relevant to both merged branches;
- stop if public contract changes unexpectedly.

After all merges:
- run integration verification;
- report conflicts, resolutions, commands/results and residual risks.

git switch main
git pull
git worktree add -b feature/auth-reset-api ../app-auth-api main
git worktree add -b feature/auth-reset-ui ../app-auth-ui main
git worktree add -b test/auth-reset-e2e ../app-auth-e2e main
git worktree list

cd ../app-auth-api
git status --short

cd ../app-auth-ui
git status --short

cd ../app-auth-e2e
git status --short

cd ../app-auth-api
git diff --stat main...HEAD

cd ../ai-agent-development-101
git switch main
git pull
git switch -c integration/password-reset
git merge feature/auth-reset-api
git merge feature/auth-reset-ui
git merge test/auth-reset-e2e

git worktree remove ../app-auth-api
git worktree remove ../app-auth-ui
git worktree remove ../app-auth-e2e
git worktree prune

[ ] Branch name matches task
[ ] git status понятен
[ ] Diff focused on one task
[ ] Changed files match expected scope
[ ] No unrelated refactor
[ ] No dependency/lockfile change without approval
[ ] Tests/evals run for this task
[ ] Not-run checks documented
[ ] Shared contract changes documented
[ ] Conflict risks reported
[ ] Commit message tied to task

[ ] Merge order defined
[ ] All branches have clean commits
[ ] Base branch updated
[ ] API/contracts stable
[ ] Conflict-prone files identified
[ ] Tests from each task known
[ ] Integration tests planned
[ ] Rollback plan exists

Password Reset

AUTH-010: reset token repository
AUTH-012: request reset endpoint
AUTH-013: reset password endpoint
AUTH-016: reset password UI form
AUTH-020: password reset E2E flow
AUTH-021: docs for reset token states

Base branch:
Integration strategy:
Merge order:
Conflict risks:
Environment risks:

1. Change reset token DB schema.
2. Implement API using the new schema.
3. Build UI using documented API contract.
4. Add E2E test for full reset flow.
5. Update password policy rules.
6. Update docs table for reset token states.

Sequential:
1 -> 2, because API depends on schema.
4 after 2 and 3, because E2E depends on API + UI.

Parallel-ready:
3 can start after API contract is documented.
6 can start after token state semantics are agreed.

Out of scope:
5 password policy rules, unless feature explicitly includes it.

../app-agent-evals

test/bugfix-agent-regression-flow

BUGAGENT-03:
Bug-fix agent must add failing regression test before fix when practical.

[ ] Task маленькая
[ ] Task имеет one change
[ ] Branch name выбран
[ ] Worktree path выбран
[ ] Base branch указан
[ ] Dependencies понятны
[ ] Shared contracts стабильны
[ ] Expected files названы
[ ] Verification commands названы
[ ] Environment risks учтены
[ ] Integration order известен

Task graph
-> parallel-ready tasks
-> one worktree per task
-> one agent per worktree
-> one change per branch
-> integration verification