Git worktrees

Mainark isolates parallel agent work with one git worktree per Linear issue.

Rule

One issue → one worktree → one branch → one PR loop.

Agents never implement two tickets in the same checkout.

Layout

Default parent directory (sibling of the target repo clone):

~/fulreach/                 ← MAINARK_ROOT / target repo
~/wt-fulreach/              ← MAINARK_PARALLEL_BASE (default)
  FUL-576/                  ← worktree for that issue
  FUL-419/
  FUL-578/

Override with MAINARK_PARALLEL_BASE.

Registry file: .mainark/parallel.json — slots, branches, paths, stackBase, wave numbers.

How worktrees are created

mainark implement (via parallelBootstrap) topologically sorts issues from Linear blockedBy, then:

1. Root issues (no open blockers): worktree from origin/main (or main)
2. Dependent issues: worktree branch starts from the blocker's branch (stack mode)

Commands:

mainark parallel clean              # remove registered worktrees
mainark parallel FUL-407 FUL-409    # setup only (no agents)
mainark parallel paths              # print cd paths for each slot
mainark parallel list               # registry summary

Agent execution

Each worktree gets:

• .mainark/issue.json — manifest (identifier, title, stackBase)
• .mainark/implement-FUL-N.md — ticket body for the agent
• .mainark/logs/implement-FUL-N.log — agent log

Implement agents run inside the worktree directory, not the primary clone.

Pre-push review

Before the first push, Mainark runs local review in each worktree (validate → Claude review → fix loop). Artifacts: .reviews/local-FUL-N.json in that tree.

Only after local pass does ship push and open PRs.

Cleanup

mainark parallel clean

Run this before a fresh parallel wave if the registry is stale or slots failed mid-run.

Do not manually delete ../wt-* directories without parallel clean — the registry will drift.

Common mistakes

See also Stacked PRs.