linear-adapter

Imported from dork-labs/marketplace (plugins/flow/skills/linear-adapter/SKILL.md). Install upstream with npx skills add dork-labs/marketplace --skill linear-adapter. Copyright stays with the author.

Linear Adapter — the v1 PMClient

Is this the adapter to use? A project can override this shipped adapter with its own, at .agents/flow/adapters/linear/SKILL.md. Before acting on anything below, run node --experimental-strip-types "<flow-root>/scripts/config-files.ts": if the adapter.path it prints is not this file, stop reading this one and read that file instead. If the check cannot run or its output cannot be read, stop.

Flow root. This skill lives at <flow-root>/skills/linear-adapter/SKILL.md. If you reached it via a symlink (.claude/skills/flow__* or .agents/skills/flow__*), resolve the real path first (realpath <path>): the flow root is two directories above the skill directory. Every <flow-root>/... reference below is relative to that root.

What this is. The /flow engine's work model + tracker adapter. It is the v1 realization of the PMClient contract (spec §3): it normalizes Linear into one generic WorkItem shape and fulfils every capability verb, so every generic stage skill and the dispatch policy can work without ever touching a Linear-specific field or a tracker API string.

This is a prose contract, not code. In v1 there is no DorkOS server and nothing imports a TypeScript adapter at runtime — the engine is server-free and skill-based. The agent reads this skill and follows it. The typed interface PMClient documented in ../../SPEC.md is what the P5 server build promotes this prose contract into. Building a TS adapter class now would be dead code (this repo forbids dead code), so we do not.

The one rule

All /flow tracker I/O lives here. No other flow skill or /flow:* command may contain a mcp__linear__* / mcp__plugin_linear_linear__* string, a composio invocation, or a LINEAR_* slug. Generic stage skills call this skill ("via the linear-adapter, claim DOR-123") instead of touching the tracker. This gives the agnosticism win ("all Linear in one place") and a single audit surface for every tracker write (spec §Security). An executable grep guard (packages/flow/src/__tests__/tracker-confinement.test.ts) enforces this for the flow bundle.

The P5 server build swaps this skill for a typed PMClient; a second adapter (Jira / GitHub Issues) proves the agnosticism. Because the generic layer only ever speaks WorkItem + the verbs, that swap is additive, not a rewrite.

Accessing Linear — the connection is config-driven

The adapter hardcodes no team, workspace, or account. It reads WHERE and HOW it reaches Linear from config, fresh on every run — so pointing flow at a different team, workspace, or account is a config edit, never a change to this skill:

Both settings files live in the project, never in the plugin: .agents/flow/config.json (committed policy) and .agents/flow/config.local.json (this machine's credentials and coordinates, ignored by git; in a git worktree it may be the main checkout's copy). Run node --experimental-strip-types "<flow-root>/scripts/config-files.ts" and read the committed and local paths it prints; never guess them. Values in the local file override the committed one.

/flow:init sets all of these. A real team key/id and workspace slug live in the gitignored config.local.json, never in the shared committed config — a concrete id baked into the shipped template would re-hardcode the agnosticism this seam exists to preserve. Below, <teamKey>, <teamId>, <workspaceSlug>, and <trackerAccount> stand in for those configured values.

Two transports, selected by connection.transport

Both paths reach the same team and workspace; connection.transport decides which is primary. The adapter is the only place either path appears.

cli (the default) — the Composio CLI, account-pinned. Works even when the MCP server is unauthenticated (see the composio-cli skill). Linear slugs are LINEAR_*. Always pass --account "<trackerAccount>", read fresh from .agents/flow/config.local.json → secrets.trackerAccount (set by /flow:init); never hardcode an account name here. This is the safe default precisely because the acting identity is pinned by config: any other connected account — a maintainer's personal login, or unrelated artblocks work — must never receive flow's writes, and the --account "<trackerAccount>" flag is the only thing keeping them out (there is no team filter on the list slug — see below). An adopter points flow at a dedicated bot account by setting trackerAccount, not by editing this skill.

