## 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>
2.9 KiB
Sources
Accessed 2026-07-17. These official Linear pages are the only external sources used by this skill.
| Source | Establishes |
|---|---|
| https://linear.app/developers/graphql | Endpoint, authentication headers, GraphQL errors, issue identifiers, issue mutations, documents |
| https://linear.app/developers/pagination | Relay cursor pagination and bounded first requests |
| https://linear.app/developers/filtering | Server-side filters and relationship filters |
| https://linear.app/developers/rate-limiting | Request and complexity limits, headers, rate-limit errors |
| https://linear.app/developers/deprecations | No API versions, schema deprecation policy, changelog notices |
| https://linear.app/developers/oauth-2-0-authentication | OAuth tokens, scopes, refresh flow, and app actors |
| https://linear.app/developers/agent-interaction | Agent Sessions, activities, and session webhooks |
| https://linear.app/developers/agent-best-practices | Markdown and interaction guidance for agent workflows |
Schema Re-verification
Linear exposes its public GraphQL schema through Apollo Studio without login. Open the API schema from the GraphQL documentation, inspect the relevant query, mutation, input, and object fields, then test the narrow query in the Explorer. Record the exact selection and add or update an offline CLI contract test. Do not infer field shapes from names or from an older SDK.
For authentication behavior, verify the request header against the GraphQL and OAuth pages. For pagination or filters, verify both the connection arguments and the relevant filter input type. For mutation behavior, verify the mutation input and returned payload fields before implementation.
When official documentation and a live schema differ, treat the live public schema as the contract for field availability and retain the documentation URL plus access date as provenance. If an official page contains internally conflicting limit values, avoid encoding either value in CLI behavior and inspect response headers during credentialed operation.
Re-verified 2026-08-05 against the live public schema via anonymous introspection for the
mutation surface added in the project/state change: projectUpdate (returns ProjectPayload.project),
issueArchive/issueUnarchive (return IssueArchivePayload.entity), team.labels,
projectStatuses, users, and the ProjectFilter.accessibleTeams / CycleFilter.team filters.
Record the exact selection and update the offline CLI contract tests on any future change.
The CLI's offline tests verify parser, safety-gate, and error-handling contracts only. They do not replace a credentialed workspace smoke test for permissions, workspace-specific names, or returned resource data.
Document URLs
The CLI extracts a trailing 12-character slug ID from Linear document URLs as an observed current Linear URL convention, not an officially documented contract. If URL extraction fails, supply the document UUID or slug ID instead.