linear-sdk-cli 0.1.3 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linear-sdk-cli",
-  "version": "0.1.3",
+  "version": "0.2.3",
   "description": "Ergonomic command-line interface for Linear, built on @linear/sdk",
   "type": "module",
   "license": "MIT",
@@ -53,14 +53,15 @@
     "dev": "bun run src/bin/linear.ts",
     "lin": "bun run src/bin/linear.ts",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
+    "lint": "oxlint .",
     "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "test": "bun test test/unit test/contract",
     "test:unit": "bun test test/unit",
     "test:contract": "bun test test/contract",
     "test:live": "LINEAR_CLI_LIVE=1 bun test --timeout 60000 test/integration",
     "test:live:admin": "LINEAR_CLI_LIVE=1 LINEAR_CLI_LIVE_ADMIN=1 bun test --timeout 60000 test/integration",
-    "verify": "bun run typecheck && bun run lint && bun run test",
+    "verify": "bun run typecheck && bun run lint && bun run audit:coverage && bun run format:check && bun run test",
     "skill:docs": "bun run skills/linear-sdk-cli/scripts/generate-docs.ts",
     "audit:coverage": "bun run scripts/coverage-audit.ts",
     "janitor": "bun run test/janitor.ts"
@@ -75,12 +76,10 @@
   },
   "packageManager": "bun@1.4.0",
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.2.0",
-    "eslint": "^10.9.0",
+    "oxlint": "^1.80.0",
     "prettier": "^3.9.6",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.67.0"
+    "typescript": "^7.0.2"
   }
 }

package/skills/README.md

@@ -0,0 +1,15 @@
+# Agent skills
+
+The `skills/` directory contains the portable, canonical skill sources for this
+repository. Each skill uses the open `SKILL.md` convention and must remain usable
+by both Codex and Claude Code without agent-specific instructions.
+
+Claude Code receives the listed skills through `.claude-plugin/plugin.json` when
+this repository is installed as its plugin. A Codex user can add or install the
+same skill directory in their Codex skills location; scheduled Codex tasks can
+also invoke a repository skill explicitly by path.
+
+The cloud maintenance routine reads
+`skills/linear-sdk-cli-maintenance/SKILL.md` before it acts. Keep routine-specific
+schedule and notification settings in the routine; keep maintenance procedure and
+guardrails in the skill.

package/skills/linear-sdk-cli/SKILL.md

@@ -24,8 +24,8 @@ If that fails, or prints `2.x` (that is `schpet/linear-cli`, a different tool th
 `linear` name), install this one — it needs Bun ≥ 1.1:
 
 ```bash
-bun add -g linear-sdk-cli          # installs `linear` and `lin`
-lin --version                      # `lin` never collides with the other CLI
+bun add --global linear-sdk-cli  # installs `linear` and collision-free `lin`
+lin --version
 ```
 
 `lin` is the safe spelling when both might be present. If the user is coming from
@@ -195,7 +195,26 @@ EOF
 
 For short, single-line content, use inline `-d/--description` (issues/initiatives),
 the positional `[body]` arg (comments: `linear comment add TES-42 "lgtm"`), or
-`--body` (status updates). There is no `-b` short flag.
+`--body` (status updates). There is no `-b` short flag. The CLI rejects an inline
+body containing literal `\n` sequences and points back to stdin; never encode a
+multiline body by inserting `\n` inside an ordinary quoted argument.
+
+### Mentions require explicit intent
+
+Never assume that `@name` in comment text should notify somebody: the CLI keeps it as literal
+Markdown. Add the repeatable `--mention <name|email|me|id>` option only when the user explicitly
+asks for a real mention. It resolves each workspace user and prepends the notification-capable
+mention before the supplied body:
+
+```bash
+linear comment add TES-42 "Please review." --mention ada --json
+linear issue comment TES-42 --body-file - --mention me --json <<'EOF'
+This deliberately mentions me; the @example in this sentence remains literal.
+EOF
+```
+
+`--mention` is available on `issue comment`, `comment add`, `comment reply`, and `comment update`
+(including the `issue comment add/update` mounts). It is repeatable and deduplicates users.
 
 ### Discovery — learn the surface without scraping help
 
