@codyswann/lisa 2.10.0 → 2.11.0

package/plugins/lisa/skills/linear-verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: linear-verify
+description: "Verifies a Linear work item meets organizational standards by fetching the live item and running it through lisa:linear-validate-issue. Catches anything dropped or reformatted on write — same gates as the pre-write check, but applied to what Linear actually stored. Read-only."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__get_project", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+---
+
+# Verify Linear Work Item: $ARGUMENTS
+
+Fetch the live Linear work item and run it through `lisa:linear-validate-issue`. This catches any field that was dropped or reformatted between the pre-write spec and what Linear stored.
+
+This skill is the destination of the `lisa:tracker-verify` shim when `tracker = "linear"`. Read-only — never writes.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Input
+
+`$ARGUMENTS` is a Linear identifier:
+- An Issue identifier (e.g. `ENG-123`)
+- A Project URL or slug (e.g. `https://linear.app/<workspace>/project/<slug>-<id>`)
+
+If `$ARGUMENTS` is not parseable, stop and report.
+
+## Phase 1 — Resolve Context
+
+1. Read `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
+3. Determine entity type from the identifier shape:
+   - `<TEAM>-<n>` → Issue
+   - URL containing `/project/<slug>-<id>` → Project
+
+## Phase 2 — Fetch Live State
+
+Call `mcp__linear-server__get_issue` (for Issues) or `mcp__linear-server__get_project` (for Projects). Capture every field, label, relation, comment, milestone, and project membership.
+
+## Phase 3 — Delegate to Validator
+
+Pass the fetched item to `lisa:linear-validate-issue` (in identifier mode — let it derive the spec from the live state). The validator runs both Specification AND Feasibility gates against what Linear actually stored.
+
+## Phase 4 — Report
+
+Return the validator's report verbatim — same structured format as `lisa:linear-validate-issue`. Callers (especially `lisa:linear-write-issue` Phase 7) parse the verdict to decide whether to declare success.
+
+If the verdict is `FAIL`, the caller should fix the item and re-run verify. Never declare success on a `FAIL` verdict.
+
+## Rules
+
+- Never write to Linear. Read-only.
+- Never short-circuit the validator. Always run the full gate set.
+- If `get_issue` / `get_project` returns an access error, surface it and exit — don't pretend the item is fine.

package/plugins/lisa/skills/linear-write-issue/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: linear-write-issue
+description: "Creates or updates a Linear work item — Project (Epic), Issue (Story), or sub-Issue (Sub-task) — following organizational best practices. Polymorphic: dispatches internally on issue_type to save_project (Epic) or save_issue (Story / Sub-task). Enforces description quality (three audiences), Gherkin acceptance criteria, project-as-parent for Stories, parentId for Sub-tasks, explicit relationship discovery (blocks / is blocked by / relates to / duplicates), labels, components-as-labels, project milestones for fix versions, native priority and estimate fields, and Validation Journey. Rejects thin items — use this skill any time a Linear work item is created or significantly edited."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_team", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment"]
+---
+
+# Write Linear Work Item: $ARGUMENTS
+
+Create or update a Linear work item — Project (for Epics), Issue (for Stories), or sub-Issue (for Sub-tasks) — with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin items are rejected.
+
+Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
+
+## Configuration
+
+This skill reads configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key). Required keys:
+
+- `linear.workspace` — Linear workspace slug
+- `linear.teamKey` — Linear team key (e.g. `ENG`); the team owns the destination items
+
+If either is missing, stop and report — never invent values.
+
+## Polymorphic dispatch
+
+Linear's data model maps Epic / Story / Sub-task to **different entity types**. This skill dispatches on `issue_type`:
+
+| `issue_type` | Linear entity | MCP write tool | Parent field |
+|--------------|---------------|----------------|--------------|
+| `Epic` | **Project** | `mcp__linear-server__save_project` | (none — Projects are top-level within a team) |
+| `Story` / `Task` / `Improvement` | **Issue** | `mcp__linear-server__save_issue` | `projectId` (the Epic Project) |
+| `Sub-task` | **sub-Issue** | `mcp__linear-server__save_issue` | `parentId` (the Story Issue) |
+| `Bug` | **Issue** | `mcp__linear-server__save_issue` | `projectId` if part of an Epic; else top-level |
+| `Spike` | **Issue** | `mcp__linear-server__save_issue` | `projectId` if part of an Epic; else top-level |
+
+Status workflow uses **labels** (`status:ready`, `status:in-progress`, `status:on-dev`, `status:done`) for portability across teams — Linear's per-team workflow state names vary, but labels are workspace-scoped and stable. Native Linear `state` is set to the team's default `Todo` state on create.
+
+## Phase 1 — Resolve Intent
+
+Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE:
+
+- **CREATE**: no existing identifier provided.
+- **UPDATE**: identifier provided (`<TEAM>-<n>` for Issue, project slug + short-id for Project) — call `/linear-read-issue <ref>` first to load the full current state. Never overwrite without reading.
+
+Resolve the team ID for `linear.teamKey` via `mcp__linear-server__list_teams({query: <teamKey>})`. Cache it.
+
+## Phase 2 — Gather Required Inputs
+
+Required fields (stop and ask if missing — never invent values):
+
+| Field | Required For | Notes |
+|-------|--------------|-------|
+| `team_key` | CREATE | From `linear.teamKey` config; required for both Project and Issue creation |
+| `issue_type` | CREATE | One of: Epic, Story, Task, Bug, Spike, Sub-task, Improvement |
+| Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
+| Description | CREATE, UPDATE | Multi-section markdown — see Phase 3 |
+| Project parent (for Story / Task / Bug / Spike / Improvement when part of an Epic) | non-Epic, non-Sub-task in Epic context | Linear Project ID — the Epic |
+| Sub-task parent | Sub-task | Linear Issue ID — the Story |
+| Priority | CREATE | Native Linear priority: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 |
+| Validation Journey | Runtime-behavior changes | Delegate to `/linear-add-journey` |
+| Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only items. |
+| Sign-in account / credentials | Items that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description. Omit when sign-in is not required. |
+| Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
+
+Optional but recommended: assignee, estimate (story points), labels, project milestone (fix-version equivalent), cycle.
+
+## Phase 3 — Description Quality
+
+Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, use `##` instead). The description MUST address three audiences. Reject and rewrite if any are missing.
+
+```markdown
+## Context / Business Value
+[Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
+ Link to the originating Slack thread, Notion doc, incident, or customer report.]
+
+## Technical Approach
+[Developer-facing. Integration points, impacted modules, data model implications,
+ relevant tradeoffs. Not a full design doc — a pointer for someone picking it up.]
+
+## Acceptance Criteria
+1. Given <precondition>
+   When <action>
+   Then <observable outcome>
+2. Given <precondition>
+   When <action>
+   Then <observable outcome>
+
+## Out of Scope
+[Explicit list of what this item does NOT cover. Forces scope discipline.]
+
+## Target Backend Environment
+[Required when the item changes runtime behavior. One of: dev / staging / prod.
+ Skip section entirely for doc-only, config-only, or type-only items.]
+
+## Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role to sign in as, where to get the credentials
+ (1Password item name, env var, seeded fixture), and any MFA/SSO notes.
+ Omit the section entirely when sign-in is not required.]
+
+## Repository
+[Required for Bug / Task / Sub-task. Name the single repo this item covers.
+ If the work spans repos, this issue type is wrong — split into per-repo
+ Tasks/Sub-tasks under a parent Story or Epic.]
+
+## Validation Journey
+[Delegate to /linear-add-journey if the item changes runtime behavior.
+ Skip only for doc-only, config-only, or type-only items.]
+```
+
+Rules:
+- Every acceptance criterion uses Given/When/Then. No vague "should work" language.
+- Every criterion is independently verifiable (UI, API, data, or performance check).
+- If the item is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
+- If the item is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings).
+- If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials.
+
+## Phase 4 — Relationship Discovery (Mandatory)
+
+Before creating or updating, find candidate relationships. Do NOT skip — this is the step agents most often omit.
+
+### 4a. Project Parent (Epic-equivalent)
+
+If the item is **not an Epic** and **not a top-level Bug/Spike**, it MUST have a parent context:
+
+- **Story / Task / Improvement** → must have a `projectId` (the Epic Project) set.
+- **Sub-task** → must have a `parentId` (the Story Issue) set.
+
+If the parent is explicitly provided, use it. Otherwise:
+
+1. Search active Projects in the team:
+   ```text
+   mcp__linear-server__list_projects({team: <teamKey>, state: ["backlog", "planned", "started"]})
+   ```
+   Match on keywords from the summary and description.
+2. If no matching Project exists, stop and ask the human to create or pick one. Do NOT orphan the item.
+
+### 4b. Related Items
+
+Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the item.
+
+**Search 1: local git history** (catches PRs / commits that touched the same area but were never linked):
+
+```bash
+git log --all --oneline --grep="<keyword>"
+git log --all --oneline -- <path-or-glob>
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling item worth linking.
+
+**Search 2: Linear MCP** (catches open and recently-closed items):
+
+```text
+# Open items in the same Project
+mcp__linear-server__list_issues({project: <projectId>, state_type: ["unstarted", "started"]})
+
+# Open items with overlapping keywords (workspace-wide)
+mcp__linear-server__list_issues({query: "<keyword>", state_type: ["unstarted", "started"]})
+
+# Items with shared labels
+mcp__linear-server__list_issues({label: "<label>", updatedAt: ">-30d"})
+
+# Recently closed items in the same Project
+mcp__linear-server__list_issues({project: <projectId>, state_type: ["completed", "canceled"], updatedAt: ">-30d"})
+```
+
+**Record the outcome.** Add a `## Relationship Search` subsection (or a comment if updating) listing the queries you ran and what they returned. If the searches yielded nothing, write that explicitly — "Searched git history for `<keywords>` and Linear for project=`X`, label=`Y`; no related work found." An item with zero relations and no documented search is rejected.
+
+For each candidate, classify the relationship:
+
+| Relation Type | When to Use |
+|---------------|-------------|
+| `blocks` | This item must ship before the linked item can proceed |
+| `blocked_by` | The linked item must ship before this one can proceed |
+| `relates_to` | Shared context, no ordering constraint |
+| `duplicates` | This item already exists — close one as duplicate |
+
+Linear native relations are set on the Issue via `save_issue`'s `relations` field (or via a paired `save_issue_relation` call if available in the MCP). For Project-level (Epic) relationships, capture them in the description under `## Related Projects` since Linear doesn't model relations between Projects natively.
+
+### 4c. Remote Links
+
+Identify and attach (Linear stores attachments / links on the Issue or in description body):
+
+- GitHub PRs, branches, or commits related to this work
+- Confluence pages (design docs, RFCs, runbooks)
+- Dashboards (Grafana, Datadog, Sentry issue)
+- Incident items (PagerDuty, Statuspage)
+- **Source artifacts from the originating PRD / parent Project**: classify and inherit per the rules in `lisa:tracker-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). Enumerate the parent Project's links and inherit the ones whose domain matches this item's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`). Never assume a developer will walk up to the Project to find design context — attach it here.
+
+If the item was generated from a PRD (by `lisa:notion-to-tracker` or similar) and the parent Project has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
+
+### 4d. Source Precedence (must appear on the item)
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-source-artifacts` §3 and §4. When an item carries both design artifacts and a description, record the precedence explicitly in the description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts. Cross-axis conflicts go under `## Open Questions` as BLOCKER items.
+
+For UI-touching items, include the existing-component reuse expectation per `lisa:tracker-source-artifacts` §7.
+
+### 4e. Live Product Walkthrough Findings (UI-touching items)
+
+If the item modifies an existing user-facing surface, a `lisa:product-walkthrough` should already have been run upstream. Inherit its findings under a `## Current Product` subsection in the description so the implementer sees what's shipped today before changing it. If the upstream skill skipped the walkthrough but this item clearly modifies an existing surface, invoke `lisa:product-walkthrough` here before proceeding.
+
+## Phase 5 — Set Metadata
+
+Before create/update, verify each field is populated where applicable:
+
+- **Labels**: include `status:ready` for new items; component labels (`component:<name>`); status / priority labels are NOT redundant with native fields — labels exist for portability and downstream queries.
+- **Native priority field**: 0–4 per Linear's scale; explicit, not "unset".
+- **Native estimate**: per Linear's team-configured estimate scale (often 0–8 Fibonacci); skip for Epic / Spike.
+- **ProjectMilestone**: when the team uses dated milestones, set the milestone on the Project (Epic) or on the Issue (when an Issue belongs to a milestone).
+- **Cycle**: only if actively in a cycle.
+- **Assignee**: leave unset if unknown rather than auto-assigning.
+
+For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
+
+## Phase 5.5 — Validate (Pre-write Gate)
+
+Before any write, invoke `lisa:linear-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa:linear-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
+
+The validator is the **single source of truth** for what makes a valid Linear work item. The same gates are used by `lisa:linear-to-tracker` dry-run, by `lisa:linear-verify` post-write, and here. Do not re-implement gate logic in this skill.
+
+If the validator reports `FAIL`:
+- Surface the failure list and the per-gate remediation to the user.
+- Do NOT proceed to Phase 6. Fix the spec (or stop and ask the human) and re-run validation.
+- Never call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` while the validator's verdict is FAIL.
+
+If the validator reports `PASS`, continue to Phase 6.
+
+## Phase 6 — Create or Update
+
+### CREATE — Epic (Project)
+
+1. Resolve any required Project labels (`prd-ticketed`, etc.) via `mcp__linear-server__list_project_labels` (create via `create_project_label` if missing).
+2. Call `mcp__linear-server__save_project` with: `name` (summary), `description` (markdown), `teamIds: [<teamId>]`, `labelIds`, `priority` (Linear Project priority is also 0–4), `state` (default `backlog`), milestones if dated.
+3. Capture the returned Project ID and slug — Phase 4 children need these.
+4. If the Project is the parent for downstream Stories, record the ID for `lisa:linear-to-tracker` Phase 4 to use.
+
+### CREATE — Story / Task / Bug / Spike / Improvement (Issue with projectId)
+
+1. Resolve any required Issue labels (`status:ready`, `component:<name>`, `prd-intake-feedback` only if this is a sentinel issue, etc.) via `mcp__linear-server__list_issue_labels` (create via `create_issue_label` if missing).
+2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (summary), `description` (markdown), `projectId` (the Epic Project), `priority` (0–4), `estimate`, `labelIds`, `assignee` if known.
+3. Capture the returned identifier (e.g. `ENG-123`) — Phase 4 sub-tasks need it as `parentId`.
+4. Add relationships from Phase 4b via `save_issue` (relations field) or paired relation calls.
+5. If the item changes runtime behavior, invoke `lisa:linear-add-journey` to append the Validation Journey section.
+
+### CREATE — Sub-task (Issue with parentId)
+
+1. Resolve labels as above.
+2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (`[<repo>] <summary>` prefix is mandatory), `description` (markdown), `parentId` (the Story Issue ID), `projectId` (inherit from parent), `priority`, `estimate`, `labelIds`.
+3. Capture identifier.
+4. Add relationships via Phase 4b.
+
+### UPDATE
+
+1. Call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` with **only the fields being changed**. Do NOT resend fields that weren't in the change set — Linear treats the call as a full overwrite of the listed fields.
+2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first.
+
+## Phase 7 — Verify
+
+Call the `lisa:linear-verify` skill on the resulting item. `lisa:linear-verify` fetches the live item and runs `lisa:linear-validate-issue` against it — same gates as Phase 5.5, but applied to what Linear actually stored. If it reports failures, fix them before returning. Do not report success on an item that fails verify.
+
+## Phase 8 — Announce
+
+Post a creation comment via `mcp__linear-server__save_comment` (on the Issue, or on a sentinel issue under the Project for Epic-level announcements) with:
+
+- `[<repo>]` prefix if the item is repo-scoped
+- Who the item is assigned to (if known)
+- The relationships that were set (`blocks`, `blocked_by`, `relates_to`) with Linear identifiers
+- Any remote PRs attached
+
+Skip this step only on UPDATE when no material change was made.
+
+## Rules
+
+- Never create a non-Epic, non-top-level item without a parent context (Project for Stories, parentId for Sub-tasks).
+- Never skip relationship discovery — both the git history search AND the Linear MCP search must run, and their outcomes must be recorded on the item. "None found" is acceptable only when it's documented.
+- Never create a Bug, Task, or Sub-task that spans multiple repos. Split it before creating.
+- Never include a runtime-behavior item without a target backend environment, and never include an authenticated-surface item without sign-in credentials in the description.
+- Never invent custom field values. If the team requires a field you don't have, stop and ask.
+- Never overwrite a description without reading the current version first.
+- All Linear writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:linear-create`) should delegate here rather than calling the MCP write tools directly.
+- The gate logic (what makes a valid item) lives in `lisa:linear-validate-issue`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:linear-verify` post-write). When a gate needs to change, change it in `lisa:linear-validate-issue` — every caller picks it up automatically.
+- This skill is the destination of the `lisa:tracker-write` shim when `tracker = "linear"`. Vendor-neutral callers (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST go through `lisa:tracker-write`, not call this skill directly.

package/plugins/lisa/skills/notion-prd-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion-prd-intake
-description: "Scans a Notion PRD database for pages with Status=Ready and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and Status=Ticketed; PRDs that fail get clarifying-question comments and Status=Blocked. The skill is the runtime for the Ready → In Review → Blocked|Ticketed lifecycle. Composes existing skills (notion-to-tracker, tracker-validate, jira-source-artifacts, product-walkthrough); does not reimplement their logic."
+description: "Scans a Notion PRD database for pages with Status=Ready and runs each one through the dry-run validation pipeline. PRDs that pass every gate get tickets written and Status=Ticketed; PRDs that fail get clarifying-question comments and Status=Blocked. The skill is the runtime for the Ready → In Review → Blocked|Ticketed lifecycle. Composes existing skills (notion-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough); does not reimplement their logic."
 allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-search", "mcp__claude_ai_Notion__notion-update-page", "mcp__claude_ai_Notion__notion-create-comment", "mcp__atlassian__getAccessibleAtlassianResources"]
 ---
 
@@ -27,7 +27,7 @@ Specifically forbidden:
 
 The only legitimate reasons to stop early:
 
-- Missing database URL or required configuration (`JIRA_PROJECT`, `JIRA_SERVER`, `E2E_BASE_URL`, etc.). Surface the missing value and exit.
+- Missing database URL or required configuration (`atlassian.cloudId`, `jira.project` or destination-tracker equivalents in `.lisa.config.json`, `E2E_BASE_URL`, etc.). Surface the missing value and exit.
 - Database misconfigured (Status property missing expected values, data source unreachable). Surface and exit.
 - Empty `Ready` set. Exit cleanly with `"No PRDs with Status=Ready. Nothing to do."`
 
@@ -78,7 +78,7 @@ Invoke the `lisa:notion-to-tracker` skill with `dry_run: true` and the PRD's URL
 - 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:tracker-validate`, which `lisa:notion-to-tracker` calls per ticket.