composio execute LINEAR_LIST_LINEAR_TEAMS    --account "<trackerAccount>" -d '{}'
composio execute LINEAR_LIST_LINEAR_PROJECTS --account "<trackerAccount>" -d '{}'
# Discover other slugs by intent:
composio search "list linear issues" "create a linear issue" --toolkits linear

mcp — the in-session Linear MCP server. Tool names are mcp__plugin_linear_linear__* (e.g. list_issues, save_issue, save_comment, get_authenticated_user); the prose shorthand for the family is mcp__linear__*. It is faster and richer than the CLI, but it carries a real footgun the cli path does not:

The MCP server acts as whoever authenticated (OAuth'd) it — which is NOT necessarily secrets.trackerAccount. Unlike the CLI, the MCP transport takes no --account flag; its acting identity is fixed at OAuth time. If the MCP is authenticated as a different identity than trackerAccount, every flow write silently lands as that OAuth identity — the exact silent-wrong-account failure the account-pinned cli path prevents.

So before you use mcp for any write: confirm the MCP is authenticated as the same identity as secrets.trackerAccount — read get_authenticated_user and check it matches the configured account. If the server is unauthenticated, run mcp__linear__authenticate and complete OAuth as that account. If it is authenticated as a different account, do not write through MCP — fall back to the cli transport (which is account-pinned) rather than acting as the wrong identity.

Query hygiene (applies to every read):

• MCP only: always pass includeArchived: false on list_issues — Linear defaults to true, pulling archived noise from deleted projects. The Composio LINEAR_LIST_LINEAR_ISSUES has no include_archived param (see the schema gotcha below); passing it errors on a paginated call.
• Do not pass includeMembers: true on list_projects — it triggers GraphQL query-complexity errors. Fetch member/lead detail separately.

Composio CLI — verified schemas, response shapes & gotchas

The Composio fallback diverges from the MCP transport in ways that bite silently. These are empirically verified against composio v0.2.31 and the live DorkOS workspace; trust them over a slug's --get-schema guess when they conflict.

• Prefer one GraphQL read over the field-poor list slug. LINEAR_RUN_QUERY_OR_MUTATION is the richest read path and resolves the two worst traps below (missing category, flattened labels) in a single call — request state{ name type } for the category and labels{ nodes{ name parent{ name } } } to recover the namespace (reconstruct agent/ready as parent.name + "/" + name; ready→parent:agent, research→parent:type). It also returns estimate (size) and priority, and accepts a label filter (issues(filter:{ labels:{ name:{ eq:"ready" } } })). The result nests under .data.data.team (note the double data). Reach for the per-verb slugs below for writes and simple lookups; reach for GraphQL when you need the full dispatch-ready shape.

• LINEAR_RUN_QUERY_OR_MUTATION's input key is query_or_mutation — not query. The payload is -d '{"query_or_mutation": "<the query>", "variables": { … }}'. A query key fails Composio's own schema validation with Unknown key before the call ever reaches Linear, so the error names your payload, not your GraphQL (verified against composio v0.2.31, 2026-09-09).

• Team scope is the adapter's job on every read — nothing in the API supplies it. getBacklogSnapshot and getEligibleWork are team-scoped reads: the team is the configured connection.team.id / connection.team.key, never "whatever the account can see". Via GraphQL, scope through the team node — team(id: "<teamId>") { issues(…) } — and never a top-level issues(…). Via the field-poor list slug there is no team filter to pass at all (see below), so post-filter the results by identifier prefix (<teamKey> + -) before any policy or write pass consumes them. A workspace holds many teams — the reference workspace has five, one of them a user-feedback intake team whose issues are live conversations with real people — so an unscoped read hands the groom's write pass items it must never relabel, close, or reassign (verified hazard, 2026-09-10).

• Slugs are doubly-prefixed; there is no LINEAR_GET_ISSUE. The verbs are LINEAR_LIST_LINEAR_ISSUES, LINEAR_GET_LINEAR_ISSUE, LINEAR_LIST_LINEAR_PROJECTS, LINEAR_GET_LINEAR_PROJECT, LINEAR_LIST_LINEAR_TEAMS, LINEAR_LIST_LINEAR_LABELS, LINEAR_LIST_LINEAR_STATES. The un-doubled LINEAR_GET_ISSUE does not exist (ToolRouterV2_ToolNotFound). When a slug 404s, rediscover it with composio search "<intent>" --toolkits linear.

• getCurrentUser is LINEAR_GET_CURRENT_USER, not LINEAR_GET_AUTHENTICATED_USER. The second is the MCP tool name with a Composio prefix, and Composio answers it with ToolRouterV2_ToolNotFound. Pass -d '{}'. The user usually comes back under .data.user, but the wrapper can nest it elsewhere, so check the keys before reading id and name, and throw if no user object is found. If the slug call fails, the same read is query { viewer { id name } } through LINEAR_RUN_QUERY_OR_MUTATION (verified against composio v0.2.31, 2026-09-15).

• LINEAR_GET_LINEAR_ISSUE takes the human identifier — -d '{"issue_id":"DOR-149"}', no UUID needed. It returns the fields the LIST call omits: state.type (the category), estimate (the size), priority, labels.nodes, project, parent. Caveat: its relations field comes back null via Composio — the typed blocks/blockedBy graph that feeds dispatch eligibility is not reliably populated. A null here means unknown, never "no blockers": "neutral" is only how the dispatch policy ranks an absent graph (see Graceful degradation), and reading it as a finding is how a blocked item gets claimed. Cross-check the graph the reliable way before any decision rests on it.

• The relation graph has exactly one reliable read: GraphQL, through the team node. For any decision that depends on the graph — dispatch blockers, a duplicate adjudication, a cross-team sweep — request relations { nodes { type relatedIssue { identifier state { type } } } } (plus inverseRelations for the incoming edges) inside team(id: "<teamId>") { issues(…) } via LINEAR_RUN_QUERY_OR_MUTATION, and treat every other path's answer as unknown (verified 2026-09-09). The cross-team case is the one that bites: a related issue's identifier carries its own team prefix, so an edge can point out of the configured team. Read those edges — "blocked by another team's item" is exactly what the graph is for — but never write to the far end of one: the sweep's scope stays the <teamKey>-prefixed items, and the related issue is evidence, not work.

• LINEAR_LIST_LINEAR_ISSUES has a tiny filter schema — no team filter. Allowed top-level keys are only after, first, project_id, assignee_id, original_cursor, include_transitions, cursor_was_corrupted. There is no team_id (passing it is silently dropped on the first call and hard-errors on a paginated one) and no include_archived. Scope to a project with project_id; there is no team scoping at all, and the unfiltered list is WORKSPACE-wide, not team-scoped. One account reaches every team in the workspace it connects to (connection.workspace.slug), so --account "<trackerAccount>" prevents cross-account leakage only — it is what keeps any other connected account (e.g. artblocks) out, and it is not a team filter. Post-filter by identifier prefix, per the team-scope rule above (verified against a five-team workspace, 2026-09-10 — an account that connects to one workspace is not thereby scoped to one team).

• Response shapes: list → .data.issues[] + .data.page_info{ hasNextPage, endCursor } (not .data.items); get → .data.issue; projects → .data.projects[]; teams → .data.teams[]. When a call needs the team id, use the configured connection.team.id (resolve it from connection.team.key via LINEAR_LIST_LINEAR_TEAMS if it is not set); never inline a literal id here.

• Large reads spill to a file. A big result returns { successful: true, storedInFile: true, outputFilePath, tokenCount } with no inline data — read outputFilePath with jq (don't slurp it into context). Paginate by passing { first, after: <endCursor> } and only those keys (adding any filter key to an after call trips schema validation).

• Labels arrive FLATTENED to leaf names. A grouped Linear label surfaces on the issue as its bare leaf: ready (not agent/ready), claimed/completed/ needs-input (not agent/*), verify/ideate (not stage/*), task/research/idea/meta (not type/*). The group prefix is a separate parent label that is not present on labels.nodes. This is a real normalization trap: the dispatch policy (node --experimental-strip-types "<flow-root>/scripts/dispatch.ts") matches the literal agent/ready, so a raw Composio ready will silently fail eligibility. The adapter MUST re-namespace leaf → group before handing labels[] to the policy. Recover the group↔leaf map from LINEAR_LIST_LINEAR_LABELS (team-scoped; distinguishes container vs leaf labels).

• The category (state.type) is absent from the LIST call. A listed issue's state is { name } only — no type. Since the generic layer matches on category, resolve it via LINEAR_GET_LINEAR_ISSUE per item, or once via LINEAR_LIST_LINEAR_STATES (a team-scoped name → type map). A triage-type state is real here (see the category table's † note).

• Project state is null via Composio. LINEAR_LIST_LINEAR_PROJECTS returns { id, name, state: null } — the project workflow-state category is not populated, so the dead-project dispatch tier degrades to a no-op (the documented graceful-degradation behavior; here it is always neutral).

• Comment-writes on ARCHIVED issues fail with a misleading error. commentCreate (via LINEAR_CREATE_LINEAR_COMMENT or raw GraphQL) on an archived issue returns Entity not found: Issue — while issue(id:) reads and even issueUpdate on the same UUID still succeed, so the error looks like a bad id or a missing OAuth scope. It is neither (verified 2026-07-13, DOR-306). When a comment-write returns "Entity not found" on a UUID that reads fine, check the issue's archivedAt via GraphQL before suspecting scopes or transposed UUIDs. Archived issues stay out of normal flow via the includeArchived: false hygiene rule; this bites only when an item is addressed directly by identifier.

• LINEAR_CREATE_LINEAR_COMMENT wants camelCase issueId — unlike LINEAR_GET_LINEAR_ISSUE's snake_case issue_id. Allowed keys: body, issueId. The casing convention varies per slug; trust the validation error's allowed-keys list.

• LINEAR_LIST_COMMENTS cannot filter by issue. Its only keys are after, first, before, includeArchived. To read one issue's comments back (the round-trip check), use LINEAR_GET_LINEAR_ISSUE — its comments.nodes carries them — or a GraphQL issue(id:){ comments { nodes { id body } } }.

• Text search is GraphQL-only; no LINEAR_SEARCH* slug is worth reaching for. The working pattern is one LINEAR_RUN_QUERY_OR_MUTATION read: searchIssues(term: $q, first: N, includeArchived: false) { nodes { identifier title state { type } } } (verified 2026-09-09). It searches the whole workspace and returns cross-team results, so scope or post-filter it by identifier prefix exactly as for the list slug before a policy or write pass touches the hits — search is the easiest place to pull another team's issues in by accident.

Building the groom snapshot (getBacklogSnapshot() via Composio)

Verified against the live workspace during the first groom (2026-08-03); team-scoping corrected 2026-09-10.

• Every pull goes through the team node. All three issue pulls below — core fields, the relation graph, and the closed titles — are team(id: "<teamId>") { issues(…) }, never a top-level issues(…). This is not hygiene: the groom's write pass ingests whatever the snapshot contains, so a snapshot carrying a sibling team's items lets it relabel, cancel, or reassign issues that are user-facing communication surfaces — a user-feedback intake team's items are somebody's open conversation, not backlog (verified hazard, 2026-09-10). Check the pulled identifiers all carry the <teamKey> prefix before handing the snapshot on.
• The GraphQL complexity cap is 10000, and relations are expensive. A plain-field team(id:) { issues } query paginates fine at first: 150-250; adding relations + inverseRelations + children costs roughly 230 points per issue, so the relation pull needs first: 40 or less. Build the snapshot as two paginated team-scoped pulls merged by identifier — core fields at 150, the relation graph at 40 — rather than one query that trips the cap.
• Pull closed items separately as titles only, through the same team node (team(id:) { issues(filter: { state: { type: { in: ["completed","canceled"] } } }, first: 250) }) — the duplicate/shipped matching passes need names, not full bodies.
• Re-namespace labels (leaf → family/leaf) and resolve state categories exactly as for getEligibleWork; project state DOES come back on a direct GraphQL projects query (unlike LINEAR_LIST_LINEAR_PROJECTS), so prefer GraphQL here — the groom's dead-project checks (GRM-9/GRM-11) need it. A project is a workspace-level object and can span teams, so narrow the project set to the ones the snapshot's own items reference rather than handing the groom every project the account can see.

Bulk-write traps (the groom write pass)

Each of these cost a failed batch on 2026-08-03; none produces a helpful error:

• A literal $word anywhere in an inlined mutation string breaks the call. Composio scans the whole query text for $identifier and demands a matching GraphQL variable, so a description containing a shell snippet or template literal ($sessionId, ${client}) fails with "Query contains variable syntax for: X". Pass all prose through real GraphQL variables — mutation($id: String!, $desc: String!) { issueUpdate(id: $id, input: { description: $desc }) { success } } — never string-interpolated into the query body.
• A description write REPLACES the whole field — including any signature already in it. Read the current description, strip any agent:provenance / flow:provenance line, then write the new body with exactly one signature as its last line. Appending without stripping leaves two signatures in one field and no rule for which a reader should believe. Note that the signature's JSON can legitimately contain a $, so it goes through a real GraphQL variable like any other description prose (see the trap above).
• A label write REPLACES the entire label set. issueUpdate's labelIds is not additive. Compute the union against a fresh read taken immediately before the write — a union computed from an earlier snapshot silently deletes labels a concurrent session added in between (observed live: another session's labels appeared mid-groom).
• Aliased mutations partially apply. A failed alias does not roll back its siblings. Batch 5-10 aliases per call, check each alias's success in the response, and re-read a sample after every batch.
• Project state accepts only backlog | planned | started | completed | canceled. paused is rejected with "No project status found for type paused" even though Linear the product has the concept. Use backlog for "real work, not shipped, not active".
• projectCreate rejects a description longer than 255 characters — "description must be shorter than or equal to 255 characters" (verified 2026-09-10). A project's description is a one-line summary field, not a body, so a programme charter pasted into it fails the whole mutation. Write a single sentence there and put the long prose — the ## Goal / ## Scope / ## Anchor & provenance sections of <flow-root>/templates/records/project.md — on the project's umbrella issue (the type/meta anchor), which has no such cap.
• Never close a project out by hand. Moving a project to completed/canceled goes through the completeProject verb (writes table above), which owns the open-issues guardrail and the live-data check that goes with it. Bulk passes are exactly where that check gets skipped, and a wrongly-closed project hides its open issues from dispatch permanently.

The WorkItem normalization shape

Every read verb returns work normalized into this shape, so the generic layer never sees a Linear field name. The adapter's job is the mapping in the third column.

WorkItem {
  id,              // tracker-native id (Linear node id)
  identifier,      // human key, e.g. "DOR-123" — the worktree/branch key
  title,
  description,
  type,            // idea|research|hypothesis|task|monitor|signal|meta
  stateCategory,   // backlog|unstarted|started|completed|canceled
                   //   MATCHED ON CATEGORY, NEVER ON DISPLAY NAME (see below)
  stateName,       // display only ("In Progress", "Triage", …) — never matched on
  priority,        // 0–4  (0 none · 1 urgent · 2 high · 3 medium · 4 low)
  size,            // number (points, native) | string (t-shirt) — promotion + ranking
  project,         // { id, name, stateCategory, lead }
  parent,          // parent WorkItem id (sub-issue) or null
  relations {      // the dependency graph — read from typed Linear relations
    blocks[],      // items THIS blocks
    blockedBy[],   // items that block THIS  (feeds dispatch eligibility)
    children[],    // sub-issues
    relatedTo[],
    duplicateOf?,
  },
  labels[],        // ALL labels, including stage/* and agent/*
  assignee,        // → classifyOwnership(): mine|reviewer|other|unassigned
  agentDisposition // ready|claimed|completed|needs-input  (derived from agent/* labels)
}

stateCategory is matched on CATEGORY, never on display name

Linear workflow states each belong to one of five categories: backlog · unstarted · started · completed · canceled. The display name is team-customizable ("Triage", "In Progress", "Shipped", …) and varies per team — matching on it is brittle and breaks the moment a team renames a state. The generic layer therefore branches only on stateCategory; stateName is carried for display only. The adapter resolves a state to its category via list_issue_statuses (each status carries its type/category) and maps:

† Linear's Triage feature adds a sixth state type, triage, beyond the five StateCategorySchema values. It is the un-triaged holding state (an item that has not yet been classified or routed). Normalize it to backlog — non-terminal, so it lists and recovers like any open item — but note it is kept out of dispatch by the absent agent/ready label, not by its category: an un-triaged item carries no agent/* label, so filterEligible drops it regardless. Readiness (agent/ready) is produced by the shaping stages, not by this adapter and not by a state category: TRIAGE applies it on accept (both routes: simple readied for EXECUTE, complex readied for IDEATE; see triaging-work) and DECOMPOSE applies it to the execute-ready tasks it emits (see decomposing-work). The adapter's job is the category mapping above (moving an accepted item into a true backlog/unstarted state); producing the agent/ready signal that lets filterEligible pick the work up is the stage skills' job, so an item lacking it is held out of dispatch by the absent label, never by its category. Never fabricate a distinct triage category — the typed enum has only five values.

‡ Linear's Duplicate workflow state has type duplicate — a seventh state type that maps onto NOTHING in the generic model. An item parked there is unprojectable: neither open nor closed, invisible to the dispatch policy, the loop, and every backlog view (the first DorkOS groom, 2026-08-03, found six items stranded this way). The adapter must never normalize duplicate to a real category; it must flag these items so a groom routes them out.

Snapshot-time obligations (the two Linear-only groom checks). The generic audit-backlog.ts oracle is tracker-neutral, so two Linear-specific conditions are this adapter's job to surface whenever it builds a getBacklogSnapshot():

1. Items in a triage-type state are un-triaged intake. A groom must route every one of them out (to a real backlog/todo state, with a type/* label) — nothing stays in Triage after a groom.
2. Items in the duplicate-type state must leave it: verify the duplicate target still makes sense, create a real duplicate relation via link, then move the item to a canceled-category state. If verification shows the item is actually live unfinished work, move it to a real open state instead — never leave anything in the unmappable state either way.

type, agentDisposition, priority, size mappings

• type ← the type/* label group (idea, research, hypothesis, task, monitor, signal, meta). Mutually exclusive — exactly one per issue.

• agentDisposition ← the agent/* label group: agent/ready → ready, agent/claimed → claimed, agent/completed → completed, agent/needs-input → needs-input. The agent/* labels are the durable state machine (spec §3, the Huginn durability lesson) — not the ephemeral plan/checklist field, which does not survive a restart.

• priority ← Linear's native priority field (0 none, 1 urgent, 2 high, 3 medium, 4 low). Native field, never a priority/* label.

• size ← Linear's native estimate field, passed through as the number Linear gives you (Linear's estimate is numeric on every scale it offers — Fibonacci, exponential, linear). Native field, never a label. Do not stringify it and do not convert it to a t-shirt letter. Drives the dispatch size tier and the sub-issue promotion rule.

  size is a union by design: number | string. A tracker with a numeric estimate emits the number; a tracker with no numeric field emits a t-shirt string (xs · sm · md · lg · xl · xxl). The dispatch policy maps both onto one shared ordinal scale, so an adapter never has to invent a conversion. Emit your tracker's native shape unconverted.

  Never compare a size to a threshold directly. decomposition.subIssueThreshold is a t-shirt word ("xl" by default), so on a numeric estimate size ≥ threshold would be comparing two different vocabularies — 8 ≥ "xl" is not a question either side can answer. Compare ordinals, which is the whole point of the shared scale:

  sizeOrdinal(item.size) >= sizeOrdinal(decomposition.subIssueThreshold)
  

  sizeOrdinal is exported from @dorkos/flow (dispatch-policy.ts) and resolves both vocabularies onto one scale — sizeOrdinal(8) and sizeOrdinal("xl") are both 4. An absent or non-conformant estimate returns undefined (neutral), and a neutral size never promotes. Use it rather than inventing a numeric→t-shirt conversion in your adapter.

Presenting a work item to a human

Every WorkItem this adapter returns carries title alongside identifier, so the title is always in hand with no extra fetch. Never surface a bare tracker key to a human reader. Whenever a stage skill, a /flow command, or the loop reports a work item to a person (terminal output, a status line, a report, an AskUserQuestion option, a PR or commit body), render the identifier followed by the title:

DOR-157 - Connect Claude Code account

• Order + separator. Identifier first, then a space-hyphen-space, then the title. The hyphen keeps the line readable when the title itself contains a colon (DOR-149 - Harness portability: dry-run loop). If a title is long or unwieldy, a 3-6 word summary may stand in for it, but the bare DOR-157 alone is never acceptable.
• Link the identifier, not the title. Where the surface supports a link, the identifier is the anchor and the title stays plain text, so variable title punctuation can never break link parsing. The structure is identical on every surface; only the link syntax adapts:
  • Markdown and Obsidian: [DOR-157](<issue-url>) - Title (a standard link, never an Obsidian [[wikilink]], since the target is an external tracker URL).
  • HTML: <a href="<issue-url>">DOR-157</a> - Title.
  • Slack mrkdwn: <<issue-url>|DOR-157> - Title.
  • Auto-linking surfaces (Linear, GitHub, Slack with the Linear app): the bare DOR-157 - Title already links the key, so do not double-link.
• Tracker comments are exempt. Comments this adapter posts live inside the tracker, whose own UI already shows the title, so pairing there is redundant. This convention governs agent-to-human surfaces outside the tracker.

The 18 capability verbs

Each verb is mapped to its concrete Linear MCP call (primary) and Composio fallback. The generic layer only ever names these verbs; the adapter owns the call. Nine reads + nine writes: the contract's 16 required verbs (../../adapters/SPEC.md section 3), the groom-only getBacklogSnapshot read this adapter adds on top, and the contract's optional completeProject, which this adapter supports. (An earlier revision titled this section "13" while the table already held more — the table is authoritative.)

Reads

Writes (all confined here; the single audit surface)

completeProject is the contract's one optional verb (contract 1.1.0, SPEC section 3, Optional verbs). This adapter declaring it supported is what lets a caller name it — and a caller must still carry its own fallback, since another tracker's adapter may not support it. One honest caveat on that declaration: the Composio binding is the verified path, while the MCP tool name has not been exercised against a live server. Before the first write on the mcp transport, list the server's tools and find the project-write sibling of save_issue — save_project on this server family, update_project on an older one. If neither is there, the server cannot write projects: treat the verb as unsupported on that transport and use the cli path instead.

Slugs shown in the Composio column follow the LINEAR_* convention; confirm the exact slug with composio search "<intent>" --toolkits linear if a call errors — Composio occasionally revises slug names. LIST_LINEAR_TEAMS and LIST_LINEAR_PROJECTS are confirmed in use today.

Provenance: signing outward writes

Every body this adapter writes outward — every comment, the needsInput question, any description it authors — carries a hidden, machine-readable signature line as its last line, so a later reader can route a follow-up back to the session that wrote it:

<!-- agent:provenance {"v":1,"harness":"claude-code","sessionId":"…","account":"work","host":"…","surface":"dorkos"} -->

The canonical spec is ../../docs/provenance.md — read it there and do not redefine it here. It owns the marker name, the eight wire fields, the per-write cadence, the omit-never-fabricate and valid-JSON discipline, the never-an-email rule, the public-repository rules, the emission list, and the reader rules. It is tracker-neutral on purpose: every adapter signs the same way, so a reader can parse a signature without knowing which tracker produced it. Readers also accept the legacy flow:provenance name; this adapter never emits it.

What belongs here is the part that is specific to this tracker:

• Round-trip verified. This tracker preserves HTML comments byte-for-byte in both issue descriptions and comment bodies — confirmed by API round-trip on both surfaces. So the signature survives a write→read cycle intact and the reader rules can rely on it.
• A human editing in the rich-text editor can strip the line. The tracker's editor is rich-text, not raw markdown, and a person editing around a hidden comment can drop it without noticing. That is expected, and it is why the reader rule treats a missing signature as "route as unsigned" rather than as evidence about the session.
• Description writes go through the $word and replace-whole-field traps documented u

*Truncated - read the full file at https://github.com/dork-labs/marketplace/blob/acb056543f0008db68db32df8c4e03108812c81c/plugins/flow/skills/linear-adapter/SKILL.md.