mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-17 14:36:29 +03:00
b8a5092c26
## 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>
48 lines
3.1 KiB
Markdown
48 lines
3.1 KiB
Markdown
# 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.
|