@codyswann/lisa 2.4.0 → 2.5.1

package/plugins/src/base/skills/linear-prd-intake/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: linear-prd-intake
+description: "Scans a Linear workspace (or a specific team) for projects labelled `prd-ready` and runs each one through the dry-run validation pipeline. Projects that pass every gate get tickets written and the label flipped to `prd-ticketed`; projects that fail get clarifying-question comments (on a sentinel feedback issue under the project) and the label flipped to `prd-blocked`. Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (linear-to-jira, jira-validate-ticket, jira-source-artifacts, product-walkthrough)."
+allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_teams"]
+---
+
+# Linear PRD Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+- A Linear **workspace** URL — scans every project in the workspace whose labels include `prd-ready`. Example: `https://linear.app/acme`.
+- A Linear **team** URL or team key — scans every project on the team whose labels include `prd-ready`. Example: `https://linear.app/acme/team/ENG/projects` or bare `ENG`.
+- The literal token `linear` — equivalent to "the default Linear workspace"; only valid if `LINEAR_WORKSPACE` is configured.
+
+Run one intake cycle against that scope. Each project with the `prd-ready` label is claimed, validated, and routed to either `prd-blocked` (with clarifying comments on a sentinel feedback issue) or `prd-ticketed` (with JIRA tickets created).
+
+This skill is the Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake`. The phases, gates, comment templates, and rules are identical — the only differences are (1) the lifecycle is encoded as **project labels** instead of a Status property, (2) the fetch / update tools are Linear MCP, and (3) clarifying-question comments land on a sentinel feedback Issue under the project (because Linear's MCP does not expose project-level comments). Keep all three skills behaviorally aligned: when changing intake logic, change them together.
+
+## Confirmation policy
+
+Do NOT ask the caller whether to proceed. Once invoked with a workspace/team scope, run the cycle to completion — claim, validate, branch to `prd-blocked` or `prd-ticketed`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill; re-prompting defeats the purpose of a background batch.
+
+Specifically forbidden:
+
+- Previewing projected scope (epic count, story count, write count) and asking whether to continue.
+- Offering A/B/C-style choices like "proceed / skip / dry-run only" — the documented behavior IS the default.
+- Pausing because a PRD looks large, has many open questions, or is likely to end in `prd-blocked`. `prd-blocked` is a valid terminal state of this lifecycle, not a failure mode — routing a PRD to `prd-blocked` with gate-failure comments is exactly how this skill communicates "the PRD needs more work before it can be ticketed." That outcome is success.
+- Pausing because the dry-run validation looks expensive. The cost of one cycle is bounded; the cost of stalling a scheduled cron waiting on a human is unbounded.
+
+The only legitimate reasons to stop early:
+
+- Missing scope argument or required configuration (`JIRA_PROJECT`, `JIRA_SERVER`, `LINEAR_WORKSPACE`, `E2E_BASE_URL`, etc.). Surface the missing key(s) and exit this cycle — never invent values.
+- Workspace/team unreachable, or the labelling convention not yet adopted (no projects carry any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`). Surface and exit.
+- Empty `prd-ready` set. Exit cleanly with `"No Linear projects labelled prd-ready. Nothing to do."`
+
+## Lifecycle assumed
+
+The Linear PRD lifecycle is encoded as **project labels** (we deliberately do NOT key off Linear's native project state, since project state is product's day-to-day signal and we don't want to fight it). Exactly one of these labels is expected on a project at any time:
+
+```text
+prd-draft → prd-ready → prd-in-review → prd-blocked | prd-ticketed → prd-shipped
+            (product)    (us)            (us)                          (product)
+```
+
+This skill ONLY transitions:
+
+- `prd-ready` → `prd-in-review` (claim)
+- `prd-in-review` → `prd-blocked` (gate failures or coverage gaps)
+- `prd-in-review` → `prd-ticketed` (success)
+- `prd-ticketed` → `prd-blocked` (post-write coverage gaps from Phase 3e)
+
+It never adds, removes, or touches `prd-draft` or `prd-shipped`. Those labels are owned by product.
+
+A "transition" means: remove the old lifecycle label and add the new one in a single `save_project` call (passing the full new label set in the `labels` array). The skill MUST verify that exactly one lifecycle label exists on the project after the update — having two simultaneously breaks idempotency.
+
+If the project does not yet use `prd-*` labels, this skill cannot run. Adopting the convention is a one-time setup the project owner does (see "Adoption" at the bottom of this file).
+
+## Phases
+
+### Phase 1 — Resolve the scope
+
+1. Parse `$ARGUMENTS`:
+   - Workspace URL (`https://linear.app/<workspace>`) → extract workspace slug; the scope is the entire workspace.
+   - Team URL containing `/team/<KEY>/...` → extract team key; the scope is that team.
+   - Bare team key → use as-is; the scope is that team.
+   - The literal `linear` → fall back to `LINEAR_WORKSPACE` env var; error if not set.
+2. Verify the scope is reachable:
+   - For a workspace: call `mcp__linear-server__list_teams` and confirm at least one team is returned (non-empty workspaces are readable; empty results indicate auth or workspace-mismatch).
+   - For a team: call `mcp__linear-server__list_teams({query: <KEY>})` and confirm the team resolves.
+3. Resolve the project-label IDs for `prd-ready`, `prd-in-review`, `prd-blocked`, `prd-ticketed` via `mcp__linear-server__list_project_labels`. Cache them — every transition uses these IDs. If any of the four are missing, surface a label-convention error and exit (see "Adoption").
+
+### Phase 2 — Find Ready PRDs
+
+Call `mcp__linear-server__list_projects({label: "prd-ready", ...scope-filter})`:
+
+- For a workspace scope: pass `label: "prd-ready"` only.
+- For a team scope: pass `label: "prd-ready"` AND `team: "<KEY>"`.
+
+The query returns the list of candidate projects with IDs, names, and label sets. For each candidate, confirm that exactly one lifecycle label is present (the API filter is `prd-ready`, but a project could have ended up with two labels by hand — that's a misconfiguration, not a normal queue entry).
+
+If the result set is empty, run a secondary query to distinguish between a genuinely empty queue and a workspace/team that has not yet adopted the label convention:
+
+- Secondary query: `list_projects({...scope-filter})` with no label filter, then in-process check whether any returned project carries any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`.
+
+If the secondary query shows zero projects carrying any `prd-*` label → the convention has not been adopted. Surface a misconfiguration message: `"No Linear projects in this scope carry prd-* labels. If this is a new project, apply the prd-ready label to projects that are ready for ticketing (see Adoption section)."` Exit with an error — this is a setup issue, not a normal idle cycle.
+
+If the secondary query shows projects with other `prd-*` labels but none with `prd-ready` → the queue is genuinely empty (all PRDs are already in-review, blocked, ticketed, or shipped). Exit cleanly with `"No Linear projects labelled prd-ready. Nothing to do."`
+
+### Phase 3 — Process each Ready PRD
+
+For each project (process serially to keep label transitions auditable):
+
+#### 3a. Claim
+
+Transition labels via `mcp__linear-server__save_project({id, labels})`: pass the full new label set with `prd-ready` removed and `prd-in-review` added. This is the idempotency lock — a re-entrant cycle running concurrently won't see this project because its query filters on `label: "prd-ready"`.
+
+If the update fails (permission error, race condition), log it and skip this project. Do not proceed to validation on a project you didn't successfully claim.
+
+The `save_project` call must preserve all other project fields (description, state, priority, lead, dates, teams, initiatives) untouched — pass only `id` and the new `labels` array. This skill never edits PRD body content.
+
+#### 3b. Dry-run validation
+
+Invoke the `lisa:linear-to-jira` skill with `dry_run: true` and the project's URL. The skill returns a structured report containing:
+- The planned ticket hierarchy
+- Per-ticket validation verdicts and remediation
+- An overall PASS / FAIL verdict
+- A failure count
+
+This call also indirectly invokes `lisa:jira-source-artifacts` (artifact extraction + classification) and `lisa:product-walkthrough` (when the PRD touches existing user-facing surfaces). All gate logic lives in `lisa:jira-validate-ticket`, which `lisa:linear-to-jira` calls per ticket.
+
+#### 3c. Branch on the verdict
+
+**If `PASS`** (every planned ticket passed every applicable gate):
+
+1. Re-invoke `lisa:linear-to-jira` with `dry_run: false` to actually write the tickets. This re-runs Phases 1-5 and runs the preservation gate (Phase 5.5).
+2. Capture the created ticket keys from the skill's output.
+3. Ensure the project has a sentinel feedback issue (see "Sentinel feedback issue" below for the helper). Post a comment on it via `mcp__linear-server__save_comment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the prd-shipped label to the Linear project after the work is delivered."`
+4. Transition labels: remove `prd-in-review`, add `prd-ticketed` via `save_project`.
+5. **Run Phase 3e (coverage audit)** before considering this PRD done.
+
+**If `FAIL`** (one or more planned tickets failed one or more gates):
+
+The audience for these comments is the **product team**, not engineers. They are not familiar with JIRA gate IDs, validator vocabulary, or skill internals. Follow the rules below strictly — the goal is for a non-engineer product owner to read a comment, understand what is unclear, and know what to do next.
+
+##### 3c.1 Partition failures
+
+1. Drop every failure where `product_relevant = false`. Those are internal data-quality problems — the agent should fix its own spec rather than ask product to clarify a missing core field. Record the dropped failures under `Errors` in the cycle summary so engineers can see them; never surface them on the PRD.
+2. Group the remaining product-relevant failures by `prd_anchor` (which, for Linear, is a sub-issue identifier when the failure traces to a specific issue, or `null` otherwise). Failures that share an anchor become one comment thread on that issue. Failures with `prd_anchor: null` are batched into one comment on the sentinel feedback issue, since they have no source sub-issue to attach to.
+
+##### 3c.2 Render each comment
+
+Ensure the project has a sentinel feedback issue (see helper below). For each anchored group (`prd_anchor` is a sub-issue identifier), post a comment on THAT sub-issue via `mcp__linear-server__save_comment({issueId: <prd_anchor>, body: <template>})`. For the unanchored group, post a single comment on the sentinel feedback issue using the same template, prefixed with `Issues without a specific sub-issue anchor:` and one block per failure.
+
+If `save_comment` fails for a specific anchored sub-issue (the issue was deleted between fetch and post, or the agent lacks comment permission), fall back to the sentinel feedback issue for that group. Do not silently drop the failure.
+
+##### 3c.3 Comment template
+
+Each comment body MUST contain these four parts, in this order, no exceptions:
+
+```text
+[<Category badge>] <prd_section heading text>
+
+**What's unclear:** <validator's `what` field, verbatim — already product-readable>
+
+**Recommendation:** <validator's `recommendation` field, verbatim — must contain 1–3 concrete options, never a generic "please clarify">
+
+**Action:** Update this section in the PRD, then replace the `prd-blocked` label with `prd-ready` on the Linear project and Claude will re-run intake.
+```
+
+If multiple failures share an anchor, render each as its own `**What's unclear:** ... **Recommendation:** ...` block within the same comment, separated by horizontal lines (`---`). Keep the single `[Category badge]` heading at the top using the most-severe / most-blocking category from the group.
+
+##### 3c.4 Category badges
+
+Use these exact badge labels — they are the validator's category values translated for product readers:
+
+| Validator category | Badge label |
+|---------------------|-------------|
+| `product-clarity` | `[Product clarity]` |
+| `acceptance-criteria` | `[Acceptance criteria]` |
+| `design-ux` | `[Design / UX]` |
+| `scope` | `[Scope]` |
+| `dependency` | `[Dependency]` |
+| `data` | `[Data]` |
+| `technical` | `[Technical]` |
+
+`structural` failures must never reach this step (filtered in 3c.1). If you see one here, treat it as an Error and surface internally.
+
+##### 3c.5 Forbidden in product comments
+
+- Gate IDs (`S4`, `F2`, etc.). Never appear in a comment body.
+- JIRA terminology that has no product meaning (e.g. "Gherkin", "epic parent", "issue link", "validation journey", "sub-task hierarchy"). Paraphrase before posting.
+- Internal skill names (`lisa:jira-validate-ticket`, `linear-to-jira`).
+- Engineering shorthand (`AC`, `OOS`, `repo`, `env var`).
+- "Clarify this" / "Please specify" without candidate resolutions. The validator is required to provide candidates; if `recommendation` is empty or vague, treat the failure as an Error and surface internally rather than posting a useless comment.
+
+##### 3c.6 Label transition
+
+After all comments are posted (anchored groups + the optional sentinel-issue summary), transition labels: remove `prd-in-review`, add `prd-blocked` via `save_project`. Do NOT write any JIRA tickets.
+
+#### 3d. Continue
+
+Move to the next Ready PRD. One PRD failing does not affect others.
+
+#### 3e. Coverage audit (mandatory after prd-ticketed)
+
+Per-ticket gates prove each ticket is well-formed; they do NOT prove the *set* of created tickets covers the *whole* PRD. Silent drops happen — invoke the `lisa:prd-ticket-coverage` skill to catch them.
+
+1. Invoke `lisa:prd-ticket-coverage` with `<PRD URL> tickets=[<created ticket keys from 3c step 2>]`. The coverage skill auto-detects the PRD vendor from the URL.
+2. Read the verdict:
+
+   | Verdict | Action |
+   |---------|--------|
+   | `COMPLETE` | Done. Leave label as `prd-ticketed`. Move to next PRD. |
+   | `COMPLETE_WITH_SCOPE_CREEP` | Post an advisory comment on the sentinel feedback issue naming the scope-creep tickets (so product can decide whether to close them as out-of-scope). Leave label as `prd-ticketed`. |
+   | `GAPS_FOUND` | The created ticket set is incomplete. (a) For each gap, post a comment using the same product-facing template as Phase 3c.3 — anchored on the relevant sub-issue when `prd_anchor` is non-null, on the sentinel feedback issue otherwise; category badge from the gap's `category` field; `What's unclear` and `Recommendation` from the audit report's `what` and `recommendation` fields. Apply the same forbidden-language rules from Phase 3c.5. (b) Post one summary comment on the sentinel feedback issue listing the tickets that *were* successfully created (so product knows what to keep vs. what to extend). (c) Transition labels from `prd-ticketed` back to `prd-blocked` via `save_project`. |
+   | `NO_TICKETS_FOUND` | Should not happen if step 2 succeeded. If it does, log it as an Error in the cycle summary and leave label as `prd-ticketed` with a comment flagging the audit failure for human review. |
+
+3. The created tickets remain in JIRA regardless of the verdict — they are valid in their own right. The audit only tells us whether *more* are needed.
+
+### Phase 4 — Summary report
+
+After processing every Ready PRD, emit a summary:
+
+```text
+## linear-prd-intake summary
+
+Scope: <workspace-slug | team-key> (<URL>)
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+PRDs processed: <n>
+- prd-ticketed: <n>
+  - <project name> → <epic-key> + <story-count> stories + <subtask-count> sub-tasks (coverage: COMPLETE | COMPLETE_WITH_SCOPE_CREEP)
+- prd-blocked: <n>
+  - <project name> → <gate-failure-count> gate failures (pre-write) OR <gap-count> coverage gaps (post-write)
+- Errors (claim failed, etc): <n>
+  - <project name> — <reason>
+
+Total JIRA tickets created: <n>
+Coverage audit summary: <n> COMPLETE / <n> COMPLETE_WITH_SCOPE_CREEP / <n> GAPS_FOUND
+```
+
+Print to the agent's output. Do not write this summary to Linear or JIRA — it's an operational record for the human.
+
+## Sentinel feedback issue
+
+Linear's MCP does not expose project-level comments. To preserve the comment-based feedback channel that Notion and Confluence intake have natively, this skill maintains a single sentinel **feedback Issue** under each project. All clarifying-question comments that don't anchor to a specific sub-issue land here.
+
+The sentinel issue is identified by:
+
+- A stable title: `"PRD intake: clarifying questions"`
+- A stable label: `prd-intake-feedback` (issue-level label, distinct from the project-level `prd-*` labels)
+- Membership in the project being processed
+
+Helper behavior — call this **before** posting any clarifying-question comment in Phase 3c or 3e:
+
+1. Search for an existing feedback issue: `list_issues({project: <id>, label: "prd-intake-feedback"})`. If multiple match (shouldn't happen, but defensive), use the oldest by `createdAt`.
+2. If none exists: ensure the `prd-intake-feedback` label exists on the project's team via `list_issue_labels` then `create_issue_label` if needed; then create the sentinel via `save_issue({team: <team-id>, project: <id>, title: "PRD intake: clarifying questions", description: "Auto-created by lisa:linear-prd-intake. This issue collects clarifying-question comments that don't anchor to a specific sub-issue. Do not close manually — it is reused across intake cycles.", labels: ["prd-intake-feedback"]})`. Capture the new issue identifier.
+3. Return the issue identifier to the caller for use in `save_comment({issueId: <id>, body: ...})`.
+
+Idempotency: the helper finds-or-creates. Re-runs of the cycle reuse the same sentinel issue. Comments accumulate; product reads top-down to see the latest cycle's findings. Do not delete or repurpose old comments — history is the audit trail.
+
+## Idempotency & safety
+
+- **Single-cycle scope**: this skill processes the `prd-ready` set as it exists at the start of Phase 2. New `prd-ready` projects added mid-cycle are picked up next run.
+- **No writes outside the lifecycle**: this skill only ever writes to JIRA via `lisa:linear-to-jira` (which delegates to `lisa:jira-write-ticket`), only ever changes Linear project labels among `prd-in-review`, `prd-blocked`, `prd-ticketed`, only ever creates/comments on the sentinel feedback issue (never any other Linear issue). It never edits project descriptions, never edits Linear documents, never touches `prd-draft` or `prd-shipped`, never archives or deletes projects.
+- **Claim-first ordering**: the label flip to `prd-in-review` happens BEFORE validation runs, so a re-entrant call won't double-process.
+- **Failure isolation**: an exception processing one project must not stop the cycle. Catch, record under "Errors" in the summary, continue to the next project. The project that errored is left labelled `prd-in-review` — the human investigates from there.
+- **Single-label invariant**: after every transition, verify exactly one lifecycle label is present on the project. If two are present (rare race), surface as an Error and skip — do NOT auto-resolve, the human decides.
+
+## Configuration
+
+Same env vars as `lisa:linear-to-jira` — `JIRA_PROJECT`, `JIRA_SERVER`, `LINEAR_WORKSPACE`, `E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL`. If any required value is missing, surface the missing key(s) and exit this cycle — never invent values.
+
+## Rules
+
+- Never write to JIRA outside of `lisa:linear-to-jira` → `lisa:jira-write-ticket`. The validator's verdict gates progress; bypassing it produces broken tickets.
+- Never add or remove a label this skill doesn't own (`prd-in-review`, `prd-blocked`, `prd-ticketed`). Product owns `prd-draft`, `prd-ready`, `prd-shipped`. The issue-level `prd-intake-feedback` label is owned by this skill but is not a lifecycle label.
+- Never edit a project's description or any attached Linear document. Communication with product happens only through comments on sub-issues or on the sentinel feedback issue.
+- Never post a single dump of all gate failures on one comment. One comment per `prd_anchor` group on the relevant sub-issue (or one comment on the sentinel feedback issue for unanchored failures only). Comments must be sub-issue-anchored where possible, categorized, plain-language, and contain a concrete recommendation.
+- Never include a gate ID, internal skill name, or engineering shorthand in a comment body.
+- Never run more than one intake cycle concurrently against the same scope. This skill assumes serial execution.
+- Never close, archive, or otherwise modify the sentinel feedback issue except to post comments on it. Its longevity is the audit trail.
+- If `lisa:linear-to-jira` returns errors, treat them as gate failures: comment + `prd-blocked`. Don't silently fail.
+
+## Adoption (one-time per project)
+
+Before this skill can run against a Linear workspace or team, the team must adopt the `prd-*` project-label convention:
+
+1. Apply `prd-ready` to projects that are ready for ticketing (replaces the Notion `Status = Ready` flip and the Confluence `prd-ready` page label).
+2. Reserve `prd-in-review`, `prd-blocked`, `prd-ticketed` for this skill — humans should not set them manually except to recover from an error.
+3. (Optional but recommended) Add `prd-draft` for in-progress PRDs and `prd-shipped` for delivered work, so the full lifecycle is visible at a glance.
+4. The labels must exist as **project labels** in Linear (`list_project_labels` should return them). Issue-level labels with the same names won't work; Linear keeps the two label kinds separate.
+
+If the workspace hasn't adopted these labels, the first run exits with a label-convention error (not the idle empty-set message) — this distinguishes a setup issue from a genuinely empty queue so operators know to apply the convention rather than assuming the queue is drained. See Phase 2 for how the skill detects this case.

package/plugins/src/base/skills/linear-to-jira/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: linear-to-jira
+description: >
+  Break down a Linear PRD (a Linear Project) into JIRA epics, stories, and sub-tasks. Use this skill
+  whenever the user shares a Linear project URL and wants it converted into JIRA tickets, or asks to
+  "break down this Linear project", "create tickets from a Linear project", "turn this Linear PRD into
+  JIRA", or similar. This skill mirrors `lisa:notion-to-jira` and `lisa:confluence-to-jira` for projects
+  whose PRDs live in Linear — the workflow, gates, dry-run mode, and validation rules are identical;
+  only the source-of-truth tool surface differs (Linear MCP instead of Notion / Confluence MCP).
+allowed-tools: ["Skill", "Bash", "mcp__linear-server__get_project", "mcp__linear-server__list_projects", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_comments", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_teams", "mcp__atlassian__getJiraIssueRemoteIssueLinks"]
+---
+
+# Linear PRD to JIRA Breakdown
+
+Convert a Linear PRD (a Linear **Project**) into a structured JIRA ticket hierarchy: Epics > Stories > Sub-tasks.
+Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
+
+This skill is the Linear counterpart of `lisa:notion-to-jira` and `lisa:confluence-to-jira`. The three skills share the same phases, gates, dry-run contract, and per-ticket validation logic. Only the PRD-side fetch tools differ. When changing workflow logic, change ALL THREE skills together so the source vendors stay behaviorally identical.
+
+## What "PRD" means in Linear
+
+Linear has no native "PRD" entity. This skill treats a **Linear Project** as the PRD container:
+
+- **Project description** (markdown) is the PRD body — equivalent to a Notion page body or a Confluence page body.
+- **Project documents** (Linear's long-form markdown docs attached to projects, fetched via `list_documents({projectId})` / `get_document`) are treated as additional spec content and merged into the analysis. A multi-document Linear PRD is the analog of a multi-page Confluence PRD.
+- **Project sub-issues** (`list_issues({project})`) act as the candidate set for epics and user stories — the same role child Epic pages play in a Notion/Confluence PRD.
+- **Linear comments live on Issues, not on Projects.** This skill aggregates comments from every issue under the project to capture decisions and engineering notes. Project-level discussion that isn't reflected on an issue is invisible to this skill.
+
+## Modes
+
+This skill supports two modes, controlled by a `dry_run` flag in `$ARGUMENTS`:
+
+- **`dry_run: false`** (default — full mode): run all phases, write tickets via `lisa:jira-write-ticket`, run the preservation gate, report.
+- **`dry_run: true`** (planning + validation only — no writes): run Phases 1, 1.5, 1.6, 2, 3, 4 to plan the hierarchy and draft each ticket spec, then call `lisa:jira-validate-ticket` (with `--spec-only`) on every drafted ticket. Aggregate the per-ticket validator reports into a single dry-run report. **Skip Phase 5 (sub-task creation), Phase 5.5 (preservation gate), and Phase 6 (results report)** — none of those make sense without writes. Return the dry-run report so the caller (e.g. `lisa:linear-prd-intake`) can decide whether to proceed.
+
+Dry-run output format is identical to `lisa:notion-to-jira`'s and `lisa:confluence-to-jira`'s. Reuse the same fields, including `prd_anchor` and `prd_section`. The only difference: Linear has no inline-comment selection-anchor primitive at the project level — `prd_anchor` is the anchor a downstream caller would use to *post a comment on the related sub-issue* (typically the issue identifier, e.g. `LIN-123`, scoped to a section heading). When the failure does not map to any single sub-issue, set `prd_anchor: null` and the caller falls back to its sentinel feedback channel.
+
+```text
+## linear-to-jira dry-run: <PRD title>
+
+### Planned hierarchy
+- Epic: <summary>
+  prd_section: "<heading text from the project description / document that produced this epic>"
+  prd_anchor: "<linear issue identifier or null>"
+  - Story 1.1: <summary>
+    prd_section: "<heading or user-story line>"
+    prd_anchor: "<linear issue identifier or null>"
+    - Sub-task [<repo>]: <summary>
+      prd_section: "<heading or AC bullet>"
+      prd_anchor: "<linear issue identifier or null>"
+    - ...
+  - Story 1.2: ...
+
+### Per-ticket validation
+- <ticket-id>: PASS | FAIL — <count> failures
+  prd_section: "<heading text>"
+  prd_anchor: "<linear issue identifier or null>"
+  failures:
+    - gate: <gate-id>
+      category: <category from validator>
+      product_relevant: <true|false>
+      what: <plain-language description from validator>
+      recommendation: <1–3 candidate resolutions from validator>
+
+### Verdict: PASS | FAIL
+### Total failures: <n>
+```
+
+The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJiraIssue`. It also never modifies the source Linear project, never adds/removes labels, never edits sub-issues, and never posts comments — that is the orchestrating skill's responsibility (`lisa:linear-prd-intake`).
+
+## Hard Rule: All Writes Go Through `lisa:jira-write-ticket`
+
+**Every JIRA ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa:jira-write-ticket` skill. Never call `mcp__atlassian__createJiraIssue`, `mcp__atlassian__editJiraIssue`, `mcp__atlassian__createIssueLink`, or any other Atlassian write tool directly from this skill or from any sub-agent it spawns.**
+
+`lisa:jira-write-ticket` enforces gates this skill does not:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation
+- Explicit issue-link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Single-repo scope check on Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+Bypassing `lisa:jira-write-ticket` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. Atlassian reads in this skill are limited to the tools listed in `allowed-tools` (currently `getJiraIssueRemoteIssueLinks`) for the Phase 5.5 preservation gate. The Linear read tools listed in `allowed-tools` above are PRD-side only and never write.
+
+## Input
+
+A Linear project URL, slug, or ID. The PRD is expected to have:
+- A project with a description containing context, problems, and (optionally) a list of user stories
+- One or more sub-issues that act as candidate epics or user stories
+- Optionally one or more Linear documents attached to the project, with deeper spec content
+- Issue comments capturing engineering notes and product decisions
+
+URL parsing — Linear project URLs come in this shape:
+
+```text
+https://linear.app/<workspace>/project/<slug>-<short-id>
+https://linear.app/<workspace>/project/<slug>-<short-id>/<view>
+```
+
+Extract the trailing `<short-id>` (the alphanumeric segment after the last `-` in the slug). If only a workspace or team URL is provided (no `/project/<slug>-<id>` segment), stop and report — single-PRD mode requires a specific project. The caller wanted `lisa:linear-prd-intake` (batch mode).
+
+## Configuration
+
+This skill reads project-specific configuration from environment variables. If these are not set, ask the user for the values before proceeding.
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `JIRA_PROJECT` | JIRA project key for ticket creation | `SE` |
+| `JIRA_SERVER` | Atlassian instance URL (site host) | `mycompany.atlassian.net` |
+| `LINEAR_WORKSPACE` | Linear workspace slug (used for URL synthesis on JIRA remote links) | `acme` |
+| `E2E_TEST_PHONE` | Test user phone number for verification plans | `0000000099` |
+| `E2E_TEST_OTP` | Test user OTP code | `555555` |
+| `E2E_TEST_ORG` | Test organization name | `Arsenal` |
+| `E2E_BASE_URL` | Frontend base URL for Playwright tests | `https://dev.example.io/` |
+| `E2E_GRAPHQL_URL` | GraphQL API URL for curl verification | `https://gql.dev.example.io/graphql` |
+
+If env vars are not available, ask the user to provide them explicitly before proceeding. Do not retrieve credentials from repository files or local agent settings.
+
+## Workflow
+
+### Phase 1: Fetch & Analyze the PRD
+
+1. **Resolve the project** via `mcp__linear-server__get_project` with the slug or ID, including milestones and resources (`includeMilestones: true`, `includeResources: true`). Capture the project title, description, state, labels, lead, dates, attached documents, attached links.
+2. **Fetch attached Linear documents** via `mcp__linear-server__list_documents({projectId})` then `get_document` per result. Treat each as additional PRD content. (A Linear PRD with a single rich project description and no attached documents is the common case; multi-document PRDs are valid too.)
+3. **Identify candidate epics and user stories** from project sub-issues via `mcp__linear-server__list_issues({project: <id>})`. Capture identifier, title, description, labels, state, parent issue, and `parentId` chain so the issue hierarchy is reproducible.
+4. **Fetch full comments per sub-issue** via `mcp__linear-server__list_comments({issueId})` for every issue surfaced in step 3. Walk thread parents/children — comments are threaded via `parentId` references on the comment object.
+5. **Synthesize decisions and blockers** from the project description + every document + every issue comment:
+   - Decisions already confirmed by the team (look for agreement in comment threads)
+   - Open questions that need product/engineering input
+   - Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
+   - Cross-PRD dependencies (references to other Linear projects, documents, or shared infrastructure)
+
+### Phase 1.5: Extract Source Artifacts
+
+PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, peer Linear or Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
+
+1. **Scan the project description, every attached document body, every sub-issue description, and every fetched comment thread** for:
+   - URLs to design/prototype tools (Figma, FigJam, Figma Make, Lovable, Framer, Penpot)
+   - URLs to recording/walkthrough tools (Loom, YouTube, Vimeo, Descript)
+   - URLs to collaborative docs (Google Docs/Slides/Sheets, peer Confluence pages, Notion peer pages, peer Linear documents)
+   - URLs to code sandboxes (CodeSandbox, StackBlitz, Replit, GitHub permalinks/gists)
+   - URLs to diagramming tools (Miro, Mural, Excalidraw, Mermaid Live, draw.io, Lucid)
+   - URLs to data/observability tools (Grafana, Datadog, Sentry, Metabase, Looker)
+   - Embedded images and file attachments referenced in the project / documents
+   - Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
+
+2. **Classify each artifact and apply taxonomy rules** by invoking the `lisa:jira-source-artifacts` skill. That skill is the single source of truth for: domains (`ui-design` / `ux-flow` / `data` / `ops` / `reference`), per-tool classification rules (Figma `/proto/` vs design, Lovable as `ux-flow`, Loom, screenshots), and coverage smells. Do not restate the rules here — invoke the skill so any drift in the rules propagates uniformly.
+
+3. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable. The `source_page` lets you trace each reference back to where it appeared (project description vs a specific document title vs a specific sub-issue comment).
+
+4. **Surface coverage smells** as defined in `lisa:jira-source-artifacts` §5. Record any detected smells on the epic.
+
+### Phase 1.6: Source Precedence & Conflict Resolution
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa:jira-source-artifacts` §3 and §4. Apply them during ticket synthesis: every conflict between artifacts must be recorded under `## Open Questions` on the affected ticket, never silently reconciled.
+
+The existing-component reuse expectation is defined in `lisa:jira-source-artifacts` §7. Encode it on every UI-touching story.
+
+### Phase 2: Codebase + Live Product Research
+
+Identical to `lisa:notion-to-jira` Phase 2 and `lisa:confluence-to-jira` Phase 2. Two complementary inputs ground PRD analysis: the **code** (what's there to reuse / extend) and the **live product** (what users see today). Skipping either produces tickets that misjudge the change.
+
+**2a. Codebase research.** If the session doesn't already have codebase context, explore the repos to understand what exists. Use Explore agents for repos not yet examined.
+
+**2b. Live product walkthrough.** If the PRD touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill against `E2E_BASE_URL` using the test user from config.
+
+Skip 2b only when the work is purely backend with no user-visible surface, or affects a screen that does not yet exist in dev/prod.
+
+Walkthrough findings are surfaced back to product via the orchestrating intake skill (`lisa:linear-prd-intake`), which posts them on the project's sentinel feedback issue. This skill itself does NOT post to Linear — it only reads. The walkthrough section is also inherited onto the resulting epic / stories under a `## Current Product` subsection in the JIRA description.
+
+### Phase 3: Create Epics
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:jira-write-ticket` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `lisa:jira-validate-ticket --spec-only`. Record the drafted spec (including a placeholder epic key like `DRY-RUN-EPIC-1`) for Phase 4 to use as parent references. In `dry_run: false` mode (default), proceed as described below.
+
+For each epic identified in Phase 1, **invoke the `lisa:jira-write-ticket` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
+
+- `project_key`: from `JIRA_PROJECT` config
+- `issue_type`: `Epic`
+- `summary`: epic title from the PRD
+- `description_body`: a draft of the 3-audience description containing:
+  - **Context / Business Value**: epic summary from the PRD, originating Linear project URL, business outcome
+  - **Technical Approach**: cross-cutting integration points and constraints surfaced in Phase 2 codebase research
+  - List of user stories the epic contains
+  - Key decisions from comments (with attribution)
+  - Blockers and open questions
+  - Dependencies on other epics or PRDs
+  - A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
+- `artifacts`: the full Phase 1.5 artifact list — every artifact, regardless of domain. The epic is the canonical hub. No filtering at the epic level.
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
+
+Capture the returned epic key — Phase 4 needs it as the parent for stories.
+
+### Phase 4: Create Stories
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:jira-write-ticket` in this phase. Instead, draft each story spec and validate it with `lisa:jira-validate-ticket --spec-only`. Use placeholder keys (e.g. `DRY-RUN-STORY-1.1`) for any downstream references. In `dry_run: false` mode (default), proceed as described below.
+
+For each Epic, plan two kinds of stories:
+- **One "X.0 Setup" story** for data model and infrastructure prerequisites
+- **One story per user story** from the PRD (numbered to match the PRD's structure or the source Linear sub-issues)
+
+**Story naming convention**: Prefix the summary with a short code derived from the PRD title (e.g., `[CU-1.1]` for "Contract Upload").
+
+For each story, **invoke `lisa:jira-write-ticket`** with:
+
+- `project_key`: from `JIRA_PROJECT` config
+- `issue_type`: `Story`
+- `epic_parent`: the Epic key captured in Phase 3 (mandatory)
+- `summary`: prefixed per the naming convention above
+- `description_body`: 3-audience description as in `lisa:notion-to-jira` Phase 4
+- `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below
+
+| Story type | Inherits domains |
+|------------|------------------|
+| Frontend / UI | `ui-design`, `ux-flow`, `reference` |
+| Backend / API / data model | `data`, `reference` |
+| Infrastructure | `ops`, `reference` |
+| Mixed / setup ("X.0") | All domains |
+
+Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
+
+### Phase 5: Create Sub-tasks
+
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:jira-write-ticket` for each sub-task — no agent may call `createJiraIssue` directly.**
+
+Each sub-task MUST:
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`
+2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
+
+Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task.
+
+### Phase 5.5: Artifact Preservation Gate (mandatory)
+
+Run the preservation gate defined in `lisa:jira-source-artifacts` §8 against the artifacts extracted in Phase 1.5 and the tickets just created. Do NOT restate or modify the gate logic here — invoke the rules from `lisa:jira-source-artifacts`.
+
+To run the gate, this skill must:
+
+1. Pull the remote links of every epic and story created in this run via `mcp__atlassian__getJiraIssueRemoteIssueLinks`.
+2. Apply the §8 preservation matrix and verdict rules.
+3. If the gate fails: list each dropped/misrouted artifact and either re-attach via `lisa:jira-write-ticket` (UPDATE mode) or stop and ask the human.
+4. If the gate passes: print the matrix compactly and proceed to Phase 6.
+
+This gate is not optional.
+
+### Phase 6: Report Results
+
+After all tickets are created, present a summary table to the user:
+- All Epics with keys and URLs
+- All Stories grouped by Epic
+- All Sub-tasks grouped by Story with repo tags
+- Repo distribution
+- **Artifact Preservation Matrix**
+- Blockers list with recommendations and alternatives
+- Cross-PRD dependencies
+
+## Handling Ambiguities and Blockers
+
+When you encounter something the PRD + comments + codebase can't resolve:
+
+1. **Don't guess** — mark the ticket with a BLOCKER section
+2. **Include your recommendation** with rationale
+3. **List 2-3 alternatives** so the user/product can choose
+4. **State what's needed to unblock**
+
+## Agent Prompt Template for Sub-task Creation
+
+When delegating to agents, provide this context. **The "MUST invoke jira-write-ticket" instruction is load-bearing — do not edit it out when adapting this template.**
+
+```text
+Create JIRA sub-tasks in the [PROJECT] project at [CLOUD_ID].
+
+CRITICAL: For each sub-task, invoke the `lisa:jira-write-ticket` skill via the Skill tool.
+Do NOT call `mcp__atlassian__createJiraIssue` directly. The `lisa:jira-write-ticket` skill
+enforces required quality gates (Gherkin acceptance criteria, 3-audience description,
+single-repo scope, sign-in/environment fields, post-create verification). Bypassing it
+produces broken tickets that downstream skills (triage, journey, evidence) cannot use.
+
+For each sub-task, invoke `lisa:jira-write-ticket` with:
+- issue_type: "Sub-task"
+- parent: the parent story key
+- project_key: [PROJECT]
+- summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria)
+- gherkin_acceptance_criteria: derived from the story's functional requirements
+- sign_in_account: [test user credentials from config — name + role + how to obtain]
+- target_environment: "dev"
+- empirical_verification_plan: real user-like verification (curl + auth token,
+  Playwright browser flow, CLI check after deploy) using the test credentials.
+  NOT unit tests, linting, or typechecking.
+
+Each sub-task must:
+1. Be scoped to ONE repo only — repo named in brackets in the summary
+2. Include the Empirical Verification Plan in the description
+3. Be created via `lisa:jira-write-ticket`, not via direct MCP calls
+
+If `lisa:jira-write-ticket` rejects a sub-task, fix the input and re-invoke. Do NOT fall back
+to a direct `createJiraIssue` call to bypass the gate.
+
+Test user info: [credentials from config]
+
+[Then list all sub-tasks grouped by parent story with details]
+```
+
+## Cross-PRD Shared Infrastructure
+
+Track tickets that are shared across PRDs to avoid duplication. When a sub-task overlaps with an existing ticket, reference it instead of creating a duplicate. Search JIRA for existing tickets in the project before creating new ones for shared infrastructure.
+
+## Linear-specific notes
+
+- **Project description format**: Linear project descriptions are markdown. Treat headings (`#`, `##`, `###`) as section markers for `prd_section`.
+- **Document parents**: Linear documents are attached to either a Project or an Issue (exactly one). For PRD intake, only documents attached to the project being processed are in scope. Documents attached to a child Issue are picked up via that issue's content surface.
+- **Comment threading**: Linear comments are threaded via a `parentId` field on each comment. When fetching comments via `list_comments`, capture the full reply tree — replies often hold the actual decision while the root comment was the question.
+- **No project-level comments via MCP**: clarifying-question comments cannot land directly on the project itself. The orchestrating skill (`lisa:linear-prd-intake`) handles this by maintaining a sentinel feedback issue under the project. This skill does not write to Linear at all — it only reads.
+- **Issue identifiers** (`LIN-123`, `ENG-456`, etc.) are the closest analog to a Confluence inline-comment anchor. When dry-run output sets `prd_anchor` to an issue identifier, the caller knows it can post a clarifying-question comment on that specific issue if it wants block-level anchoring.

package/plugins/src/base/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: "Decompose a single PRD or specification into ordered work items in the configured tracker. Vendor-agnostic — the source can be a Notion PRD URL, a Confluence PRD URL, an existing JIRA epic key, a markdown file, or a free-form description; the destination tracker is whatever the project is configured to use (JIRA today; Linear/GitHub Issues are pluggable). Single-PRD mode only — for batch scanning of all Ready PRDs in a queue, use the lisa:intake skill."
+description: "Decompose a single PRD or specification into ordered work items in the configured tracker. Vendor-agnostic — the source can be a Notion PRD URL, a Confluence PRD URL, a Linear project URL, an existing JIRA epic key, a markdown file, or a free-form description; the destination tracker is whatever the project is configured to use (JIRA today; GitHub Issues is pluggable). Single-PRD mode only — for batch scanning of all Ready PRDs in a queue, use the lisa:intake skill."
 allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
 ---
 
@@ -24,8 +24,10 @@ Detect the input type from `$ARGUMENTS` and route to the appropriate source skil
 | A Notion **database** URL or database ID | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a database. |
 | A Confluence **page** URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` (single PRD) | `lisa:confluence-to-jira` (with the PRD URL; same full pipeline as the Notion path) |
 | A Confluence **space** URL (`/wiki/spaces/<KEY>` with no `/pages/...`) | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a space. |
+| A Linear **project** URL (`https://linear.app/<workspace>/project/<slug>-<id>`) | `lisa:linear-to-jira` (with the project URL; same full pipeline as the Notion / Confluence paths). The Linear project's description, attached documents, and sub-issues form the PRD body. |
+| A Linear **workspace** URL (`https://linear.app/<workspace>` with no `/project/...`) or **team** URL | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a workspace or team. |
 | A JIRA ticket ID/URL of an Epic (existing epic *is* the spec) | `lisa:jira-agent` (read epic, decompose into stories/sub-tasks) |
-| A Linear / GitHub Issues URL or key | Not yet implemented. Stop and tell the user the adapter doesn't exist yet — the architecture supports it, but no `linear-prd-source` / `github-prd-source` skill has been built. Don't fall back. |
+| A GitHub Issues URL or key | Not yet implemented. Stop and tell the user the adapter doesn't exist yet — the architecture supports it, but no `github-prd-source` skill has been built. Don't fall back. |
 | A file path (`@plan.md`, `./spec.md`) | Read the file as the spec; run the Plan flow's core decomposition with the file content as input. |
 | A plain-text description | Use the description as the spec; run the Plan flow's core decomposition. |
 
@@ -37,4 +39,4 @@ Execute the **Plan** flow as defined in the `intent-routing` rule (loaded via th
 
 ## Output
 
-Work items in the configured tracker (JIRA today; Linear/GitHub Issues when adapters exist) with acceptance criteria, dependencies, and recommended skills/agents per item. Ordered by dependency. If the specification cannot be decomposed without further clarification, stop and report what is missing.
+Work items in the configured tracker (JIRA today; GitHub Issues when the adapter exists) with acceptance criteria, dependencies, and recommended skills/agents per item. Ordered by dependency. If the specification cannot be decomposed without further clarification, stop and report what is missing.