Linear setup

Linear is the source of truth for tickets, dependencies, and epic plans. Mainark reads from Linear; it does not replace Linear for human product management.

Blocking relations

Set native Linear blocked by relations when creating issues:

• FUL-419 blocked by FUL-576
• FUL-578 blocked by FUL-420

Mainark's parallel bootstrap topologically sorts from these edges. Do not encode dependencies in ticket prose or repo files.

Spec → Linear (Cursor skill)

When pushing tickets via the spec-to-linear skill:

• Pass blockedBy: ["FUL-576"] in save_issue during Pass 2
• Never add "depends on FUL-576" inside Requirements or Acceptance Criteria

Epic plans

For phased epics, put ## Mainark plan in the epic Linear description (FUL-416, not each child):

## Mainark plan

### Phase 1 — Operator surface
checkpoint: merge
- FUL-576  base: main
- FUL-577  base: stack

### Phase 2 — Policy migration
checkpoint: merge
stack: true
- FUL-419  base: main
- FUL-420  base: stack
- FUL-578  base: stack

Validate without running agents:

mainark plan FUL-416
mainark implement FUL-416 --dry-run

Linear may rewrite markdown bullets (- → *); Mainark's plan parser accepts both.

Active epics (target repo)

Optional: .mainark/epics.json in the target repo marks which epics are active for mainark queue / mainark next:

{
  "version": 1,
  "epics": [
    { "id": "FUL-416", "active": true },
    { "id": "FUL-355", "active": true }
  ]
}

This is a pointer, not a copy of the plan or blocker graph.

Orchestrator-managed label

The backend orchestrator (mainark dev) ingests issues with the orchestrator-managed label.

CLI mainark implement uses Linear Todo state (and optional MAINARK_IMPLEMENT_LABEL). You can run parallel CLI work without that label.

What stays in Linear only

See Anti-patterns.

Multi-track work

Independent tracks (e.g. FUL-416 and FUL-355) are separate epic graphs in Linear. Run:

mainark implement FUL-416 --no-ship
mainark implement FUL-355 --no-ship

Avoid editing the same functions in both tracks in the same week when possible.