@codyswann/lisa 2.189.7 → 2.189.9

package/plugins/lisa-cursor/skills/lisa-linear-read-issue/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: lisa-linear-read-issue
+description: "Fetches the full scope of a Linear work item — Issue or Project — including metadata, description, acceptance criteria, all comments, attachments, native relations (blocks/blocked_by/relates_to/duplicates), Project parent (if any) with siblings, and sub-Issues. Produces a consolidated context bundle that downstream agents consume so they never act on a single item in isolation."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Read Linear Work Item: $ARGUMENTS
+
+Fetch the full scope of the item AND its related graph. Downstream agents must never act on an item in isolation — always call this skill first so they see blockers, project siblings, linked PRs, and historical comments.
+
+This skill is the destination of the `lisa-tracker-read` shim when `tracker = "linear"`. Read-only.
+
+Repository name for scoped comments and logs: `basename $(git rev-parse --show-toplevel)`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Phase 1 — Resolve Context
+
+1. If `$ARGUMENTS` matches `<TEAM>-<n>` → Issue mode.
+2. If `$ARGUMENTS` is a URL containing `/project/<slug>-<short-id>` → Project mode (extract `<short-id>`).
+3. Otherwise stop and report. Do NOT guess.
+4. Resolve team ID via `lisa-linear-access operation: list-teams({query: <teamKey>})`.
+
+## Phase 2 — Fetch Primary Item
+
+### Issue mode
+
+Call `lisa-linear-access operation: get-issue`. Extract and preserve:
+
+**Metadata**
+- Identifier, title, issue type (typically a label or workflow state), state, priority (0–4)
+- Assignee, creator, subscribers
+- Labels (capture full names — `status:*`, `component:*`, `priority:*`, `prd-*`)
+- Project (parent), parent Issue (if Sub-task), cycle, milestone (ProjectMilestone)
+- Estimate, due date
+- Created, updated, completed dates
+
+**Body**
+- Full description (preserve markdown)
+- **Validation Journey** section if present (pass verbatim to downstream)
+- Attachment URLs (capture, do not download unless needed)
+
+**Comments**
+Fetch ALL comments via `lisa-linear-access operation: list-comments({issueId: <id>})` in chronological order. Walk thread parents/children — Linear comments are threaded via `parentId`. Do not truncate. For each comment:
+- Author, timestamp, body
+- Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers.
+
+### Project mode
+
+Call `lisa-linear-access operation: get-project` with `includeMilestones: true`, `includeResources: true`. Extract:
+
+**Metadata**
+- ID, slug, name, state, priority, lead, color
+- Teams, labels, milestones, target date, start date
+- Created, updated dates
+
+**Body**
+- Description (markdown)
+- Attached documents — call `lisa-linear-access operation: list-documents({projectId})` then `lisa-linear-access operation: get-document` per result. Treat each as additional spec content.
+
+**Member Issues**
+- Call `lisa-linear-access operation: list-issues({project: <id>})` to enumerate the Project's Issues. Capture identifier, title, state, parent Issue (for sub-Issue tree).
+
+## Phase 3 — Fetch Attachments / Remote Links
+
+Linear stores remote URLs as attachments on the Issue. For each:
+
+- **GitHub PR or commit**: run `gh pr view <url> --json title,state,body,mergedAt,reviewDecision,comments,reviews` (PRs) or `gh api repos/<owner>/<repo>/commits/<sha>` (commits). Capture title, state, unresolved review comments, merge status.
+- **Confluence page**: capture title and URL. Do not fetch body unless a downstream task explicitly needs it.
+- **Dashboard / log link / external URL**: capture title and URL only.
+
+If `gh` is not authenticated, note "gh auth required" and continue — do not abort.
+
+## Phase 4 — Fetch Relations
+
+Linear native Issue relations are returned in the `get_issue` response under `relations`. Group by type:
+
+- `blocks` / `blocked_by`
+- `relates_to`
+- `duplicates` / `duplicated_by`
+
+For each related Issue, call `lisa-linear-access operation: get-issue` and capture:
+- Identifier, title, state, priority, assignee
+- Description (full, unless cancelled — then summary only)
+- Acceptance Criteria section
+- Last 10 comments (chronological)
+- Attachments (URLs only — skip deep PR fetch unless the relation is `blocks` or `blocked_by`)
+
+**Special handling for `blocked_by`:** fetch full PR details via `gh` for each blocker's GitHub attachments so the agent knows whether the blocker is actually shipped.
+
+For Project-level relationships (Project ↔ Project), Linear doesn't model native relations — check the Project description and resources for cross-references and capture them as plain links.
+
+## Phase 5 — Fetch Project Context
+
+If the primary Item is an Issue with a Project parent:
+
+1. Fetch the Project via `lisa-linear-access operation: get-project` — full description, milestones, labels, lead.
+2. Fetch Project documents (Phase 2 procedure).
+3. Find Project siblings via `lisa-linear-access operation: list-issues({project: <projectId>})` excluding the primary identifier.
+4. For each sibling, capture: identifier, title, state, priority, assignee, summary (first paragraph of description).
+5. If a sibling is `Started` or `In Review` with a different assignee, flag it prominently.
+
+If the primary Item IS a Project, Phase 5 is the same as fetching all member Issues (already done in Phase 2 Project mode).
+
+## Phase 6 — Fetch Sub-Issues
+
+If the primary Issue has children (sub-Issues), fetch each via `lisa-linear-access operation: get-issue`: identifier, title, state, assignee, description (first paragraph), Acceptance Criteria.
+
+## Phase 7 — Assemble Context Bundle
+
+Produce a single structured output the caller can pass verbatim to downstream agents.
+
+```text
+# Linear Work Item Context: <IDENTIFIER>
+
+## Primary Item
+- Identifier: <ID>
+- Type: <Issue | Project>
+- State: <state>
+- Priority: <0–4 or named>
+- Assignee: <name or none>
+- Project (parent): <project-slug — name> or none
+- Parent Issue: <ID — title> or none (Sub-task only)
+- Cycle: <name or none>
+- Milestone: <project-milestone or none>
+- Labels: <comma-separated>
+- Estimate: <points>
+
+### Description
+<full description>
+
+### Acceptance Criteria
+<criteria>
+
+### Validation Journey
+<section or "None">
+
+### Comments (<count>)
+<chronological comments, flagged items called out>
+
+### Attachments
+<list of URLs with titles>
+
+## Remote Links
+### Pull Requests (<count>)
+- <url> — <title> — <state> — <reviewDecision>
+  <body summary + unresolved review comments>
+
+### Confluence
+- <title> — <url>
+
+### Other
+- <title> — <url>
+
+## Relations
+### Blocks (<count>)
+<per-issue block>
+
+### Blocked By (<count>)
+<per-issue block with PR state>
+
+### Relates To (<count>)
+<per-issue block>
+
+### Duplicates / Duplicated By
+<per-issue block>
+
+## Project Context (when primary is an Issue under a Project)
+### Project <slug> — <name>
+- State: <state>
+- Description: <full markdown>
+- Milestones: <list>
+- Documents: <list of doc titles + identifiers>
+
+### Siblings In-Flight (<count>)
+- <ID> — <state> — <assignee> — <title>  **[FLAG: in progress by other assignee]**
+
+### Other Siblings (<count>)
+- <ID> — <state> — <title>
+
+## Sub-Issues (<count>)
+- <ID> — <state> — <assignee> — <title>
+
+## Summary for Downstream
+- Full item count pulled: <N>
+- Blockers still open: <list>
+- Related in-flight work: <list>
+- Relevant PRs: <list with state>
+```
+
+## Rules
+
+- Never summarize or truncate the primary item's description or Validation Journey.
+- Never skip a relation type, even if it seems unrelated — the downstream agent decides relevance.
+- If a related item returns an access error, capture the error and continue. Do not abort the read.
+- Flag in-flight sibling work prominently so the caller can avoid duplicate implementation.
+- If the Issue has no Project parent, state this explicitly — do not silently skip Phase 5.
+- Output is pure context. This skill never modifies the item.