+This call also indirectly invokes `lisa:tracker-source-artifacts` (artifact extraction + classification) and `lisa:product-walkthrough` (when the PRD touches existing user-facing surfaces). All gate logic lives in `lisa:tracker-validate`, which `lisa:notion-to-tracker` calls per ticket.
 
 #### 3c. Branch on the verdict
 
@@ -208,12 +208,18 @@ Print to the agent's output. Do not write this summary to Notion or JIRA — it'
 
 ## Configuration
 
-This skill reads project configuration from environment variables (or `$ARGUMENTS` overrides). If any required value is missing, ask the user before proceeding — never invent values.
+This skill reads project configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key) and operational E2E test config from environment variables. See the `config-resolution` rule for the full schema. Destination tracker config (jira / github / linear) is consumed by `lisa:tracker-write` internally — this skill does NOT read it.
+
+### From `.lisa.config.json`
+
+| Field | Purpose |
+|-------|---------|
+| `notion.prdDatabaseId` | Notion database hosting PRDs (when `$ARGUMENTS` is the literal token `notion`) |
+
+### From environment variables
 
 | Variable | Purpose |
 |----------|---------|
-| `JIRA_PROJECT` | JIRA project key for ticket creation (passed to `lisa:notion-to-tracker`) |
-| `JIRA_SERVER` | Atlassian instance host |
 | `E2E_BASE_URL` | Frontend URL for `lisa:product-walkthrough` |
 | `E2E_TEST_PHONE` / `E2E_TEST_OTP` / `E2E_TEST_ORG` | Test user creds for walkthrough + verification plans |
 | `E2E_GRAPHQL_URL` | API URL for verification plans |

