@kyaukyuai/linear-cli 2.12.0 → 2.12.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [2.12.2] - 2026-03-31
+
+### Fixed
+
+- restored `linear capabilities --json` to a startup-safe `v1` machine-readable shape by default, while requiring `--compat v2` for richer schema metadata
+
+## [2.12.1] - 2026-03-30
+
+### Added
+
+- added `stateName` to `issue list --json` as an additive convenience field while keeping the nested `state` object unchanged
+
+### Changed
+
+- refreshed the README, agent workflow docs, and skills.sh install guidance to better position `linear-cli` as an agent-first Linear CLI
+
+### Fixed
+
+- preserved agent-first generated skill docs so `deno task generate-skill-docs` no longer reverts the published skill description and command guidance
+
 ## [2.12.0] - 2026-03-30
 
 ### Added

package/README.md

@@ -6,6 +6,7 @@ if you want an agent to read Linear state, preview a write, apply it, and return
 
 ```bash
 linear capabilities --json
+linear capabilities --json --compat v2
 linear issue list --json
 linear issue view ENG-123 --json
 linear issue create -t "Backfill webhook contract docs" --team ENG --dry-run --json
@@ -16,6 +17,22 @@ linear notification list --json
 
 interactive commands still exist for humans, but the primary design goal is that an agent can discover commands incrementally, pass all important input as flags or stdin, and get machine-readable success or failure back.
 
+## for agents
+
+If an agent only reads one page, it should be this README plus the two contract docs below.
+
+- start with `linear capabilities --json` for the stable startup-safe shape; use `linear capabilities --json --compat v2` when you also need primary input schema and output semantics
+- prefer stable read surfaces such as `issue`, `project`, `cycle`, `milestone`, `document`, `webhook`, `notification`, `team`, `user`, `workflow-state`, `label`, `initiative`, and update feeds with `--json`
+- preview writes with `--dry-run --json` before mutating Linear
+- apply writes with `--json`, then inspect exit codes and `error.details` instead of parsing terminal text
+- use stdin or file flags for Markdown-heavy descriptions and comments instead of long inline shell strings
+
+Recommended docs:
+
+- [Agent workflow guide](docs/agent-first.md)
+- [Automation contracts](docs/json-contracts.md)
+- [stdin and pipeline policy](docs/stdin-policy.md)
+
 ## screencast demos
 
 <details>
@@ -36,6 +53,24 @@ interactive commands still exist for humans, but the primary design goal is that
 
 for agents and scripts, prefer a pinned install in the repo or runtime you control.
 
+### install as a skill
+
+If you want to expose `linear-cli` as a reusable skill on top of an existing agent runtime, install it from the repo root and select the public skill explicitly:
+
+```bash
+npx skills add https://github.com/kyaukyuai/linear-cli --skill linear-cli
+```
+
+This is the most compatible form for `skills` and `skills.sh`.
+
+If you want to point directly at the skill directory instead, this also works:
+
+```bash
+npx skills add https://github.com/kyaukyuai/linear-cli/tree/main/skills/linear-cli
+```
+
+Once installed, agents can load the skill and then call the local `linear` binary using the agent-first guidance in [skills/linear-cli/SKILL.md](skills/linear-cli/SKILL.md).
+
 ### npm / bun / pnpm
 
 install as a dependency to pin a version in your project:
@@ -59,6 +94,8 @@ bunx linear issue list
 
 package on npm: [@kyaukyuai/linear-cli](https://www.npmjs.com/package/@kyaukyuai/linear-cli)
 
+skills directory on GitHub: [skills/linear-cli](https://github.com/kyaukyuai/linear-cli/tree/main/skills/linear-cli)
+
 ### deno via jsr
 
 ```bash
@@ -88,7 +125,7 @@ deno task install
 compared to upstream, this fork adds and maintains capabilities aimed at automation-heavy workflows:
 
 - stable JSON contracts for the automation tier, with machine-readable failures for parser, validation, and runtime errors
-- a self-describing `linear capabilities --json` surface so agents can discover contract coverage, primary input schema, output semantics, and command traits without scraping docs
+- a self-describing `linear capabilities --json` surface with a backward-compatible default and an explicit `--compat v2` mode for richer schema and output metadata
 - `--dry-run` previews for high-value write commands, including `issue start`, issue writes, and non-issue writes
 - stdin and pipeline support for high-value write paths
 - retry-safe semantics for relation add/delete, project label add/remove, notification read/archive, and structured partial-failure details
@@ -106,11 +143,20 @@ compared to upstream, this fork adds and maintains capabilities aimed at automat
 - workspace-aware auth management with keyring migration and default workspace support
 - generated AI-agent skill docs, Claude plugin metadata, npm publishing, and Homebrew tap release plumbing
 
+## docs map
+
+Use the docs in this order if you are building an agent integration:
+
+1. [docs/agent-first.md](docs/agent-first.md) for the recommended discover/read/preview/apply/recover loop
+2. [docs/json-contracts.md](docs/json-contracts.md) for stable JSON payloads, exit codes, timeout semantics, and dry-run envelopes
+3. [docs/stdin-policy.md](docs/stdin-policy.md) for pipeline and file-input conventions
+4. [`linear capabilities --json`](#automation-contract) for machine-readable command metadata at runtime
+
 ## automation contract
 
 for bot and org-wide automation use cases, `linear-cli` defines a stable JSON contract for a focused automation tier.
 
-to discover the curated agent-facing command surface programmatically, use `linear capabilities --json`. it reports stable contract versions, automation-tier membership, and per-command support for `--json`, `--dry-run`, stdin, confirmation bypass, idempotency category, primary arguments and flags, and success/failure output semantics.
+to discover the curated agent-facing command surface programmatically, use `linear capabilities --json`. the default shape preserves the v1-compatible startup contract for existing bots. when you need richer metadata such as primary arguments, flags, and output semantics, opt into `linear capabilities --json --compat v2`.
 
 - v1 in scope: `issue list/view/create/update --json`, `issue relation add/delete/list --json`, `issue comment add --json`, `team members --json`, `issue parent/children/create-batch --json`
 - v2 additions: `project list/view --json`, `cycle list/view/current/next --json`, `milestone list/view --json`

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@kyaukyuai/linear-cli",
-      "version": "2.12.0"
+      "version": "2.12.2"
     },
     "node_modules/@isaacs/cliui": {
       "engines": {
@@ -542,5 +542,5 @@
     }
   },
   "requires": true,
-  "version": "2.12.0"
+  "version": "2.12.2"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/kyaukyuai/linear-cli/releases/download/v2.12.0"
+    "https://github.com/kyaukyuai/linear-cli/releases/download/v2.12.2"
   ],
   "bin": {
     "linear": "run-linear.js"
@@ -85,7 +85,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "2.12.0",
+  "version": "2.12.2",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"