Parallel agent work — overview

Mainark runs multiple Linear issues in parallel without branch mix-ups by giving each issue its own git worktree and, by default, stacked pull requests on GitHub.

Two execution paths

For multi-issue epics with dependency chains (e.g. FUL-576 → FUL-419 → FUL-578), use the CLI path until stacked PR support lands in the orchestrator.

Mental model

Linear (issues + blockedBy + optional ## Mainark plan)
        ↓
mainark implement / parallel bootstrap
        ↓
Per issue: worktree + branch + agent + local review
        ↓
mainark publish → stacked PR on GitHub
        ↓
You review & merge → unblocks next wave

Linear owns tickets, human states, and blocker relations.
Mainark owns worktrees, agent runs, review loops, and PR publication.
GitHub owns code review and merge.

Do not duplicate ticket graphs under .mainark/plans/ or repo-local bash wave scripts — see Anti-patterns.

When to use parallel implement

Use mainark implement when:

• Several Todo issues are ready (or you pass explicit FUL ids)
• Linear blocking relations are set (FUL-411 blocked by FUL-407)
• You want stacked PRs (dependent PRs target the blocker branch, not main)

Use mainark implement --no-ship when you want agents to finish locally without push/review until you inspect diffs.

Use mainark implement --no-stack only for legacy merge-first waves (everything branches from main; wait for merge between waves).

Epic phases

Epics with ## Mainark plan in the Linear description run phase by phase with merge checkpoints:

mainark plan FUL-416              # parse plan, no side effects
mainark implement FUL-416         # current phase
mainark implement FUL-416 --resume  # after phase PRs merged
mainark implement FUL-416 --parallel  # current phase via worktree stack

See Linear setup for plan format.

Monitoring

CLI parallel state lives in .mainark/parallel.json in the target repo. Orchestrator state lives in server SQLite + /issues UI.

Next steps

• Git worktrees
• Stacked PRs
• Commands