package/plugins/lisa/skills/notion-to-tracker/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: notion-to-tracker
 description: >
-  Break down a Notion PRD into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA or GitHub Issues per .lisa.config.json). Use this skill whenever the user
+  Break down a Notion PRD into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json). Use this skill whenever the user
   shares a Notion PRD URL and wants it converted into tracker tickets, or asks to "break down a PRD",
   "create tickets from a PRD", "turn this PRD into tickets", or similar. Also trigger when the user
   mentions creating epics/stories/tasks from a Notion document. This skill handles the full pipeline:
@@ -11,7 +11,7 @@ description: >
 
 # Notion PRD to Tracker Breakdown
 
-Convert a Notion PRD into a structured ticket hierarchy in the configured destination tracker (JIRA or GitHub Issues per .lisa.config.json): Epics > Stories > Sub-tasks.
+Convert a Notion PRD into a structured ticket hierarchy in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json): Epics > Stories > Sub-tasks.
 Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
 
 ## Modes
@@ -84,21 +84,27 @@ A Notion PRD URL. The PRD is expected to have:
 
 ## Configuration
 
-This skill reads project-specific configuration from environment variables. If these are not set,
-ask the user for the values before proceeding.
+This skill reads project configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key) and operational E2E test config from environment variables. See the `config-resolution` rule for the full schema.
+
+### From `.lisa.config.json`
+
+This skill is a **PRD source** (Notion); destination tracker resolution is handled by `lisa:tracker-write` and `lisa:tracker-validate` internally — this skill does NOT read `tracker` directly. The relevant config for the source side:
+
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `notion.prdDatabaseId` | Notion database hosting PRDs | invoked without an explicit Notion page URL (batch / arg-less mode) |
+
+### From environment variables (E2E test config — operational, not tracker)
 
 | Variable | Purpose | Example |
 |----------|---------|---------|