@@ -235,6 +254,7 @@ linear attachment delete
 linear attachment list
 
 linear auth
+linear auth adopt
 linear auth default
 linear auth list
 linear auth login
@@ -351,6 +371,8 @@ linear notification read-all
 linear notification snooze
 linear notification unread
 
+linear open
+
 linear organization
 linear organization invites
 linear organization members
@@ -386,6 +408,7 @@ linear team
 linear team create
 linear team cycles
 linear team delete
+linear team id
 linear team labels
 linear team list
 linear team members
@@ -432,6 +455,7 @@ prints the same). These are supplementary — `--help` on any command is authori
 - [label](references/label.md) — Work with issue labels
 - [milestone](references/milestone.md) — Work with project milestones
 - [notification](references/notification.md) — Work with your notifications
+- [open](references/open.md) — Open the workspace, an issue, team, project, or URL
 - [organization](references/organization.md) — Inspect the current workspace
 - [project](references/project.md) — Work with projects
 - [project-update](references/project-update.md) — Post and list project status updates

package/skills/linear-sdk-cli/references/api.md

@@ -14,14 +14,14 @@ Run a raw GraphQL query or mutation against the Linear API
 linear api [options] [query]
 ```
 
-| Option                | Description                                                       |
-| --------------------- | ----------------------------------------------------------------- |
-| `--query-file <path>` | read the query from a file ('-' for stdin)                        |
-| `--var <k=v...>`      | set a variable (repeatable; string value)                         |
-| `--vars <json>`       | variables as a JSON object                                        |
-| `--vars-file <path>`  | read variables from a JSON file ('-' for stdin)                   |
-| `--operation <name>`  | run this operation of a multi-operation document                  |
-| `--paginate`          | auto-follow the first connection's pageInfo cursor (queries only) |
-| `--raw`               | print the full GraphQL response (data + extensions)               |
+| Option                | Description                                                                    |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `--query-file <path>` | read the query from a file ('-' for stdin)                                     |
+| `--var <k=v...>`      | set a variable (repeatable; JSON literals are typed, other values are strings) |
+| `--vars <json>`       | variables as a JSON object                                                     |
+| `--vars-file <path>`  | read variables from a JSON file ('-' for stdin)                                |
+| `--operation <name>`  | run this operation of a multi-operation document                               |
+| `--paginate`          | auto-follow the first connection's pageInfo cursor (queries only)              |
+| `--raw`               | print the full GraphQL response (data + extensions)                            |
 
 **Output (`--json`)**: raw JSON (keys depend on the request) — the response `data` as the API returned it (`--raw`: {data, extensions}); `--paginate` prints one array of every page's nodes

package/skills/linear-sdk-cli/references/auth.md

@@ -14,6 +14,24 @@ Manage authentication
 linear auth [options]
 ```
 
+### `linear auth adopt`
+
+Adopt an existing named credential from the shared OS keyring
+
+```
+linear auth adopt [options] <slug>
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+success: boolean
+workspace: string
+user: {id: string, name: string, email: string}
+storage: string
+path: string
+```
+
 ### `linear auth default`
 
 Set the default workspace credential

package/skills/linear-sdk-cli/references/commands.md

@@ -21,7 +21,7 @@ path: string
 description: string
 aliases: string[]
 arguments: Array<{name: string, required: boolean, variadic: boolean}>
-options: Array<{flags: string, description: string}>
+options: Array<{flags: string, description: string, attribute: string, valueRequired: boolean, valueOptional: boolean, variadic: boolean, choices?: string[], defaultValue?: unknown, global: boolean, applicable: boolean}>
 output?: {kind: string, fields?: object, note?: string, variants?: object}
 ```
 
@@ -32,6 +32,6 @@ path: string
 description: string
 aliases: string[]
 arguments: Array<{name: string, required: boolean, variadic: boolean}>
-options: Array<{flags: string, description: string}>
+options: Array<{flags: string, description: string, attribute: string, valueRequired: boolean, valueOptional: boolean, variadic: boolean, choices?: string[], defaultValue?: unknown, global: boolean, applicable: boolean}>
 output?: {kind: string, fields?: object, note?: string, variants?: object}
 ```