package/plugins/lisa-cursor/skills/lisa-linear-sync/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: lisa-linear-sync
+description: "Syncs plan progress to a linked Linear Issue. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep Linear Issues in sync. The Linear counterpart of lisa-jira-sync and lisa-github-sync."
+allowed-tools: ["Bash", "Skill"]
+---
+
+# Sync Plan to Linear: $ARGUMENTS
+
+Post milestone updates to the linked Linear Issue at key plan-lifecycle moments. This skill is the destination of the `lisa-tracker-sync` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## When to invoke
+
+Callers (planning skills, lifecycle skills) invoke this skill at:
+
+| Milestone | What to post |
+|-----------|--------------|
+| Plan created | Plan contents (sections + ordered tasks) as a comment, suggest transition `Backlog → Todo` (label: `status:ready`) |
+| Implementation in progress | Branch URL + first commit, suggest transition `Todo → In Progress` (label: `status:in-progress`) |
+| PR ready for review | PR URL + summary, the implementation handoff comment, suggest transition `In Progress → In Review` (label: `status:code-review`) |
+| PR merged | Merge SHA + deploy environment (if known), suggest transition `In Review → Done` (label: `status:done`) |
+
+This skill **suggests** transitions but does not auto-transition the native Linear `state` field. It DOES update the `status:*` label set when the caller asks (the build queue is keyed off labels). Native state transitions remain a human / triage decision.
+
+## Input
+
+`$ARGUMENTS` is `<IDENTIFIER> <milestone>` where:
+
+- `<IDENTIFIER>` is the Linear Issue identifier (e.g. `ENG-123`). If not provided, the skill searches the active plan file for a linked Linear Issue.
+- `<milestone>` is one of `plan-created`, `implementation-in-progress`, `pr-ready`, `pr-merged`.
+- Optional tokens include `pr_url=<url>` for the live pull request and `merge_sha=<sha>` once merged.
+
+## Phase 1 — Resolve Issue
+
+1. If `$ARGUMENTS` includes an identifier, parse it.
+2. Else search for the active plan file (most recent file under `plans/`) and extract the linked Linear Issue identifier from its frontmatter.
+3. Fetch the Issue via `lisa-linear-access operation: get-issue` to confirm it exists.
+
+## Phase 2 — Compose Milestone Comment
+
+Per the milestone, build the comment body. Include:
+
+- A milestone header (e.g. `**Plan created** — <plan-file>`)
+- Relevant links (plan file, branch, PR)
+- A short summary (first 5 lines of the plan section / commit message / PR description)
+- The suggested status transition
+
+Example for `plan-created`:
+
+```markdown
+**Plan created** — `plans/feat-X.md`
+
+Sections:
+- Phase 1: Schema doc
+- Phase 2: Linear destination skills
+- ...
+
+Tasks: 7 ordered items.
+
+Next: implementation begins. Suggested status: **Todo** (label: `status:ready`).
+```
+
+## Phase 3 — Post Comment
+
+Call `lisa-linear-access operation: save-comment({issueId: <id>, body: <comment>})`.
+
+## Phase 3b — Ensure PR Backlink
+
+When `$ARGUMENTS` includes `pr_url=<url>` for `pr-ready` or `pr-merged`, ensure the Linear Issue has a durable ticket -> PR link:
+
+1. Prefer Linear's native GitHub attachment / pull request link when the integration has attached the PR through the branch name, PR title, or PR body issue identifier. Verify by re-reading the Issue and its attachments / relations where the Linear access layer exposes them.
+2. If native linkage is unavailable, unconfigured, cross-system, or cannot be verified, create or update a single managed Linear comment containing the PR URL. The comment must start with `[lisa-pr-link]` and include the milestone (`pr-ready` or `pr-merged`) and merge SHA when available.
+3. Keep the fallback idempotent: read existing comments where the access layer exposes them, find the `[lisa-pr-link]` comment for the same PR URL, and update/skip it instead of appending duplicates. If comment update is unavailable, skip when an identical managed comment already exists and otherwise add exactly one replacement comment with the stable marker.
+
+The PR branch/title/body identifier is the PR -> Linear side. This phase is the required Linear -> PR side.
+
+## Phase 4 — Update Status Label (when caller requests)
+
+If the caller passes `--update-label`, update the `status:*` label set via `lisa-linear-access operation: save-issue`:
+
+- `plan-created` → add `status:ready`
+- `implementation-in-progress` → remove `status:ready`, add `status:in-progress`
+- `pr-ready` → remove `status:in-progress`, add `status:code-review`
+- `pr-merged` → remove `status:code-review`, add `status:done`
+
+If the requested label doesn't exist on the team, create it via `lisa-linear-access operation: create-issue-label`.
+
+Verify exactly one `status:*` label remains after the update — having two simultaneously breaks the build-queue invariant.
+
+Without `--update-label`, this skill posts the comment only and does NOT touch labels.
+
+## Phase 5 — Parent Status Rollup (`--rollup`)
+
+When the caller passes `--rollup`, this skill **derives a parent/container's `status:*` label from the roll-up of its children** instead of acting on a leaf. A **Project** (the Epic equivalent) rolls up from its Issues; an **Issue** rolls up from its sub-Issues. This implements the Linear child-issue-status arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy.
+
+**Resolve the child set the same way `lisa-linear-read-issue` does** — `lisa-linear-access operation: list-issues({project: <id>})` for a Project's Issues, or `lisa-linear-access operation: get-issue` per child for an Issue's sub-Issues (via `parentId`). Capture each child's `status:*` label. If the item has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
+
+**Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the Linear env-keyed `done` map, e.g. `status:on-dev < status:on-stg < status:done`) and take the first match** (canonical roles from `config-resolution`; Linear label map is `status:blocked`, `status:in-progress`, `status:code-review`, env-keyed `done`):
+
+| If among the required child leaves… | Derived parent role | Linear label |
+|---|---|---|
+| any child carries `status:blocked` | `blocked` | `status:blocked` |
+| else **every** required child has shipped to some env (each at a `done`-map label, e.g. `status:on-dev`/`status:on-stg`/`status:done`) | `done[min-env]` | the **least-advanced** env label among them (all `status:on-stg` → `status:on-stg`; mixed dev+staging → `status:on-dev`; all production → `status:done`) |
+| else any child has **started** (`status:in-progress` / `status:code-review`, or shipped to an env while a sibling has not) | `claimed` | `status:in-progress` |
+| else (children exist, none started) | — | unchanged — parent keeps its non-ready container label |
+
+- **Blocked dominates** — one blocked child surfaces `status:blocked` on the parent even while siblings progress.
+- **Least-advanced env wins** — the parent reaches an env only when every required child has reached at least that env; it never sits ahead of its laggard child. Native completion (moving the workflow `state` to Done) fires only when the resolved env is the production `status:done`, never at `status:on-dev`/`status:on-stg`.
+- **"Required" children only** — won't-do / optional (e.g. `Canceled`) children do not hold the parent open.
+- **Recursive** — a Project reaches an env only when its Issues have themselves rolled up to at least that env. Evaluate bottom-up.
+- **Never set the parent to `status:ready`** — `ready` is leaf-only. Rollup only moves the parent between non-ready container labels.
+
+**Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to the single `status:done` label, the only env rung is production, and the lifecycle is `status:ready → status:in-progress → status:code-review → status:done` with **no** dev/staging promotion hops; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to intermediate env labels (`status:on-dev`/`status:on-stg`).
+
+**Apply the derived label** via `lisa-linear-access operation: save-issue` (Project or Issue), removing the parent's existing `status:*` and adding the derived one so exactly one `status:*` label remains. Post an idempotent rollup comment naming the derived state and the child tally. The native Linear `state` is **not** auto-transitioned — only the `status:*` label, mirroring the `--update-label` rule. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's label untouched.
+
+## Rules
+
+- Never auto-transition the native Linear `state` — only the label, and only when the caller explicitly asks (`--update-label`, or `--rollup` for parent derivation per the `leaf-only-lifecycle` rule).
+- Rollup derives a *parent's* `status:*` label from its children and never sets a parent to `status:ready`. It cites the `leaf-only-lifecycle` rule by slug rather than restating the state machine.
+- Never post empty or minimal comments — if a milestone has no meaningful content, skip the post.
+- Do not delete prior milestone comments. They are the audit trail.
+- If `save_comment` fails, retry once. If it fails again, surface the error.
+- Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.