@codyswann/lisa 2.195.4 → 2.195.6

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

@@ -0,0 +1,200 @@
+---
+name: lisa-linear-read-issue
+description: "Fetches the full scope of a…"
+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/.codex-plugin/skills/lisa-linear-read-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Read Issue"
+short_description: "Fetches the full scope of a…"
+default_prompt:
+  - "Use $lisa-linear-read-issue: Fetches the full scope of a…."

package/plugins/lisa/.codex-plugin/skills/lisa-linear-sync/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: lisa-linear-sync
+description: "Syncs plan progress to a linked…"
+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.

package/plugins/lisa/.codex-plugin/skills/lisa-linear-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Sync"
+short_description: "Syncs plan progress to a linked…"
+default_prompt:
+  - "Use $lisa-linear-sync: Syncs plan progress to a linked…."