linmux 0.1.0

package/skills/linmux/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: linmux
+description: Operate Linear across all your workspaces from any agent that can shell out — the full GraphQL surface (~500 ops), multiple workspaces in one session, and stable versioned JSON. Use when the user asks about Linear issues, projects, cycles, comments, teams, labels, or workflow states, or wants to query/mutate Linear via CLI — especially when more than one Linear workspace is in play.
+compatibility: Requires Node 22+ and a Linear API key (LINEAR_API_KEY env var or `linmux workspace add`).
+metadata:
+  version: "0.1.0"
+  homepage: "https://github.com/ChuckMayo/linear-multi-workspace-cli"
+---
+
+# linmux
+
+One CLI that drives **every** Linear operation across **all** your workspaces — the full GraphQL surface (~500 ops), multiple workspaces in a single session, JSON by default for agents.
+
+Pinned version: `0.1.0`. Always invoke as `npx -y linmux@0.1.0 <command>`. Never the floating dist-tag — agents must pin so a registry update doesn't silently change the contract mid-session.
+
+## When to invoke
+
+Invoke `linmux` when the user wants to read or write Linear data and you can shell out. It shines when more than one Linear workspace is in play — each command resolves its workspace independently, so a single session can touch several. Trigger phrases include:
+
+- "create / update / archive / list / search / get an issue"
+- "add a comment", "find issues in <team>", "what's in cycle <n>"
+- "create / update a project", "set project status"
+- "list teams / labels / workflow states / cycles"
+- "who am I" / "what workspace am I in" (use `me` or `whoami`)
+- Anything spanning two workspaces ("compare my open issues in acme vs personal")
+- Any GraphQL query a curated command doesn't cover — fall back to the raw layer
+
+You do NOT need to ask the user for permission to call a read-only command (`*list*`, `*get*`, `*search*`, `me`, `whoami`, `describe`, `list-tools`, `schema`). For write commands (create/update/delete/archive/trash/transition/purge), confirm intent first unless the user has clearly asked for the write.
+
+## Auth setup
+
+`linmux` reads its Linear API key from one of two sources, in this order:
+
+1. **Per-shell env var** (preferred for CI / one-shot invocations):
+   ```
+   export LINEAR_API_KEY=lin_api_...
+   npx -y linmux@0.1.0 me --json
+   ```
+
+2. **Persistent workspace registry** (preferred for interactive use, supports multiple workspaces):
+   ```
+   npx -y linmux@0.1.0 workspace add acme --token lin_api_...
+   npx -y linmux@0.1.0 workspace add personal --token lin_api_...
+   npx -y linmux@0.1.0 workspace use acme
+   npx -y linmux@0.1.0 me --json
+   ```
+
+The workspace name is a positional argument (`workspace add <name> --token ...`). Every command accepts `--workspace <name>` to target a specific registered workspace without changing the active default — that is how one session drives several workspaces:
+
+```
+npx -y linmux@0.1.0 issue list --workspace acme --team ENG --json
+npx -y linmux@0.1.0 issue list --workspace personal --team SIDE --json
+```
+
+Tokens are stored at `$XDG_CONFIG_HOME/linear-agent/config.json`, default `~/.config/linear-agent/config.json` (the directory name predates the `linmux` rename), written with mode 0600. Personal API keys only — no OAuth in v1.
+
+If neither source is set, every command exits with `WORKSPACE_NOT_RESOLVED` (exit 10). Run `linmux workspace list` to see what's registered.
+
+## JSON-by-default contract
+
+Every command emits a versioned envelope on stdout. **Pass `--json` for machine output** — pretty/human output is on by default but agents should always use `--json`.
+
+Success envelope (locked key order):
+```json
+{
+  "$apiVersion": "1",
+  "ok": true,
+  "data": { /* command-specific payload */ },
+  "meta": { "command": "issue list", "workspace": "acme" }
+}
+```
+
+Failure envelope:
+```json
+{
+  "$apiVersion": "1",
+  "ok": false,
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Title is required",
+    "transient": false,
+    "details": { "field": "title" }
+  },
+  "meta": { "command": "issue create" }
+}
+```
+
+`ok: true` ⇒ exit 0. `ok: false` ⇒ exit > 0 (taxonomy below). The `data` payload shape is stable per command — pin tests against `data.*` paths, not human prose. The `meta.workspace` field tells you which workspace served the call — check it when working across several.
+
+## Curated commands quick-reference
+
+Top-of-funnel commands (one line each). Run `npx -y linmux@0.1.0 describe <command>` for full flag schema, or `npx -y linmux@0.1.0 list-tools` for the full inventory.
+
+| Command | Purpose |
+|---------|---------|
+| `me --json` | Fetch viewer + organization (auth probe). |
+| `whoami --json` | Active workspace + user identity. |
+| `issue list --team <slug> --json` | Page through issues in a team. |
+| `issue get <id> --json` | Fetch one issue by identifier (e.g. `ENG-123`). |
+| `issue search "<query>" --json` | Full-text search. |
+| `issue create --team <slug> --title "..." [--description "..." --state <name> --assignee <email> --labels <l1,l2>] --json` | Create. |
+| `issue update <id> [--title --description --state --assignee --labels] --json` | Patch fields. |
+| `issue transition <id> --state <name> --json` | Move to a workflow state. |
+| `issue archive <id> --json` / `issue trash <id> --json` / `issue purge <id> --json` | Lifecycle ops (require confirmation). |
+| `comment create --issue <id> --body "..." --json` | Add a comment. |
+| `comment list --issue <id> --json` | List comments on an issue. |
+| `project list [--team <slug>] --json` | List projects (optionally team-scoped). |
+| `project create --team <slug> --name "..." [--description ...] --json` | Create project. |
+| `project update-status <id> --status <name> --json` | Update a project's status field. |
+| `cycle list --team <slug> --json` | List cycles for a team. |
+| `team list --json` / `label list --team <slug> --json` / `state list --team <slug> --json` | Read-only catalogs. |
+
+Any command above accepts `--workspace <name>` to target a specific workspace. Every write command short-circuits to a `CONFIRMATION_REQUIRED` error if it looks destructive without `--yes`. Pass `--yes` only when the user has explicitly approved the write.
+
+## Raw GraphQL escape hatch
+
+When a curated command doesn't expose a field you need, use the raw layer. Workflow:
+
+1. **Discover the operation:**
+   ```
+   npx -y linmux@0.1.0 describe IssueBatchCreate --json
+   ```
+   `describe` returns a Zod-derived schema with required + optional fields.
+
+2. **Invoke it via `raw`:**
+   ```
+   npx -y linmux@0.1.0 raw IssueBatchCreate \
+     --vars '{"input":{"issues":[{"teamId":"...","title":"..."}]}}' \
+     --json
+   ```
+   Output is the SAME envelope shape as curated commands.
+
+3. **Or run an arbitrary GraphQL query string:**
+   ```
+   npx -y linmux@0.1.0 graphql \
+     --query 'query { viewer { id } }' \
+     --json
+   ```
+
+The raw layer covers Linear's full GraphQL surface (~500+ operations) — this is the part the official Linear MCP doesn't reach. Use it when the user asks for something a curated command doesn't expose; otherwise prefer the curated command for cleaner UX and snapshot-stable output.
+
+## Common error envelopes
+
+The five most-likely failure codes you'll see:
+
+| Code | Exit | Meaning |
+|------|------|---------|
+| `WORKSPACE_NOT_RESOLVED` | 10 | No `LINEAR_API_KEY` and no active workspace. Tell the user to run `linmux workspace add` or set `LINEAR_API_KEY`. |
+| `AUTH_INVALID` | 11 | Token is malformed or has been revoked. Tell the user to regenerate at <https://linear.app/settings/api>. |
+| `VALIDATION_FAILED` | 12 | A required field is missing or malformed. Inspect `error.details.field`. |
+| `RATELIMITED` | 14 | Linear's rate limit is hit (3M points/hr authenticated). `error.transient: true` — back off and retry. |
+| `NETWORK_ERROR` | 15 | Transport-level failure (DNS, TLS, timeout). `error.transient: true` — retry once before surfacing to the user. |
+
+The table above covers the five most-frequent codes. Other codes follow the same envelope shape — inspect `error.code` to identify the failure and `error.transient` to decide whether to retry (codes 14 and 15 set `transient: true`).
+
+### Token & Retry Knobs
+
+Three flags help shave bytes or control retries in high-volume agent sessions.
+
+- `--no-meta`: drop the `meta` block from success envelopes (failure envelopes unchanged for debuggability). Saves ~150–250 bytes per call.
+
+  ```
+  npx -y linmux@0.1.0 issue list --json --no-meta
+  ```
+
+- `--quiet`: implies `--no-meta` AND suppresses pretty-mode banners. Useful for human pipelines and CI scripts that just want the data.
+
+  ```
+  npx -y linmux@0.1.0 me --json --quiet
+  ```
+
+- `--retry N`: add N additional retries on top of the per-error-type defaults (3 for rate-limit, 3 for network). Only retries `transient: true` errors; auth and validation errors fail immediately regardless. Each retry attempt is logged to stderr unless `--quiet` is set.
+
+  ```
+  npx -y linmux@0.1.0 issue list --json --retry 2
+  ```
+
+## Self-discovery (introspection)
+
+The CLI ships with three introspection commands that let an agent learn the surface without external docs:
+
+- `npx -y linmux@0.1.0 list-tools --json` — every command (curated + raw) with its one-line description.
+- `npx -y linmux@0.1.0 describe <command-or-operation> --json` — flag schema, JSON output schema, examples.
+- `npx -y linmux@0.1.0 schema --json` — the full Linear GraphQL schema (cached) for arbitrary queries.
+
+Always prefer `describe` over reading source. The `describe` output is generated from the same Zod schemas that drive command parsing, so it's the canonical contract for what a command accepts and returns.