mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-17 06:26:31 +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>
47 lines
2.9 KiB
Markdown
47 lines
2.9 KiB
Markdown
# 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.
|