@llodev/pm-tasks-linear 0.0.0-pr-48-70482cb

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLDev Information Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+<!-- readme-selector:start -->
+<p align="center">
+  <a href="https://github.com/llodev/skills/blob/main/skills/pm-tasks-linear/README.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/usa.svg" width="30" alt="English"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/pm-tasks-linear/docs/i18n/README.pt-BR.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/brazil.svg" width="30" alt="Português"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/pm-tasks-linear/docs/i18n/README.es-ES.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/spain.svg" width="30" alt="Español"></a>
+</p>
+<!-- readme-selector:end -->
+
+# @llodev/pm-tasks-linear
+
+[![npm](https://img.shields.io/npm/v/@llodev/pm-tasks-linear?color=blue)](https://www.npmjs.com/package/@llodev/pm-tasks-linear)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Linear adapter for the `@llodev/pm-tasks-*` family. Publishes generic cards as Linear issues and dispatches CRUD operations through the [Linear MCP](https://linear.app/docs/mcp). The **first** pm-tasks family adapter to implement `task.sprint.set` (via Linear cycles).
+
+## Install
+
+```bash
+npm install @llodev/pm-tasks-linear @llodev/pm-tasks-core
+# or
+pnpm add @llodev/pm-tasks-linear @llodev/pm-tasks-core
+```
+
+## Setup the MCP
+
+Linear uses the **Linear MCP** over Streamable-HTTP at `https://mcp.linear.app/mcp`. The MCP handles OAuth — the adapter never sees tokens.
+
+For any MCP-capable agent (Claude Code, Cursor, Codex, Windsurf, Cline, Roo Code):
+
+- **Claude Code**: `claude mcp add linear -s project -- npx -y @linear/mcp-server` (or follow [Linear's MCP setup guide](https://linear.app/docs/mcp)), then approve the OAuth flow in your browser.
+- **Cursor / Windsurf / Cline / Roo Code**: add an MCP entry in that agent's settings pointing at `https://mcp.linear.app/mcp`.
+- **Codex**: add an `[mcp_servers.linear]` entry in `~/.codex/config.toml`.
+
+In Claude Code, verify with `claude mcp list` — `linear` should appear as authenticated.
+
+## Setup the config
+
+The `init` script enumerates your Linear team, states, labels, members, and estimation settings, then writes a `.linear.json`. Run it from within an agent session that already has the Linear MCP connected, or standalone with a Linear API key.
+
+**MCP-driven (recommended):**
+
+```bash
+npx @llodev/pm-tasks-linear init
+```
+
+Walk through the prompts. The script uses the Linear MCP to discover your team metadata — no credentials needed.
+
+**GraphQL standalone (no MCP):**
+
+Create a personal API key at [linear.app/settings/api](https://linear.app/settings/api), then:
+
+```bash
+export LINEAR_API_KEY=lin_api_...
+npx @llodev/pm-tasks-linear init
+```
+
+Pick where the config should live:
+
+- **local** → `./.linear.json` (recommended for project-scoped configs, can be committed).
+- **global** → platform default:
+  - macOS / Linux (XDG): `$XDG_CONFIG_HOME/llodev/pm-tasks/linear.json`, falling back to `~/.config/llodev/pm-tasks/linear.json`.
+  - Windows: `%APPDATA%\llodev\pm-tasks\linear.json`.
+  - Override with `LLODEV_PM_TASKS_CONFIG_HOME=/your/path`.
+
+The init prompt prints the absolute path it will write to.
+
+Run workspace health checks anytime with:
+
+```bash
+npx @llodev/pm-tasks-linear init --doctor
+```
+
+> [!IMPORTANT]
+> The API key is **only** used by `init` to discover your team metadata. The Linear MCP uses OAuth — never put the API key in `.linear.json`.
+
+## Use
+
+| Prompt example                                                   | What the agent does                                                   |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `"publish this plan as Linear issues"`                           | Phase 5 publish — parent issue + sub-issues + labels in batch         |
+| `"check sub-issue LEO-43"`                                       | Phase 6 CRUD — `checklist.check` (moves sub-issue to completed state) |
+| `"close LEO-42"`                                                 | Phase 6 CRUD — `task.close` (state resolved by type `completed`)      |
+| `"set the estimate on LEO-42 to 5 points"`                       | Phase 6 CRUD — `task.estimate.set` (effort → points + label `est:`)   |
+| `"move LEO-42 to LEO-12"`                                        | Phase 6 CRUD — `task.parent.set` (arbitrary depth)                    |
+| `"assign cycle 3 to LEO-42"`                                     | Phase 6 CRUD — `task.sprint.set` (resolve cycle by number)            |
+| `"[autonomous] create linear issues from plan @docs/plans/X.md"` | Phase 5b autonomous (requires `autonomous.enabled: true`)             |
+
+## Linear-specific notes
+
+**Sub-issues as checklists:** Linear has no native checklist. Checklist items from the generic card become **sub-issues** (`save_issue { parentId }`). `checklist.check` moves the sub-issue to a completed-type state — it does not edit description text.
+
+**States by type:** The adapter resolves states by type string (`unstarted`, `started`, `completed`, `canceled`) — never by name. State names are locale-dependent and team-customizable.
+
+**Single assignee:** Linear supports one assignee per issue. `task.assignee.add` is a set operation — it replaces the current assignee.
+
+**Label replace-set:** Any label write overwrites the full label array. The adapter always reads current labels before writing (read-modify-write). Never write labels without reading first.
+
+**Cycles = sprints:** `task.sprint.set` assigns an issue to a Linear cycle. Cycles are team-gated — enable them in team Settings before use. Returns `NOT_APPLICABLE` when cycles are disabled.
+
+**save_issue upsert:** When `id` is absent, `save_issue` **creates** a new issue. Always pass `id` on updates — omitting it silently creates a duplicate.
+
+## Documentation
+
+- [`SKILL.md`](SKILL.md) — full skill reference (routing, Linear model, all phases, CRUD verbs, result envelope)
+- [`references/operations.md`](references/operations.md) — verb → MCP tool mapping, task-ref resolution, error codes
+- [`references/estimation.md`](references/estimation.md) — estimation strategies, `est:<slug>` label idempotency
+- [`references/autonomous.md`](references/autonomous.md) — Linear autonomous mode scope and allowlist
+- [`anti-patterns/linear.md`](anti-patterns/linear.md) — NEVER rules for Linear
+- [`schemas/config.json`](schemas/config.json) — `.linear.json` schema
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: pm-tasks-linear
+description: >-
+  Linear adapter for the @llodev/pm-tasks-* family. Use when the user mentions
+  Linear, asks to "create Linear issue", "publish to Linear", "log to Linear",
+  "set cycle/sprint", "check sub-issue", or uses --publish-linear; OR for CRUD
+  on existing issues (check sub-issue, close, due-date, assign, comment,
+  estimate, parent, sprint); OR when invoked autonomously with [autonomous] /
+  --auto sentinel. Linear model: issue upsert via save_issue; sub-issues as
+  hierarchy AND checklist mechanism (parentId); states by type (unstarted/
+  started/completed/canceled); cycles = sprints (team-gated); single assignee
+  (set-not-add); labels are replace-set (est: idempotency read-modify-write).
+  MCP: Linear MCP (Streamable-HTTP, OAuth, mcp__linear__ prefix). Modes:
+  paste-ready, MCP publish, autonomous (write-through with allowlist),
+  plan-execution. Implements 10 verbs (task.create, task.move, checklist.check,
+  task.close, task.due-date.set, task.assignee.add, task.comment.add,
+  task.parent.set, task.estimate.set, task.sprint.set). FIRST family adapter to
+  implement task.sprint.set (via cycles). Requires @llodev/pm-tasks-core.
+license: MIT
+metadata:
+  version: 1.0.0
+  tags:
+    - agent-skill
+    - linear
+    - plan-to-tasks
+    - pm-tools
+    - linear-mcp
+  family: pm-tasks
+  role: adapter
+  tool: linear
+compatibility:
+  agents:
+    - claude-code
+    - cursor
+    - codex
+    - windsurf
+    - cline
+    - roo-code
+---
+
+# pm-tasks-linear
+
+Linear adapter for the `@llodev/pm-tasks-*` family. Publishes generic cards as Linear issues and dispatches CRUD verbs through the Linear MCP (`mcp__linear__*` tool prefix).
+
+## Routing
+
+| Trigger        | Signal                                              | Path                                     |
+| -------------- | --------------------------------------------------- | ---------------------------------------- |
+| Paste-only     | No MCP, no `.linear.json`                           | Phase 4 only — Markdown issue body       |
+| MCP publish    | Linear MCP connected + `.linear.json` present       | Phase 4 → 5 (create parent + sub-issues) |
+| Autonomous     | `[autonomous]` sentinel or `--auto` flag            | Phase 5b (write-through, no preview)     |
+| CRUD ops       | Verb on existing issue (`LEO-12`, UUID, or URL)     | Phase 6 — jump directly                  |
+| Plan-execution | Plan file path or `--plan-exec` with `.linear.json` | Phase 7 (discover + dispatch)            |
+
+## Linear model
+
+Linear issues have:
+
+- **Title** (required; aim for ≤80 chars for board readability).
+- **Description** (Markdown; MCP instructions require **literal newlines** — not `\n` escape sequences).
+- **State** — resolved by **type string** (`backlog`, `unstarted`, `started`, `completed`, `canceled`, `duplicate`). States are team-scoped and stored in `.linear.json`. **NEVER match by state name** — names are locale-dependent and change with team customization.
+- **Sub-issues** — `save_issue` with `parentId` = parent issue id. Arbitrary depth (unlike Jira's one-level Subtask). Sub-issues are both the **hierarchy mechanism** and the **checklist mechanism** (see Phase 4).
+- **Cycles** — Linear's sprint primitive. Team-gated (`config.cycles.enabled`). Resolved by name/number/id via `list_cycles`. `task.sprint.set` returns `NOT_APPLICABLE` when cycles are disabled.
+- **Single assignee** — `save_issue { assignee }`. Set-not-add — Linear supports only one assignee. Accepts id, name, email, or `"me"`.
+- **Labels** — **replace-set**: any label write overwrites the full label array. The transport always reads current labels, strips `est:*`, merges, and writes the complete set (read-modify-write). Never write labels without reading first.
+- **Identifiers** — `TEAMKEY-N` (e.g. `LEO-1`) or UUID are interchangeable on all MCP tools.
+
+**MCP transport:** Linear MCP at Streamable-HTTP (`https://mcp.linear.app/mcp`). The MCP handles OAuth — the adapter never sees tokens. All tools use the prefix `mcp__linear__`.
+
+**`save_issue` upsert:** 8 of 10 verbs collapse onto `save_issue`. When `id` is present → update. When `id` is absent → create. Omitting `id` silently creates a new issue — always pass `id` on updates.
+
+## Phase 4 — Linear formatting
+
+Apply the generic card from core's [`../pm-tasks-core/references/generic-card.md`](../pm-tasks-core/references/generic-card.md). Then map to Linear:
+
+- Title → issue `title`.
+- Sections of the generic card → Markdown headings in `description` (literal newlines, per MCP instructions).
+- Labels → resolve by name from `config.labels[]`; pass through raw strings otherwise.
+- Due date → `dueDate` (YYYY-MM-DD; sliced from ISO 8601). Native Linear field.
+- Assignee → `save_issue { assignee }` by id/name/email/`"me"`. Single-assignee set.
+- Estimate → `save_issue { estimate }` (numeric points) when `estimation.enabled` and `linearTarget === "points"`.
+- **Checklists → sub-issues (M3 resolution):** The core `task.create` contract carries no `items[]`. During Phase 5 MCP publish, the SKILL orchestrates child creation: for each checklist item in the generic card, call `save_issue` with `parentId` = the created parent issue's id. This is the doc-layer resolution — Linear has no native checklist, so checklist items become **sub-issues**. `checklist.check` later moves the sub-issue to a completed-type state via `save_issue { id: subIssueId, state: <completed-type-id> }`.
+
+## Phase 5 — MCP publish
+
+**Prerequisites:** Linear MCP connected in your agent.
+
+- **Claude Code**: `claude mcp add linear -s project -- npx -y @linear/mcp-server` (or follow [Linear's MCP setup guide](https://linear.app/docs/mcp)), then approve the OAuth flow.
+- **Cursor / Windsurf / Cline / Roo Code**: add an MCP entry pointing at `https://mcp.linear.app/mcp`.
+- **Codex**: add `[mcp_servers.linear]` in `~/.codex/config.toml`.
+
+In Claude Code, verify with `claude mcp list` — `linear` should appear as authenticated.
+
+Strict order: 5.1 read `.linear.json` → 5.2 resolve labels/members/states → 5.3 preview & approval → 5.4 publish → 5.5 error handling.
+
+MCP publish sequence:
+
+1. **Config discovery** — `requireConfig` loads `.linear.json` (see § Config for lookup order). Extract `team.id`, `states[]`, `labels[]`, `members[]`.
+2. **Resolve** — match label names to ids from `config.labels[]`; resolve assignee from `config.members[]` or pass-through; resolve target state from `config.states[]` by type.
+3. **Preview & approval** — show title, description excerpt, labels, assignee, estimate.
+4. **Publish** — `save_issue` (no id) → parent issue. Then one `save_issue` per checklist item with `parentId` = created id.
+5. **Confirm** — display issue identifier (`LEO-N`) + URL and each sub-issue identifier.
+6. **Error handling** — on MCP error, surface the raw error; no partial-commit guarantees (sub-issue creates are individual calls).
+
+### Attribution (opt-in)
+
+Before calling `save_issue`, read `config.attribution`. If `enabled === true`, append the `descriptionFooter` returned by `getAttribution()` to the end of `description`, and prefix comments with `commentPrefix`. In autonomous mode (`[autonomous]` sentinel), the `commentPrefix` automatically becomes the `autonomousCommentPrefix`. See [references/attribution.md in pm-tasks-core](../pm-tasks-core/references/attribution.md).
+
+## Phase 5b — Autonomous
+
+Skip 5.3 preview & approval. Apply the autonomous-mode contract from [`../pm-tasks-core/references/autonomous-mode.md`](../pm-tasks-core/references/autonomous-mode.md). Audit log entries per [`../pm-tasks-core/references/audit-log-format.md`](../pm-tasks-core/references/audit-log-format.md).
+
+Linear-specific autonomous scope: `autonomous.scope.teams` must list the target team id from `.linear.json`. Issue state transitions must be to types reachable from the current workflow (`config.states[]` is the allowlist). See [`references/autonomous.md`](references/autonomous.md).
+
+### Continuous operation in multi-task loops
+
+Mandatory when the controller executes a plan with multiple tasks autonomously. Mirror each task transition on the corresponding Linear issue in real time — NEVER batch state updates at end-of-loop. See [`../pm-tasks-core/references/autonomous-mode.md`](../pm-tasks-core/references/autonomous-mode.md) § **Continuous operation across multi-task loops**.
+
+Linear-specific verb mapping:
+
+| Transition        | Canonical verb + MCP call(s)                                                                                                                                                        |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Task started      | `task.move` → `save_issue { id, state }` (type `started`)                                                                                                                           |
+| Task completed    | `task.close` → `save_issue { id, state }` (type `completed`)                                                                                                                        |
+| Sub-issue checked | `checklist.check` → `save_issue { id: subIssueId, state }` (type `completed`) (idempotent)                                                                                          |
+| Task failed       | `task.comment.add` → `save_comment { issueId, body }` with failure mode + `task.assignee.add` to reassign for human escalation. Do NOT call `task.move(_, "done")` or `task.close`. |
+
+**Linear note:** `get_issue` returns current state but not the full changelog. Verify lifecycle in the Linear UI activity feed when auditing.
+
+## Phase 6 — CRUD operations (existing issues)
+
+For verbs other than `task.create`, jump directly to the operation.
+
+> **MANDATORY READ:** [`references/operations.md`](references/operations.md) — full verb → MCP tool mapping, `<task-ref>` resolution, error codes, and idempotency rules.
+
+Verb → MCP tool mapping summary:
+
+| Core verb           | Linear MCP tool                                         | Notes                                                                                                       |
+| ------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `task.create`       | `save_issue` (no id)                                    | `title`+`team` required; `project: config.defaultProjectId` when set; sub-issues via `parentId` per Phase 5 |
+| `task.move`         | `save_issue` (id + state)                               | Resolve state by type: `open`→`unstarted`, `wip`→`started`, `done`→`completed`                              |
+| `checklist.check`   | `save_issue` (sub-issue id + state)                     | `req.itemId` = sub-issue id; check = type `completed`; uncheck = type `unstarted`                           |
+| `task.close`        | `save_issue` (id + state)                               | Type `completed`; cancel = type `canceled`                                                                  |
+| `task.due-date.set` | `save_issue` (id + dueDate)                             | `YYYY-MM-DD` sliced from ISO 8601                                                                           |
+| `task.assignee.add` | `save_issue` (id + assignee)                            | Single-assignee set-not-add; accepts id/name/email/`"me"`                                                   |
+| `task.comment.add`  | `save_comment` (issueId + body)                         | Markdown, literal newlines; apply attribution prefix if enabled                                             |
+| `task.parent.set`   | `save_issue` (id + parentId)                            | Arbitrary depth; `null` parentId detaches                                                                   |
+| `task.estimate.set` | `get_issue` (labels) → `save_issue` (estimate + labels) | Read-modify-write label merge; see § Estimation below                                                       |
+| `task.sprint.set`   | `list_cycles` → `save_issue` (id + cycle)               | Team-gated; see § Sprint below                                                                              |
+
+`<task-ref>` resolution: Linear permalink (`https://linear.app/team/issue/LEO-12`) → bare identifier (`LEO-12`) → UUID → alias from `.linear.json` `taskAliases[]`.
+
+### Estimation (task.estimate.set detail)
+
+> **MANDATORY READ:** [`references/estimation.md`](references/estimation.md)
+
+Estimation records **effort** — never a calendar deadline. The request carries `{ taskId, input: EstimateInput, config: EstimationConfig }`.
+
+Flow:
+
+1. `normalizeEstimate(req.input, req.config)` (core helper, never throws) → `NormalizedEstimate`.
+2. Guard: if `config.estimation.linearTarget === "points"` and `n.points` is `null` → return `INVALID_REQUEST` with hint to pick a point-based strategy or set `linearTarget: "none"` and re-run `pm-tasks-linear init`.
+3. Guard: if `config.estimation.enabled === false` → return `NOT_APPLICABLE`.
+4. `get_issue({ id: taskId })` — read current labels (Linear `labels` is a replace-set).
+5. Strip all prior `est:*` labels; append `est:<slug>` where `slug = slugify(normalized.humanReadable)`.
+6. If `est:<slug>` label does not exist in `config.labels[]` → create via `create_issue_label { name, teamId }` (create-on-demand, M1).
+7. Build native field patch: `linearTarget === "points"` → `estimate: n.points`; `linearTarget === "none"` → no native field.
+8. `save_issue({ id: taskId, ...nativeFieldPatch, labels: mergedIds })` — ONE call.
+9. Return `{ ok: true, data: { normalized, fieldWritten } }`.
+
+The `est:<slug>` label is the durable human-readable record. Labels are plain strings: robust, idempotent, searchable.
+
+### Sprint (task.sprint.set detail)
+
+> **Note:** Linear is the FIRST pm-tasks family adapter to implement `task.sprint.set`.
+
+Cycles are Linear's sprint primitive. They are **team-gated** — not all teams use cycles.
+
+Flow:
+
+1. Guard: `config.cycles.enabled === false` → return `NOT_APPLICABLE` with `{ reason: "cycles_disabled" }`.
+2. `list_cycles({ teamId })` — fetch all cycles for the team.
+3. Match `req.sprintRef` against `cycle.id` (exact), `cycle.name` (exact), or `String(cycle.number)` (exact). If no match, pass `req.sprintRef` directly as `cycle` (may be a raw UUID).
+4. `save_issue({ id: req.taskId, cycle: cycleId })`.
+5. Return `{ ok: true, data: { previousSprintRef: null, newSprintRef: cycleId } }`.
+
+If `config.cycles.enabled` is true but no cycles exist yet on the team, step 2 returns an empty list and step 4 will likely fail at the MCP layer. Surface the raw error.
+
+## Phase 7 — Plan-execution mode
+
+When the calling agent passes a plan reference (a path to a markdown plan file, a plan slug, or an explicit list of expected issue titles), this skill loads `.linear.json` via `requireConfig` and uses `discoverPlanTasks` (from `@llodev/pm-tasks-core`) to triage which tasks in the plan already exist as Linear issues in scope. The skill returns `{ found, missing, ambiguous }` — the **calling agent** decides how to act on each bucket (create missing issues via Phase 4 + 5; disambiguate by picking the right ambiguous issue; proceed with existing).
+
+The skill does **not** assume any particular implementation strategy. It does not drive the calling agent's task loop, does not depend on any specific orchestration framework. When the calling agent finishes a task and asks the skill to record progress, it invokes the standard verbs (`task.move`, `checklist.check`, `task.comment.add`, `task.close`) directly — the same path used by Phase 5b autonomous mode.
+
+Full contract: [`skills/pm-tasks-core/references/plan-execution.md`](../pm-tasks-core/references/plan-execution.md). Linear note: use `list_issues` with team + title filters for scope queries.
+
+## Result envelope
+
+Every verb returns the core contract shape (see [`../pm-tasks-core/references/contract.md`](../pm-tasks-core/references/contract.md) § Result envelope):
+
+```json
+{
+  "ok": true,
+  "verb": "task.create",
+  "tool": "linear",
+  "ref": { "id": "LEO-42", "url": "https://linear.app/team/issue/LEO-42", "alias": null },
+  "details": {}
+}
+```
+
+Linear-specific `details` per verb:
+
+| Verb                | `details` fields                                                       |
+| ------------------- | ---------------------------------------------------------------------- |
+| `task.create`       | `{ id: "LEO-42", url?: string }`                                       |
+| `task.move`         | `{ previousListOrSectionId: null, newListOrSectionId: "<stateId>" }`   |
+| `checklist.check`   | `{ previousState, newState }` (`"complete"` / `"incomplete"`)          |
+| `task.close`        | `{ closed: true, movedToListOrSectionId: "<stateId>" }`                |
+| `task.due-date.set` | `{ previousDueAt: null, newDueAt: "YYYY-MM-DD" }`                      |
+| `task.assignee.add` | `{ added: true, currentAssigneeIds: ["<userId>"] }`                    |
+| `task.comment.add`  | `{ commentId: "<id>", postedAt: "<ISO8601>" }`                         |
+| `task.parent.set`   | `{ previousParentId: null, newParentId: "<issueId or null>" }`         |
+| `task.estimate.set` | `{ normalized: NormalizedEstimate, fieldWritten: "estimate" or null }` |
+| `task.sprint.set`   | `{ previousSprintRef: null, newSprintRef: "<cycleId>" }`               |
+
+On failure: `{ ok: false, code: "<CODE>", details: { message, ... } }`. Stable error codes: `UNSUPPORTED_VERB`, `INVALID_REQUEST`, `NOT_APPLICABLE`, `NOT_FOUND`, `AUTH_ERROR`, `RATE_LIMITED`, `MCP_ERROR`. `NOT_APPLICABLE` is returned for `task.sprint.set` when cycles are disabled, and for `task.estimate.set` when estimation is disabled.
+
+## Anti-patterns
+
+> **MANDATORY READ:** [`anti-patterns/linear.md`](anti-patterns/linear.md)
+
+Key rules (do not violate):
+
+- NEVER write labels without reading first (replace-set — overwrites everything).
+- NEVER fake checklists with `- [ ]` in description — use sub-issues.
+- NEVER hard-code state names — resolve by type.
+- NEVER omit `id` when updating — silently creates a duplicate.
+- NEVER assume cycles exist on a team.
+
+## Standalone fallback
+
+If `@llodev/pm-tasks-core` is not installed: ask the user for minimum input (title + sub-issue names) and produce a paste-ready Linear issue body from this content alone. Quality is degraded — no scope/audience/fidelity inference. Print: _"Install `@llodev/pm-tasks-core` for the full flow."_
+
+## Config
+
+Lookup order: `<git-root>/.linear.json` → `~/.config/llodev/pm-tasks/linear.json` → abort with init instructions. Schema: [`schemas/config.json`](schemas/config.json). Secrets NEVER in JSON — Linear MCP handles OAuth; `init` uses `LINEAR_API_KEY` (env only) for standalone GraphQL discovery.
+
+Key fields written by `init`:
+
+- `team` — `{ id, key, name }`.
+- `states` — `[{ id, name, type }]` (move/close targets, scoped to team; `type` is the stable reference).
+- `labels` — `[{ id, name }]` (workspace-level label registry).
+- `members` — `[{ id, name, email, alias? }]`.
+- `estimation` — `{ strategy, linearTarget: "points"|"none", enabled, scale? }`.
+- `cycles` — `{ enabled }` (gate for `task.sprint.set`).
+- `projects` — `[{ id, name }]` (OPTIONAL; workspace projects discovered at init).
+- `defaultProjectId` — OPTIONAL string; id from `projects[]`. When set, `task.create` files the new issue into this project automatically.
+- `locale` — chosen at init; used for narration.
+- `attribution` — opt-in block; see core attribution reference.
+- `autonomous` — `{ enabled, allow[], scope: { teams[], projects[] }, rateLimit, auditLog }`.
+
+## Init
+
+```
+npx @llodev/pm-tasks-linear init
+```
+
+See [`../pm-tasks-core/references/init-ux.md`](../pm-tasks-core/references/init-ux.md) for the shared flow. Two discovery paths:
+
+**MCP-driven (default, recommended):** Requires the Linear MCP connected in your agent session.
+
+- `list_teams` — select team (`key` + `name`).
+- `list_issue_statuses { team }` — discover states (move/close targets) with their stable `type`.
+- `list_issue_labels` — workspace-level label registry.
+- `list_users` — member roster (id/name/email).
+- `get_team { query }` — team settings (`cyclesEnabled`, `issueEstimationType`).
+- `list_cycles { teamId }` — confirm cycles are available.
+- `list_projects { team }` — workspace projects (stored in `config.projects[]`; optional default prompt).
+
+**GraphQL standalone:** For environments where MCP is not available. Set `LINEAR_API_KEY` in env (personal API key — no Bearer prefix needed). The init script queries the Linear GraphQL API at `https://api.linear.app/graphql` directly for the same discovery (uses `{ projects { nodes { id name } } }` for projects).
+
+```bash
+export LINEAR_API_KEY=lin_api_...
+npx @llodev/pm-tasks-linear init
+```
+
+> [!IMPORTANT]
+> The API key is **only** used by `init` to discover team metadata. The MCP uses OAuth — never put the key in `.linear.json`.
+
+Pass `--doctor` to run workspace health checks:
+
+```sh
+npx @llodev/pm-tasks-linear init --doctor
+```
+
+Doctor checks (C-LIN-*): config present and valid, team resolvable, states cover at least one `completed`-type, estimation/cycles flags coherent, autonomous scope sane, project ids consistent (`C-LIN-8`: `defaultProjectId` and `autonomous.scope.projects` ids must all appear in `projects[]`).
+
+The init prompt prints the absolute path it will write to, so you always see exactly where the file goes. Walk through the prompts and pick local (`./.linear.json`, recommended, committable) or global (`~/.config/llodev/pm-tasks/linear.json`).

package/dist/adapter.d.ts

@@ -0,0 +1,25 @@
+import { type Runtime } from "@llodev/pm-tasks-core/runtime";
+import { type McpCaller } from "./transport-linear.js";
+export type { McpCaller };
+export interface CreateAdapterOptions {
+    /** Absolute or cwd-relative path to .linear.json config file. */
+    configPath: string;
+    /** Caller-supplied MCP dispatcher (proxies to `mcp__linear__*` tools at runtime). */
+    mcp: McpCaller;
+    /** Optional session id for audit-log correlation. Defaults to generateSession() when omitted. */
+    session?: string;
+    /** Optional locale hint (forwarded from .linear.json locale field for narration). */
+    language?: string;
+}
+/**
+ * Construct a ready-to-use Linear adapter Runtime. Reads + parses config from
+ * configPath, wires the Linear MCP transport from the caller-supplied McpCaller,
+ * and returns the same Runtime shape as createCoreRuntime.
+ *
+ * The double-parse (adapter reads config for transport; createCoreRuntime reads
+ * it again for the handler layer) is intentional — extending CreateRuntimeOptions
+ * to carry an already-parsed config is deferred (YAGNI). Config validation lives
+ * in `init` / `doctor` (Phase 3), not here.
+ */
+export declare function createAdapter(opts: CreateAdapterOptions): Promise<Runtime>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,OAAO,EAAkB,MAAM,+BAA+B,CAAC;AAChG,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE9E,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,GAAG,EAAE,SAAS,CAAC;IACf,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAchF"}

package/dist/adapter.js

@@ -0,0 +1,29 @@
+import { readFile } from "node:fs/promises";
+import { createCoreRuntime } from "@llodev/pm-tasks-core/runtime";
+import { createLinearTransport } from "./transport-linear.js";
+/**
+ * Construct a ready-to-use Linear adapter Runtime. Reads + parses config from
+ * configPath, wires the Linear MCP transport from the caller-supplied McpCaller,
+ * and returns the same Runtime shape as createCoreRuntime.
+ *
+ * The double-parse (adapter reads config for transport; createCoreRuntime reads
+ * it again for the handler layer) is intentional — extending CreateRuntimeOptions
+ * to carry an already-parsed config is deferred (YAGNI). Config validation lives
+ * in `init` / `doctor` (Phase 3), not here.
+ */
+export async function createAdapter(opts) {
+    const raw = await readFile(opts.configPath, "utf-8");
+    const config = JSON.parse(raw);
+    // Cast to Transport: taskEstimateSet is narrowed to LinearTaskEstimateSetRequest
+    // (uses linearTarget instead of jiraTarget); the runtime always calls it via
+    // the task-estimate-set handler which passes req.config as-is from the caller.
+    const transport = createLinearTransport({ mcp: opts.mcp, config });
+    return createCoreRuntime({
+        tool: "linear",
+        configPath: opts.configPath,
+        transport,
+        session: opts.session,
+        language: opts.language,
+    });
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAgC,MAAM,+BAA+B,CAAC;AAChG,OAAO,EAAE,qBAAqB,EAAkB,MAAM,uBAAuB,CAAC;AAe9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAA0B;IAC5D,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,iFAAiF;IACjF,6EAA6E;IAC7E,+EAA+E;IAC/E,MAAM,SAAS,GAAG,qBAAqB,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,CAAyB,CAAC;IAC3F,OAAO,iBAAiB,CAAC;QACvB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS;QACT,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC,CAAC;AACL,CAAC"}

package/dist/bin/init.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/bin/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/bin/init.ts"],"names":[],"mappings":""}

package/dist/bin/init.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// pm-tasks-linear init — thin CLI shim. Library surface lives in ../init-flow.ts.
+import path from "node:path";
+import { runInit } from "../init-flow.js";
+async function run() {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--doctor")) {
+        const { runDoctor } = await import("../doctor-cli.js");
+        await runDoctor({ tool: "linear", argv });
+        return;
+    }
+    const outputIdx = argv.indexOf("--output");
+    const outPath = outputIdx !== -1 && argv[outputIdx + 1] ? path.resolve(argv[outputIdx + 1]) : undefined;
+    await runInit({ outPath });
+}
+run().catch((e) => {
+    console.error("pm-tasks-linear init:", e.message);
+    process.exit(1);
+});
+//# sourceMappingURL=init.js.map

package/dist/bin/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/bin/init.ts"],"names":[],"mappings":";AACA,kFAAkF;AAClF,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,KAAK,UAAU,GAAG;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACvD,MAAM,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,OAAO,GACX,SAAS,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1F,MAAM,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;IAChB,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAG,CAAW,CAAC,OAAO,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/doctor-cli.d.ts

@@ -0,0 +1,18 @@
+import { type DoctorCheck } from "@llodev/pm-tasks-core/doctor";
+export interface LinearProbe {
+    /** Call Linear MCP list_teams and return team list */
+    getTeam?: (teamId: string) => Promise<{
+        id: string;
+        key: string;
+    } | null>;
+}
+/** Create the linear-specific check array, optionally with a live probe for C-LIN-7. */
+export declare function makeLinearChecks(probe?: LinearProbe): DoctorCheck[];
+/** Pre-built checks without a probe (used when running standalone without MCP). */
+export declare const ADAPTER_CHECKS: DoctorCheck[];
+export interface RunDoctorOpts {
+    tool: string;
+    argv: string[];
+}
+export declare function runDoctor({ argv }: RunDoctorOpts): Promise<void>;
+//# sourceMappingURL=doctor-cli.d.ts.map

package/dist/doctor-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-cli.d.ts","sourceRoot":"","sources":["../src/doctor-cli.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAiC,MAAM,8BAA8B,CAAC;AAS/F,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC3E;AAuSD,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAEnE;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,EAAE,WAAW,EAAuB,CAAC;AAMhE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,wBAAsB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA+CtE"}