package/skills/linear-sdk-cli/references/comment.md

@@ -29,6 +29,7 @@ linear comment add [options] <issue> [body]
 | Option               | Description                                                                               |
 | -------------------- | ----------------------------------------------------------------------------------------- |
 | `--body-file <path>` | read comment body from a file ('-' = stdin)                                               |
+| `--mention <user>`   | prepend a real Linear mention (name, email, me, or id; repeatable)                        |
 | `--attach <file>`    | upload a file and embed it in the comment (images inline; repeatable; private by default) |
 | `--public`           | upload the attachments to public, world-readable URLs (raster images only)                |
 
@@ -89,9 +90,10 @@ Reply to a comment (nested under it)
 linear comment reply [options] <commentId> [body]
 ```
 
-| Option               | Description                               |
-| -------------------- | ----------------------------------------- |
-| `--body-file <path>` | read reply body from a file ('-' = stdin) |
+| Option               | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `--body-file <path>` | read reply body from a file ('-' = stdin)                          |
+| `--mention <user>`   | prepend a real Linear mention (name, email, me, or id; repeatable) |
 
 **Output (`--json`)**: a receipt object
 
@@ -142,9 +144,10 @@ Aliases: `edit`
 linear comment update [options] <commentId> [body]
 ```
 
-| Option               | Description                             |
-| -------------------- | --------------------------------------- |
-| `--body-file <path>` | read new body from a file ('-' = stdin) |
+| Option               | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `--body-file <path>` | read new body from a file ('-' = stdin)                            |
+| `--mention <user>`   | prepend a real Linear mention (name, email, me, or id; repeatable) |
 
 **Output (`--json`)**: a receipt object
 

package/skills/linear-sdk-cli/references/config.md

@@ -23,8 +23,7 @@ credentialWorkspace: string | null
 team: string | null
 workspace: string | null
 sort: string
-vcs: string
-origins: {team: {source: string, path?: string}, workspace: {source: string, path?: string}, sort: {source: string, path?: string}, vcs: {source: string, path?: string}}
+origins: {team: {source: string, path?: string, key?: string}, workspace: {source: string, path?: string, key?: string}, sort: {source: string, path?: string, key?: string}}
 userConfigPath: string
 projectConfigPath: string | null
 globalConfigPath: string | null
@@ -38,12 +37,12 @@ Write a project .linear.toml (at the git root, or here outside a repository)
 linear config init [options]
 ```
 
-| Option           | Description                                              |
-| ---------------- | -------------------------------------------------------- |
-| `--team <key>`   | default team key (otherwise chosen from a list)          |
-| `--sort <order>` | default issue-list sort (priority \| updated \| created) |
-| `--path <file>`  | write this file instead of <git root>/.linear.toml       |
-| `--force`        | overwrite an existing file                               |
+| Option           | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `--team <key>`   | default team key (otherwise chosen from a list)                    |
+| `--sort <order>` | default issue-list sort (priority \| manual \| updated \| created) |
+| `--path <file>`  | write this file instead of <git root>/.linear.toml                 |
+| `--force`        | overwrite an existing file                                         |
 
 **Output (`--json`)**: a receipt object
 
@@ -56,7 +55,7 @@ sort?: string
 
 ### `linear config set`
 
-Set one project setting (team, workspace, sort, vcs) in the project config
+Set one project setting (team, workspace, sort) in the project config
 
 ```
 linear config set [options] <key> <value>
@@ -93,8 +92,7 @@ credentialWorkspace: string | null
 team: string | null
 workspace: string | null
 sort: string
