## What this adds Implements the request in #287 and the Tier 1 audit gaps for the `linear` skill's `scripts/linear` CLI, reconciled against the live Linear GraphQL schema. ### New verbs - `linear project update` — name, description, status, start/target dates, priority, with the same `--dry-run`/`--confirm` gate as issue mutations, and a local 255-character description guard matching Linear's `projectUpdate` limit (Linear rejects longer descriptions with a generic error). - `linear issue archive` / `linear issue unarchive` — both gated, returning `IssueArchivePayload.entity`. - `linear state list --team ENG` — first-class workflow-state discovery (previously states were only visible in the `issue move` failure path). ### Richer issue verbs - `issue create` now accepts `--project`, `--parent`, `--assignee`, `--label` (repeatable), `--state`, `--due`. - `issue update` now accepts `--assignee`, `--label` (add), `--remove-label`, `--due`, `--project`. ### Resolution rules (all require exactly one match, mirroring `resolve_team`) - Project: UUID or exact name - Parent: issue identifier or UUID - Assignee: exact name, display name, or email (via `users`) - Label: exact name within the issue's team (via `team.labels`) - Workflow state: exact name within the issue's team (existing `team.states` resolver, now reusable for `--state` on create) - Project status: exact name or type (via `projectStatuses`) ### Docs, tests, evals - SKILL.md command map, state-change gate, and error/recovery sections; README; `domain-and-workflows.md` (project semantics + 255-char limit), `graphql-contract.md` (resolution queries), `integration-boundaries.md` (intentional exclusions list), `sources.md` (2026-08-05 schema re-verification note). - 15 new offline tests (45 total) covering resolution, gates, dry-run intent, payload shapes, and field guards. - Added a sixth eval case (`safe-project-and-issue-mutations`). ## Validation - `python3 -m unittest linear/tests/test_linear.py` — 45/45 pass - `python3 scripts/validate-evals.py`, `ruby scripts/validate-skills.rb`, `python3 scripts/check-artifacts.py`, `python3 scripts/eval-coverage.py --modified-from origin/main`, skill-quality validator, marketplace/codex/llms freshness, jscpd — all green locally Closes #287 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
3.1 KiB
Integration Boundaries
| Need | Use |
|---|---|
| A bounded terminal read or carefully confirmed issue mutation | This CLI |
| An interactive tool connection inside an AI client | Linear's native MCP integration |
| A documented operation absent from the focused command surface | linear raw with a narrow GraphQL query |
| A multi-user application acting for each user | OAuth 2.0 with user access tokens |
| A workspace agent or service actor | OAuth actor authorization or client credentials, as documented by Linear |
| An agent that receives delegation, mentions, or user follow-ups in Linear | Agent Session and webhook APIs |
This CLI intentionally does not run an OAuth callback server, manage refresh tokens, receive webhooks, create Agent Sessions, or emit Agent Activities. Those paths require an application integration with secure token storage, webhook verification, and lifecycle handling.
Agent Session webhooks notify a configured agent when it is mentioned, delegated an issue, or receives a follow-up prompt. Their receiver must respond within five seconds, and a new session should send an activity or external URL within ten seconds. These availability requirements do not fit a one-shot terminal command.
Agent Activities are semantic progress events such as thoughts, actions, elicitation requests, responses, and errors. They belong to an Agent Session and are validated by Linear. Do not use ordinary issue comments as a substitute when building an embedded Linear agent integration.
OAuth application integrations should request the smallest documented scope. The documented
admin scope is not a default; use it only when the integration truly needs administrative API
access. This terminal CLI receives an already-issued environment credential and never chooses
scopes itself.
For a standalone agent operating Linear from a terminal, prefer this CLI's read commands and its
--dry-run plus --confirm mutation gate. For an unsupported but documented GraphQL operation,
use raw only after confirming the exact field, permissions, target, scope, and rollback path.
Use the GraphQL schema explorer before promoting a repeated raw operation into this CLI. A command
belongs in the focused surface only when it has a recurring agent workflow, a clear safe default,
and a bounded contract. Promotion is complete only when CLI help and routing, SKILL/README command
maps, official source provenance, offline request/failure tests, schema re-verification, and the
repository regression gates all agree. Until then, keep the verified operation behind narrow raw.
Intentional Exclusions
These documented operations stay behind raw on purpose and are not promoted to first-class
verbs: issue, project, cycle, and document deletion (irreversible by default); attachment uploads
(multipart, outside the JSON endpoint); bulk issue create/update (issueBatchCreate/issueBatchUpdate);
team, user, workflow-state, and organization administration; and integrations, webhooks, initiatives,
customers, and notifications. If a workflow needs one of these repeatedly, review the promotion
criteria above before adding a verb.