mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-16 05:56:30 +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

3.9 KiB

Raw Blame History

Linear Domain And Workflows

Linear organizes work around teams. Issues belong to a team and can be associated with a project and cycle. A project expresses a larger outcome; a cycle groups time-bounded team work. Use an issue for actionable work and a document for durable narrative, planning, or reference material.

Workflow Semantics

Workflow states have types including triage, backlog, unstarted, started, completed, and canceled. Creating an issue without stateId places it in the team's first Backlog state, or in Triage when that feature is enabled. Priorities are numeric in the API: 0 none, 1 urgent, 2 high, 3 medium, and 4 low.

Issue IDs can be UUIDs or shorthand identifiers such as ENG-42. Obtain object UUIDs in Linear with the command menu's “Copy model UUID” action. A parent issue groups child issues; use children only when their work is independently actionable and trackable. Assignees resolve by exact name or email within the workspace; labels resolve by exact name within the issue's team; due dates are ISO dates (YYYY-MM-DD). issue create accepts --project, --parent, --assignee, --label, --state, and --due; issue update accepts --assignee, --label (add), --remove-label, --due, and --project. Archived issues are excluded from default reads; issue archive and issue unarchive move an issue across that boundary and use the same confirmation gate as other mutations.

Project Semantics

Projects carry a status, a priority, start and target dates, a lead, and members. project update changes the name, description, status, dates, or priority and requires the same dry-run/confirm gate as issue mutations. Linear's projectUpdate rejects project descriptions longer than 255 characters with a generic argument-validation error; keep project descriptions at 255 characters or fewer. Project statuses are workspace-defined, so resolve the destination status by its exact name or type inside the workspace rather than assuming a universal set.

Choosing A Work Item

Start with an existing issue whenever a request refers to known work. Search by distinctive words, then inspect the result before changing it. Use the issue identifier in follow-up work because it is shorter and is accepted by the public API.

Use a project when the user asks about a larger initiative or its status. Use a cycle when the user asks about a team's current or planned timebox. The mutation boundary stays bounded: issues, projects, workflow states, and comments are first-class verbs; cycles, teams, and documents remain read-only, and destructive deletion stays behind raw.

Descriptions, comments, and documents support Markdown. Plain Linear URLs to users, issues, projects, and other resources become mentions in the Linear UI. Collapsible Markdown sections use +++ Title to open and +++ to close.

Safe Mutation Recipe

Read the target issue and relevant team, project, cycle, or state first.
Check for an existing issue with issue search before creating another one.
State the exact change and recovery path to the user.
Run the mutation with --dry-run --json; friendly references are only resolved during a live run.
Run the same command with --confirm --json only after confirmation.
Report the returned identifier and outcome. If a change is wrong, use issue update, issue move, project update, or issue unarchive to restore the prior value rather than guessing.

Use an issue comment for a dated, issue-specific update. Use a document when the information must remain useful beyond one issue. Do not create duplicates for work that an existing issue already covers; link or update the existing issue instead.

Do not treat a completed or canceled state as reversible without checking the team's workflow and the requested recovery path. State names are workspace-defined, so resolve the exact destination inside the issue's own team rather than assuming a universal “Done” state.

3.9 KiB Raw Blame History