-vcs: string
-origins: {team: {source: string, path?: string}, workspace: {source: string, path?: string}, sort: {source: string, path?: string}, vcs: {source: string, path?: string}}
+origins: {team: {source: string, path?: string, key?: string}, workspace: {source: string, path?: string, key?: string}, sort: {source: string, path?: string, key?: string}}
 userConfigPath: string
 projectConfigPath: string | null
 globalConfigPath: string | null

package/skills/linear-sdk-cli/references/issue.md

@@ -44,18 +44,27 @@ team: {id: string, key: string, name: string} | null
 project: {id: string, name: string} | null
 milestone: {id: string, name: string} | null
 cycle: {id: string, number: number, name: string | null} | null
-parent: {id: string, identifier: string} | null
+parent: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null} | null
+children: Array<{id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}>
 labels: Array<{id: string, name: string}>
 subscribers: Array<{id: string, displayName: string}>
+attachments: Array<{id: string, title: string, url: string, subtitle: string | null, sourceType: string | null, createdAt: string}>
+documents: Array<{id: string, title: string, slugId: string, url: string, createdAt: string, updatedAt: string}>
+relations: Array<{id: string, type: string, issue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}, relatedIssue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}}>
+inverseRelations: Array<{id: string, type: string, issue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}, relatedIssue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}}>
+comments: Array<{id: string, body: string, url: string, createdAt: string, editedAt: string | null, resolvedAt: string | null, parent: {id: string} | null, user: {id: string, displayName: string} | null, externalUser: {id: string, displayName: string} | null, resolvingCommentId: string | null, resolvingUser: {id: string, displayName: string} | null}>
 ```
 
-With `--comments`: the same, plus:
+With `--web`: a receipt object
 
 ```text
-comments: Array<{id: string, body: string, user: {id: string, displayName: string} | null, createdAt: string, editedAt: string | null, resolvedAt: string | null, parent: {id: string} | null, url: string}>
+id: string
+identifier: string
+url: string
+opened: boolean
 ```
 
-With `--web`: a receipt object
+With `--app`: a receipt object
 
 ```text
 id: string
@@ -143,6 +152,12 @@ Archive an issue
 linear issue archive [options] [id]
 ```
 
+| Option               | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `--bulk <ids>`       | archive comma-separated issue ids (repeatable)   |
+| `--bulk-file <path>` | archive issue ids from a file (one per line)     |
+| `--bulk-stdin`       | archive issue ids read from stdin (one per line) |
+
 **Output (`--json`)**: a receipt object
 
 ```text
@@ -151,6 +166,15 @@ identifier: string
 archived: boolean
 ```
 
+With `--bulk`: a receipt object
+
+```text
+action: string
+results: Array<{input: string, id?: string, identifier?: string, archived?: boolean, deleted?: boolean, error?: {message: string, code: string}}>
+succeeded: number
+failed: number
+```
+
 ### `linear issue assign`
 
 Assign an issue (use 'me', email, name, or id). Issue defaults to the branch.
@@ -214,9 +238,10 @@ Add a comment to an issue; on a matching branch, `issue comment "<body>"` is eno
 linear issue comment [options] [id] [body]
 ```
 
-| Option               | Description                                 |
-| -------------------- | ------------------------------------------- |
-| `--body-file <path>` | read comment body from a file ('-' = stdin) |
+| Option               | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `--body-file <path>` | read comment body from a file ('-' = stdin)                        |
+| `--mention <user>`   | prepend a real Linear mention (name, email, me, or id; repeatable) |
 
 **Output (`--json`)**: a receipt object — the bare form adds a comment; add/list/update/delete are subcommands
 
@@ -236,6 +261,7 @@ linear issue comment add [options] <issue> [body]
 | Option               | Description                                                                               |
 | -------------------- | ----------------------------------------------------------------------------------------- |
 | `--body-file <path>` | read comment body from a file ('-' = stdin)                                               |