-| `JIRA_PROJECT` | JIRA project key for ticket creation | `SE` |
-| `JIRA_SERVER` | Atlassian instance URL (site host) | `mycompany.atlassian.net` |
 | `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.
+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
 
@@ -128,17 +134,17 @@ PRDs typically reference external design, UX, and data artifacts (Figma files, L
    - Embedded images and file attachments on the page itself
    - 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.
+2. **Classify each artifact and apply taxonomy rules** by invoking the `lisa:tracker-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 ("Figma URL contains `/proto/` → ux-flow"). The `source_page` lets you trace each reference back to where it appeared in the PRD.
 
-4. **Surface coverage smells** as defined in `lisa:jira-source-artifacts` §5 (zero artifacts, prototype-without-mock, mock-without-prototype, Lovable-without-business-rules). Record any detected smells on the epic.
+4. **Surface coverage smells** as defined in `lisa:tracker-source-artifacts` §5 (zero artifacts, prototype-without-mock, mock-without-prototype, Lovable-without-business-rules). 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.
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-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 (mocks define visual intent, not implementation shortcut) is defined in `lisa:jira-source-artifacts` §7. Encode it on every UI-touching story.
+The existing-component reuse expectation (mocks define visual intent, not implementation shortcut) is defined in `lisa:tracker-source-artifacts` §7. Encode it on every UI-touching story.
 
 ### Phase 2: Codebase + Live Product Research
 
