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:

Root issues (no open blockers): worktree from origin/main (or main)
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. mainark implement FUL-… will refuse if .mainark/parallel.json still has worktrees that are not in this command.

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

Common mistakes

Mistake	Fix
Running `mainark fix` in the wrong directory	Always `cd` to the slot path from `mainark parallel paths`
Editing the primary clone while parallel run is active	Work only in worktrees until ship
Reusing one branch for two issues	One FUL id per branch per slot
Starting `implement` while another batch is still in `parallel.json`	`parallel list`, then `clean` or `remove` leftovers (or `--append`)
`parallel ship` / `agents` with no ids while the registry is non-empty	Pass the issue ids, or `--append`