+| `--mention <user>`   | prepend a real Linear mention (name, email, me, or id; repeatable)                        |
 | `--attach <file>`    | upload a file and embed it in the comment (images inline; repeatable; private by default) |
 | `--public`           | upload the attachments to public, world-readable URLs (raster images only)                |
 
@@ -292,9 +318,10 @@ Update a comment's body
 linear issue comment update [options] <commentId> [body]
 ```
 
-| Option               | Description                             |
-| -------------------- | --------------------------------------- |
-| `--body-file <path>` | read new body from a file ('-' = stdin) |
+| Option               | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `--body-file <path>` | read new body from a file ('-' = stdin)                            |
+| `--mention <user>`   | prepend a real Linear mention (name, email, me, or id; repeatable) |
 
 **Output (`--json`)**: a receipt object
 
@@ -380,6 +407,12 @@ Aliases: `rm`
 linear issue delete [options] [id]
 ```
 
+| Option               | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `--bulk <ids>`       | delete comma-separated issue ids (repeatable)   |
+| `--bulk-file <path>` | delete issue ids from a file (one per line)     |
+| `--bulk-stdin`       | delete issue ids read from stdin (one per line) |
+
 **Output (`--json`)**: a receipt object
 
 ```text
@@ -388,6 +421,15 @@ identifier: string
 deleted: boolean
 ```
 
+With `--bulk`: a receipt object
+
+```text
+action: string
+results: Array<{input: string, id?: string, identifier?: string, archived?: boolean, deleted?: boolean, error?: {message: string, code: string}}>
+succeeded: number
+failed: number
+```
+
 ### `linear issue describe`
 
 Print a commit message for the issue: 'ID Title' plus Linear-issue trailers
@@ -790,6 +832,7 @@ linear issue update [options] [id]
 | `--estimate <n>`            | estimate points                                         |
 | `--parent <id>`             | parent issue id                                         |
 | `--due <date>`              | due date (YYYY-MM-DD)                                   |
+| `-l, --label <name>`        | replace all labels (repeatable / comma-separated)       |
 | `--add-label <name>`        | add a label (repeatable)                                |
 | `--remove-label <name>`     | remove a label (repeatable)                             |
 | `--unassign`                | clear the assignee                                      |
