# M167.4 — Manual Worktree Pattern for Parallel Agents

Path B workaround empirically validated

Codifies the manual pre-create worktree pattern in `/ork:implement` as a workaround for the broken `Agent(isolation="worktree")` behavior in CC Opus 4.7 (Nov 2026 — Apr 2026). Closes Yonatan-HQ/platform#3224 Path B.

## The bug

Spawn pattern

    Agent(subagent_type="x", isolation="worktree", run_in_background=true)
    Agent(subagent_type="y", isolation="worktree", run_in_background=true)
    Agent(subagent_type="z", isolation="worktree", run_in_background=true)
    Agent(subagent_type="w", isolation="worktree", run_in_background=true)

Expected behavior
primary ──── HEAD \ ├── worktree-x ── feat/x branch (agent X works here) ├── worktree-y ── feat/y branch (agent Y works here) ├── worktree-z ── feat/z branch (agent Z works here) └── worktree-w ── feat/w branch (agent W works here)
Actual behavior (git reflog of primary)

    checkout: moving from feat/x to feat/y
    checkout: moving from feat/y to feat/z
    checkout: moving from feat/z to feat/w
    ...

primary ──── HEAD ── feat/x ── feat/y ── feat/z ── feat/w ↑ ↑ ↑ ↑ agent X agent Y agent Z agent W (untracked files stashed at each switch)

Result: 3 of 4 agents hit the ~60-tool-use cliff because `pre-push` hooks fail on thrashed `node_modules`.

## Empirical evidence (M164 overnight, 2026-05-11→12)

Pattern | Tool-uses / agent | Cutoffs
--- | --- | ---
Wave 1 — `isolation="worktree"` | 60 – 86 | 3 of 4
Wave 2/3 — manual pre-create | 4 – 22 | 0 of 8

## The fix — manual pre-create + cd-first

Step 1 — Lead pre-creates worktrees

    backend_wt = setup_agent_worktree(
        REPO, SLUG, "feat/x-backend"
    )
    frontend_wt = setup_agent_worktree(
        REPO, SLUG, "feat/x-frontend"
    )
    tests_wt = setup_agent_worktree(
        REPO, SLUG, "feat/x-tests"
    )

Step 2 — Spawn with explicit cd in prompt

    Agent(
      subagent_type="backend-system-architect",
      prompt=(
        f"FIRST: cd {backend_wt}. "
        f"THEN implement: ... "
        f"Commit + push + open PR "
        f"from {backend_wt}."
      ),
      run_in_background=true)

## Helper function

    import subprocess

    def setup_agent_worktree(repo_root: str, slug: str, branch: str) -> str:
        """Pre-create a worktree off origin/main and return its absolute path."""
        path = f"{repo_root}/../{slug}-{branch.split('/')[-1]}"
        subprocess.run(
            ["git", "-C", repo_root, "worktree", "add",
             "-b", branch, path, "origin/main"],
            check=True,
        )
        return path

## Why this works

The `isolation` param is accepted by CC but the worktree may not be created (or `cd`'d into) before the agent's first Bash call fires. By the time the agent runs, its CWD is the primary tree.

Manual pre-creation moves the `git worktree add` into the deterministic lead context BEFORE the agent starts. The agent's prompt then explicitly `cd`'s into the prepared worktree as the first instruction.

## Prompt constraints (load-bearing)

1. `cd` must be the FIRST Bash call. Wrap in `FIRST: cd <path>. THEN: ...` so the agent can't skip.
2. Forbid touching the primary tree. Add: "Do not `cd` out. All commits, pushes, PRs originate from {worktree-path}."
3. Push early. Add: "As soon as you have a minimal working file + 1 reference doc, commit + push + open PR. Iterate via follow-up commits."
4. Explicit branch. Always pass `-b feat/<slug>-<role>` — never let the agent choose its own.

## What this doesn't fix

- Single-agent isolation: single `isolation="worktree"` spawns MAY work. Use the manual pattern anyway for consistency.
- `EnterWorktree` (operator-level): unrelated, works fine.
- The root-cause CC bug: Path A in #3224 — if fixed upstream, this whole pattern becomes deletable.

## References

- Yonatan-HQ/platform#3224 — tracking issue
- `feedback_agent_worktree_isolation_unreliable.md` — origin incident (2026-05-11 22:30 IDT)
- Yonatan-HQ/platform#3132 — sibling worktree-audit cron
- `src/skills/implement/references/manual-worktree-pattern.md` — full reference doc (this PR)