mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00

Files

T

b8a5092c26 feat(linear): project mutations and richer issue verbs in CLI (#288 )

## 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>

2026-08-05 16:43:36 -04:00

2.0 KiB

Raw Blame History

Linear: focused issue and document operations from the terminal

Why Install This Skill

Give an agent a small, predictable way to work with Linear without running an MCP server or installing a package. It can find teams, projects, cycles, workflow states, and issues, inspect documents, and make carefully previewed changes to issues, projects, and comments through Linear's public API.

The CLI stays intentionally narrow: it favors bounded reads, JSON output (compact with --json, indented without it), and dry-run previews over a large API mirror. That makes routine project-management work easier to audit.

What You Get

Path	Provides
`scripts/linear`	Dependency-free Python CLI for Linear GraphQL reads and confirmed mutations (issues, projects, workflow states, comments)
`SKILL.md`	Agent workflow, safety gate, command routing, and official API links
`tests/test_linear.py`	Offline tests for parsing, safety gates, GraphQL contracts, and dry-run behavior
`references/`	Linear workflow, GraphQL, integration-boundary, and source guidance

Quick Start

Set one credential for live API calls. Use a placeholder, never a real token in documentation or shell history.

export LINEAR_API_KEY='your-linear-personal-api-key'
# Or: export LINEAR_ACCESS_TOKEN='your-oauth-access-token'

linear/scripts/linear team list --limit 20 --json
linear/scripts/linear issue search "customer import" --json

Preview a write before confirming it:

linear/scripts/linear issue create --team ENG --title "Review import errors" --dry-run --json

Triggers

List, search, inspect, create, update, move, or comment on Linear issues
Find Linear teams, projects, cycles, or documents
Run a small, explicit Linear GraphQL query from a terminal

Requirements

Python 3.8 or later; no third-party packages
Network access for live API calls
LINEAR_API_KEY or LINEAR_ACCESS_TOKEN for live API calls
A Linear workspace and credentials with permission for the requested action

2.0 KiB Raw Blame History