@@ -825,10 +868,12 @@ Show an issue (defaults to the current branch's issue)
 linear issue view [options] [id]
 ```
 
-| Option       | Description                                       |
-| ------------ | ------------------------------------------------- |
-| `-w, --web`  | open the issue in the browser instead of printing |
-| `--comments` | include recent comments                           |
+| Option                    | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `-w, --web`               | open the issue in the browser instead of printing |
+| `--app`                   | open the issue in Linear.app instead of printing  |
+| `--no-comments`           | exclude comments from the output                  |
+| `--show-resolved-threads` | include resolved comment threads                  |
 
 **Output (`--json`)**: a bare object
 
@@ -856,18 +901,27 @@ team: {id: string, key: string, name: string} | null
 project: {id: string, name: string} | null
 milestone: {id: string, name: string} | null
 cycle: {id: string, number: number, name: string | null} | null
-parent: {id: string, identifier: string} | null
+parent: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null} | null
+children: Array<{id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}>
 labels: Array<{id: string, name: string}>
 subscribers: Array<{id: string, displayName: string}>
+attachments: Array<{id: string, title: string, url: string, subtitle: string | null, sourceType: string | null, createdAt: string}>
+documents: Array<{id: string, title: string, slugId: string, url: string, createdAt: string, updatedAt: string}>
+relations: Array<{id: string, type: string, issue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}, relatedIssue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}}>
+inverseRelations: Array<{id: string, type: string, issue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}, relatedIssue: {id: string, identifier: string, title: string, state: {id: string, name: string, type: string} | null}}>
+comments: Array<{id: string, body: string, url: string, createdAt: string, editedAt: string | null, resolvedAt: string | null, parent: {id: string} | null, user: {id: string, displayName: string} | null, externalUser: {id: string, displayName: string} | null, resolvingCommentId: string | null, resolvingUser: {id: string, displayName: string} | null}>
 ```
 
-With `--comments`: the same, plus:
+With `--web`: a receipt object
 
 ```text
-comments: Array<{id: string, body: string, user: {id: string, displayName: string} | null, createdAt: string, editedAt: string | null, resolvedAt: string | null, parent: {id: string} | null, url: string}>
+id: string
+identifier: string
+url: string
+opened: boolean
 ```
 
-With `--web`: a receipt object
+With `--app`: a receipt object
 
 ```text
 id: string

package/skills/linear-sdk-cli/references/open.md

@@ -0,0 +1,29 @@
+# linear open
+
+> Open the workspace, an issue, team, project, or URL
+
+_Generated from `linear commands --json`. `linear open --help` (or `<subcommand> --help`) is authoritative._
+
+Every command also accepts the global flags `-j/--json`, `--no-input`, `-y/--yes`, `-q/--quiet`, `--workspace <slug>`, `--api-key <key>`, `-t/--team <key>`, `-n/--limit <n>`, `--all`, `-f/--fields <a,b,c>`, `--no-ansi` (alias `--no-color`), and `--debug`. Only command-specific options are listed below.
+
+### `linear open`
+
+Open the workspace, an issue, team, project, or URL
+
+```
+linear open [options] [target]
+```
+
+| Option      | Description                               |
+| ----------- | ----------------------------------------- |
+| `--app`     | open in Linear.app (macOS)                |
+| `-w, --web` | open in the default browser (the default) |
+
+**Output (`--json`)**: a receipt object
+
+```text
+target: string
+url: string
+label: string
+opened: boolean
+```

package/skills/linear-sdk-cli/references/team.md

@@ -86,6 +86,22 @@ movedIssues: number
 movedTo: {id: string, key: string, name: string} | null
 ```
 
+### `linear team id`
+
+Print a team's UUID (defaults to the configured team)
+
+```
+linear team id [options] [key]
+```
+
+**Output (`--json`)**: a receipt object
+
+```text
+id: string
+key: string
+name: string
+```
+
 ### `linear team labels`
 
 List a team's labels

package/skills/linear-sdk-cli/scripts/generate-docs.ts

@@ -70,7 +70,10 @@ const GLOBAL_OPTIONS = new Map([
   ["-t, --team <key>", "default team key (e.g. TES)"],
   ["-n, --limit <n>", "max results (positive integer; 0 = all)"],
   ["--all", "fetch all results (exhaust pagination)"],
-  ["-f, --fields <a,b,c>", "select fields: table columns or detail lines (human), top-level keys (--json)"],
+  [
+    "-f, --fields <a,b,c>",
+    "select fields: table columns or detail lines (human), top-level keys (--json)",
+  ],
   ["-y, --yes", "skip confirmation prompts"],
   ["-q, --quiet", "suppress status output"],
   ["--no-input", "never prompt; fail instead"],
@@ -190,7 +193,8 @@ function formatOutput(out: OutputShape, heading = "**Output (`--json`)**"): stri
       lines.push(`With \`${when}\`: the same${drop}, plus:`);
       lines.push("");
       lines.push("```text");
-      for (const [key, shape] of Object.entries(delta.added)) lines.push(`${key}: ${renderShape(shape)}`);
+      for (const [key, shape] of Object.entries(delta.added))
+        lines.push(`${key}: ${renderShape(shape)}`);
       lines.push("```");
       lines.push("");
       continue;

package/skills/linear-sdk-cli-maintenance/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: linear-sdk-cli-maintenance
+description: "Safely maintain the linear-sdk-cli repository: assess dependency updates, prepare and verify focused pull requests, and hand off releases. Use for scheduled upkeep, dependency reviews, release-automation checks, and maintenance PR reviews in this repository."
+---
+
+# linear-sdk-cli maintenance
+
+Use this skill from the repository root. It is deliberately agent-neutral: the same
+`SKILL.md` is the source of truth for Codex and Claude Code.
+
+## Invocation modes
+
+- **Review mode (default):** inspect and report only. Do not create branches, commits,
+  pull requests, merges, releases, or configuration changes without current user approval.
+- **Scheduled autonomous mode:** the calling routine explicitly authorizes the maintenance
+  mutations described below. It may create and update PRs and merge a verified,
+  dependency-only roll-up PR. It must never push directly to `main`.
+
+If the invocation does not state a mode, use review mode.
+
+## Guardrails
+
+- Start from the current remote `main`; preserve all unrelated local or remote work.
+- Never reveal, add, rotate, or work around credentials. Do not modify API keys, auth,
+  keychain behaviour, `.env` files, or `.linear.toml` merely to make a check pass.
+- Do not weaken tests, linting, CI, branch protection, release checks, or provenance to
+  get a green result.
+- Treat a failed verification, a conflict, a required reviewer, or a non-green check as a
+  stop condition for the affected change. Report the evidence and leave the repository
+  recoverable.
+- Keep dependency-only changes isolated from source, test, configuration, workflow, or
+  documentation changes. Source changes always get their own draft PR and are never
+  auto-merged by this skill.
+- Use conventional commits. Do not bypass required checks, dismiss reviews, or override
+  branch protection.
+- For multiline GitHub PR descriptions or comments, write Markdown to a file and use the
+  corresponding `--body-file` option. Do not encode line breaks as `\n` inside a quoted
+  `--body` argument. Read the published body back once and confirm that headings, paragraphs,
+  and lists render as intended.
+
+## Maintenance loop
+
+1. Inspect the current `main`, open maintenance/release PRs, CI status, and repository
+   guidance. Confirm tool availability with `bun --version`, `gh auth status`, and the
+   repository scripts before changing anything.
+2. Survey dependency candidates with `bun outdated`. Group compatible patch/minor updates;
+   assess major updates separately. Check each material update's upstream release notes or
+   migration guide before proposing it.
+3. Prefer one focused dependency roll-up PR for compatible, low-risk updates. Defer an
+   update that causes a failure or requires an unverified migration; state its exact version,
+   reason, and next action in the report.
+4. For every candidate PR, run the repository's required verification:
+
+   ```sh
+   bun install
+   bun run verify
+   bun src/bin/linear.ts --version
+   bun src/bin/linear.ts commands --json > /dev/null
+   bun run janitor
+   ```
+
+   Run `bun run skill:docs` and include generated references whenever a command or option
+   changes. Keep the PR scope limited to the intended maintenance category.
+
+5. In scheduled autonomous mode, merge only a dependency-only roll-up PR after all required
+   checks are green, the merge is clean, and there are no unresolved review comments. Recheck
+   `main` CI after the merge. Otherwise, leave the PR ready for review and report why it was
+   not merged.
+
+## Release Please handoff
+
+When a Release Please PR exists, review its diff, mergeability, checks, and discussion.
+In scheduled autonomous mode, merge it only when all of the following are true:
+
+- it contains only the expected version and changelog changes;
+- required checks are green (or intentionally absent because the automation-created PR cannot
+  trigger them, while the exact release commit has already passed `main` CI);
+- it is cleanly mergeable with no conflicts, review blockers, or unresolved comments.
+
+Release Please may rewrite its PR whenever `main` changes. Record the `headRefOid` used by CI
+and review, then fetch the PR again immediately before merging. If its head changed, discard the
+earlier evidence and repeat diff review, verification, and review-comment checks on the new head.
+
+After an approved merge, confirm the release workflow completed, then verify the GitHub Release,
+the npm package version, and the `latest` dist-tag. npm publishing must retain OIDC provenance.
+Never retry a failed publish by adding an npm token or disabling provenance; report the failure.
+
+## Report format
+
+End every run with a short, evidence-backed summary:
+
+- repository/branch and current commit inspected;
+- dependency candidates, including deferred items and rationale;
+- PRs created, updated, merged, or deliberately left open;
+- each verification command and result;
+- release status, if applicable; and
+- blockers or the next safe action.