Mainark documentation

Mainark turns tickets into reviewed, stacked pull requests using isolated git worktrees and AI agents.

Guides

Parallel agent work

Start here if you run multiple features or epics at once.

1. Overview — mental model and when to use what
2. Git worktrees — one tree per branch per PR
3. Stacked PRs — dependency chains on GitHub
4. Linear setup — blockers, plans, what stays in Linear (current SoT; see ADR-001 for exit plan)
5. Commands — CLI cheat sheet
6. Anti-patterns — what not to add to target repos

Architecture

• ADR-001: Mainark owns the task graph — SQLite default (Phase 4); Linear opt-in rollback. Storage choice and offline requirement superseded by ADR-005
• TaskProvider boundary — default TASK_BACKEND=sqlite
• Backend spike (Phase 2) — Beads design review; "SQLite prior stands" superseded by ADR-005
• Cloud fix executor — review fixes via Cursor Cloud on the PR branch
• Ledger failure policy — classification, backoff and escalation for agent_runs
• Continuous dispatch — coordinate --watch --auto-dispatch, capacity and backoff
• Plan inbox — plan in Cursor (desktop, phone, Slack), Mainark imports and starts it
• Auto-review recovery — finished vs killed review loops, orphan restart
• Agent supervision — deadlines, retries and fallback around every agent CLI call
• PR comments — each round posts its commits, test run and Claude's review to the PR
• Cost guards — every limit on spend in one table, including the daily cap
• Self-hosted worker — route cloud agents to our own machine with MAINARK_CLOUD_ENV
• ADR-003: Incidents — health contract, incident model, detect → diagnose → fix → verify (proposed)
• ADR-004: Goals and Tasks — domain vocabulary, recursive Goals, Tasks as executable leaves, merged vs done (accepted; amended by ADR-005)
• ADR-005: Control plane on Postgres — one Postgres database for every Product, invariants in the schema, reconciliation of the SQLite copies, cutover and rollback (accepted; not yet implemented)
• Product architecture map + gaps — snapshot ingest, deterministic gaps, /architecture UI (phase 1–2)

Reference

• Local CLI — install, review loop, env vars (developer reference)
• HTTP API — standalone server, bearer auth, issues + architecture ingest

Audiences