A checkpoint gives you a known state to compare and recover. A branch labels a line of work; a worktree gives another checkout. Neither automatically isolates simulator data or external resources.

Clean baseline → New branch or worktree → Small reviewed change → Test then integrate
  1. 1Clean baseline
  2. 2New branch or worktree
  3. 3Small reviewed change
  4. 4Test then integrate

Work through the example

Inspect git status before asking an agent to edit. Commit coherent work, and review untracked files before switching tasks.

Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.

Implementation reference

The following focused section is adapted from the maintained project guide. It preserves the source’s examples and limitations.

2. /batch — many isolated changes

/batch is a packaged use of subagents plus git worktrees, aimed at roughly 5–30 isolated changes that each become their own PR. Each unit gets a fresh subagent working in its own worktree, so the changes cannot collide on disk.

Good fits:

  • Apply one mechanical rule across many modules — "add @MainActor to every view model", "replace literal spacing with Space.* tokens".
  • Fix the same class of bug in many independent places.
  • Bump a dependency across several packages.
  • Migrate N files to a new API where each file stands alone.

Bad fits:

  • Units that share files. Two workers editing AppDelegate.swift will produce conflicting PRs.
  • Units with ordering constraints. Batch has no dependency graph.
  • Exploratory work. Batch executes a known change; it does not decide what the change should be. Plan first (ios-plan), then batch.
  • One large refactor. That is one PR, not thirty.

Making a batch succeed

The per-unit prompt must be complete and self-contained — each worker starts cold and cannot see the others.

For <module>:
  goal:     every @Observable type the UI renders is @MainActor final class
  scope:    only files under <module>/ — do not touch shared/ or Package.swift
  rules:    behavior must not change; add nothing but the isolation annotations
  verify:   swift build && swift test --filter <module>
  report:   the diff, plus the real output of the verify command
  if the module has no such types: report "no change needed" and stop

That last line matters. Without an explicit no-op path, workers invent work to justify their existence.

Worktrees

Each unit gets its own working copy, so parallel writes are safe:

git worktree add ../wt-cart -b batch/cart-mainactor
git worktree add ../wt-orders -b batch/orders-mainactor
### … worker per worktree …
git worktree remove ../wt-cart

Isolation is the whole point. Without it, parallel writers corrupt each other's work in ways that are extremely hard to diagnose after the fact.

Acceptance and failure review

Checkpoint What to inspect If it does not match
Clean baseline Confirm the input and environment Preserve the failure and return to this step
New branch or worktree Inspect the intermediate artifact Preserve the failure and return to this step
Small reviewed change Run the focused check Preserve the failure and return to this step
Test then integrate Record the observed result Preserve the failure and return to this step

Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.

Evidence and limits

The workflow is source guidance; a four-client isolation experiment is not claimed.

This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.

Inspect the source used in this lesson.

What to do next

Next: Keeping the agent inside your design: tokens, no hardcoded colors, no fixed fonts