@@ -164,7 +170,7 @@ Walkthrough findings are attached to the originating Notion PRD as a comment ("C
 
 For each PRD epic, **invoke the `lisa:tracker-write` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
 
-- `project_key`: from `JIRA_PROJECT` config
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
 - `issue_type`: `Epic`
 - `summary`: epic title from the PRD
 - `description_body`: a draft of the 3-audience description containing:
@@ -195,7 +201,7 @@ For each Epic, plan two kinds of stories:
 
 For each story, **invoke `lisa:tracker-write`** with:
 
-- `project_key`: from `JIRA_PROJECT` config
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
 - `issue_type`: `Story`
 - `epic_parent`: the Epic key captured in Phase 3 (mandatory — `lisa:tracker-write` rejects non-bug, non-epic tickets without an epic parent)
 - `summary`: prefixed per the naming convention above
@@ -242,7 +248,7 @@ Sub-tasks inherit their parent story's artifacts by reference (the parent link).
 
 ### 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` so any rule change propagates uniformly.
+Run the preservation gate defined in `lisa:tracker-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:tracker-source-artifacts` so any rule change propagates uniformly.
 
 To run the gate, this skill must:
 

package/plugins/lisa/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, a Linear project URL, a GitHub Issue 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 via `.lisa.config.json` `tracker` (JIRA or GitHub Issues). 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, a GitHub Issue 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 via `.lisa.config.json` `tracker` (JIRA, GitHub Issues, or Linear). 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"]
 ---
 
@@ -32,6 +32,7 @@ Detect the input type from `$ARGUMENTS` and route to the appropriate source skil
 | A Linear **project** URL (`https://linear.app/<workspace>/project/<slug>-<id>`) | `lisa:linear-to-tracker` (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 Project URL of a Project that *is* the spec, when destination tracker = `linear` | `lisa:linear-agent` (read project, decompose into Issues / sub-Issues). Symmetric counterpart to the JIRA-Epic and GitHub-Epic branches. |
 | A GitHub **issue** URL (`https://github.com/<org>/<repo>/issues/<number>`) or `<org>/<repo>#<number>` token (single PRD) | `lisa:github-to-tracker` (with the issue ref; runs the full pipeline: extract artifacts → walk live product → validate → write tickets → coverage audit). The destination tracker is read from `.lisa.config.json` `tracker`. |
 | A GitHub **repository** URL or `<org>/<repo>` token (no issue number) | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a GitHub repo. |
 | A GitHub Issue URL of a build-side ticket (`type:Epic` / `type:Story` / etc., not `prd-*`-labelled) when `tracker = github` | `lisa:github-agent` (read issue, decompose into Sub-tasks). Symmetric counterpart to the JIRA-Epic branch above. |
@@ -46,4 +47,4 @@ Execute the **Plan** flow as defined in the `intent-routing` rule (loaded via th
 
 ## Output
 
-Work items in the configured tracker (JIRA or GitHub Issues, per `.lisa.config.json` `tracker`) 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, GitHub Issues, or Linear, per `.lisa.config.json` `tracker`) 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.

package/plugins/lisa/skills/prd-ticket-coverage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prd-ticket-coverage
-description: "Verifies that every requirement in a PRD (Notion, Confluence, Linear, or GitHub Issues) is covered by at least one created destination ticket (JIRA or GitHub Issues) — no silent drops. Parses the PRD into atomic items (goals, user stories, functional/non-functional requirements, acceptance criteria, important notes), maps each to the created tickets, and produces a coverage matrix and verdict (COMPLETE / COMPLETE_WITH_SCOPE_CREEP / GAPS_FOUND / NO_TICKETS_FOUND). Used by notion-prd-intake / confluence-prd-intake / linear-prd-intake / github-prd-intake post-write to gate the Ticketed transition; can also be invoked standalone for after-the-fact audits."
+description: "Verifies that every requirement in a PRD (Notion, Confluence, Linear, or GitHub Issues) is covered by at least one created destination ticket (JIRA, GitHub Issues, or Linear) — no silent drops. Parses the PRD into atomic items (goals, user stories, functional/non-functional requirements, acceptance criteria, important notes), maps each to the created tickets, and produces a coverage matrix and verdict (COMPLETE / COMPLETE_WITH_SCOPE_CREEP / GAPS_FOUND / NO_TICKETS_FOUND). Used by notion-prd-intake / confluence-prd-intake / linear-prd-intake / github-prd-intake post-write to gate the Ticketed transition; can also be invoked standalone for after-the-fact audits."
 allowed-tools: ["Skill", "Bash", "mcp__claude_ai_Notion__notion-fetch", "mcp__claude_ai_Notion__notion-get-comments", "mcp__atlassian__getConfluencePage", "mcp__atlassian__getConfluencePageDescendants", "mcp__atlassian__getConfluencePageFooterComments", "mcp__atlassian__getConfluencePageInlineComments", "mcp__atlassian__getConfluenceCommentChildren", "mcp__atlassian__getJiraIssue", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__linear-server__get_project", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_comments"]
 ---
 

package/plugins/lisa/skills/product-walkthrough/SKILL.md

@@ -66,8 +66,8 @@ For every walkthrough, record:
 
 - **What exists today**: a short prose description of the current flow, the components in use (if you can identify them from the DOM via `browser_snapshot`), and the states observed.
 - **What the PRD changes**: explicit delta — added screens, removed screens, modified components, new states, removed states.
-- **Existing-component reuse candidates**: components in the current product that could absorb the new behavior. The PRD-vs-current-product comparison drives which existing components a developer should reuse instead of building new (see `lisa:jira-source-artifacts` §7).
-- **Design-vs-current-product divergence**: places where the mock/prototype materially diverges from what's shipped. Each divergence is a discussion item, not an automatic "rebuild from scratch" — see `lisa:jira-source-artifacts` §3 (mocks define visual intent, not implementation shortcut).
+- **Existing-component reuse candidates**: components in the current product that could absorb the new behavior. The PRD-vs-current-product comparison drives which existing components a developer should reuse instead of building new (see `lisa:tracker-source-artifacts` §7).
+- **Design-vs-current-product divergence**: places where the mock/prototype materially diverges from what's shipped. Each divergence is a discussion item, not an automatic "rebuild from scratch" — see `lisa:tracker-source-artifacts` §3 (mocks define visual intent, not implementation shortcut).
 - **Coverage smells**: states the PRD doesn't address that exist today (e.g., the mock shows the empty state but ignores the populated state that has 90% of users).
 - **Behavioral surprises**: anything that doesn't match the PRD's assumptions about current behavior — these are usually the most valuable findings, because they invalidate parts of the PRD.
 

package/plugins/lisa/skills/spec-conformance/SKILL.md

@@ -24,8 +24,7 @@ Based on the source, load the full spec:
 | Source | How to Load |
 |--------|-------------|
 | Plan file (`.md`) | `Read` the file |
-| JIRA key or GitHub issue ref | Invoke `/tracker-read <ref>` (vendor-neutral; dispatches to `/jira-read-ticket` or `/github-read-issue` per `.lisa.config.json` `tracker`) to get the full context bundle (primary ticket + epic / parent + linked tickets) |
-| Linear key | Fetch via Linear MCP if available; else `Bash` with Linear CLI; else report "Linear reader unavailable" |
+| JIRA key, GitHub issue ref, or Linear identifier | Invoke `/tracker-read <ref>` (vendor-neutral; dispatches to `/jira-read-ticket`, `/github-read-issue`, or `/linear-read-issue` per `.lisa.config.json` `tracker`) to get the full context bundle (primary item + epic / project / parent + linked items) |
 | PRD | `Read` the file or fetch via Notion / Confluence MCP, or `gh issue view` for a GitHub PRD |
 
 ## Phase 2 — Extract Requirements

package/plugins/lisa/skills/ticket-triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ticket-triage
-description: "Analytical triage gate for tickets in the configured destination tracker (JIRA or GitHub Issues). Detects requirement ambiguities, identifies edge cases from codebase analysis, and plans verification methodology. Posts findings to the ticket and produces a verdict (BLOCKED/PASSED_WITH_FINDINGS/PASSED) that gates whether implementation can proceed. Vendor-neutral: the caller (jira-agent or github-agent) is responsible for fetching the ticket via lisa:tracker-read, running the pre-flight gate via lisa:tracker-verify, and posting findings via the matching vendor comment tool."
+description: "Analytical triage gate for tickets in the configured destination tracker (JIRA, GitHub Issues, or Linear). Detects requirement ambiguities, identifies edge cases from codebase analysis, and plans verification methodology. Posts findings to the ticket and produces a verdict (BLOCKED/PASSED_WITH_FINDINGS/PASSED) that gates whether implementation can proceed. Vendor-neutral: the caller (jira-agent or github-agent) is responsible for fetching the ticket via lisa:tracker-read, running the pre-flight gate via lisa:tracker-verify, and posting findings via the matching vendor comment tool."
 allowed-tools: ["Read", "Glob", "Grep", "Bash"]
 ---
 

package/plugins/lisa/skills/tracker-add-journey/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tracker-add-journey
-description: "Vendor-neutral wrapper for appending a Validation Journey section to an existing ticket/issue. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-add-journey or lisa:github-add-journey."
+description: "Vendor-neutral wrapper for appending a Validation Journey section to an existing ticket/issue. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-add-journey, lisa:github-add-journey, or lisa:linear-add-journey."
 allowed-tools: ["Skill", "Bash", "Read"]
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: ["Skill", "Bash", "Read"]
 
 Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor skill.
 
-See the `tracker-resolution` rule for configuration and dispatch table.
+See the `config-resolution` rule for configuration and dispatch table.
 
 ## Workflow
 
@@ -16,9 +16,11 @@ See the `tracker-resolution` rule for configuration and dispatch table.
 2. Dispatch:
    - `jira` → invoke `lisa:jira-add-journey` with `$ARGUMENTS` verbatim. Arg: a JIRA ticket key.
    - `github` → invoke `lisa:github-add-journey` with `$ARGUMENTS` verbatim. Arg: `org/repo#<number>` or a GitHub issue URL.
+   - `linear` → invoke `lisa:linear-add-journey` with `$ARGUMENTS` verbatim. Arg: a Linear Issue identifier (e.g., `ENG-123`).
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
 3. Pass through the output.
 
 ## Rules
 
-- The Validation Journey content format is identical across both vendors (markdown sections with `[EVIDENCE: name]` markers). The only difference is how the section is appended — JIRA via `editJiraIssue`, GitHub via `gh issue edit --body-file`.
+- The Validation Journey content format is identical across all vendors (markdown sections with `[EVIDENCE: name]` markers). The only difference is how the section is appended — JIRA via `editJiraIssue` (Jira wiki markup), GitHub via `gh issue edit --body-file` (markdown), Linear via `save_issue` (markdown).
 - If the ticket already has a Validation Journey, the vendor skill reports it and stops. This shim does not retry.

package/plugins/lisa/skills/tracker-build-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tracker-build-intake
-description: "Vendor-neutral wrapper for the build-queue batch scanner. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-build-intake (JQL/project-key queue) or lisa:github-build-intake (GitHub repo queue keyed off the `status:ready` label). Counterpart to lisa:intake's PRD-side dispatchers."
+description: "Vendor-neutral wrapper for the build-queue batch scanner. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa:jira-build-intake (JQL/project-key queue), lisa:github-build-intake (GitHub repo queue keyed off the `status:ready` label), or lisa:linear-build-intake (Linear team queue keyed off the `status:ready` label). Counterpart to lisa:intake's PRD-side dispatchers."
 allowed-tools: ["Skill", "Bash", "Read"]
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: ["Skill", "Bash", "Read"]
 
 Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor build-queue scanner.
 
-See the `tracker-resolution` rule for configuration and dispatch table.
+See the `config-resolution` rule for configuration and dispatch table.
 
 ## Workflow
 
@@ -16,10 +16,12 @@ See the `tracker-resolution` rule for configuration and dispatch table.
 2. Dispatch:
    - `jira` → invoke `lisa:jira-build-intake` with `$ARGUMENTS` verbatim. Arg shape: a JIRA project key (e.g., `SE`) or a JQL filter.
    - `github` → invoke `lisa:github-build-intake` with `$ARGUMENTS` verbatim. Arg shape: a GitHub `org/repo` token or a full GitHub repo URL.
+   - `linear` → invoke `lisa:linear-build-intake` with `$ARGUMENTS` verbatim. Arg shape: a Linear team key (e.g., `ENG`) or the literal token `linear` (which falls back to `linear.teamKey`).
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
 3. Pass through the cycle summary verbatim.
 
 ## Rules
 
 - Single cycle per invocation — the vendor skill processes the current `Ready` set and exits.
-- The vendor skills run their own pre-flight checks (JIRA workflow transitions for the JIRA path; label namespace adoption for the GitHub path) before processing items. Never bypass.
+- The vendor skills run their own pre-flight checks (JIRA workflow transitions for the JIRA path; label namespace adoption for the GitHub and Linear paths) before processing items. Never bypass.
 - Never run two intake cycles concurrently against overlapping queues — the scheduling layer is responsible for serialization.