@codyswann/lisa 2.10.1 → 2.11.1

package/plugins/src/base/skills/github-write-issue/SKILL.md

@@ -92,7 +92,7 @@ Scenario: <name>
 ## Source Artifacts
 [Group by domain (UI / UX flow / Data / Ops / Reference). One bullet per
  artifact with title and URL. Inherited from the parent epic per the rules
- in lisa:jira-source-artifacts.]
+ in lisa:tracker-source-artifacts.]
 
 ## Source Precedence
 [When artifacts are attached, name the authoritative source per axis:
@@ -175,7 +175,7 @@ Identify and attach (under `## Links`):
 - Related GitHub PRs, branches, or commits.
 - Confluence / Notion / Linear PRD pages (the originating PRD).
 - Dashboards (Grafana, Datadog, Sentry).
-- **Source artifacts from the originating PRD / parent Epic**: classify and inherit per `lisa:jira-source-artifacts`. Inherit by domain — UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`. Never assume a developer will walk up to the Epic to find design context.
+- **Source artifacts from the originating PRD / parent Epic**: classify and inherit per `lisa:tracker-source-artifacts`. Inherit by domain — UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`. Never assume a developer will walk up to the Epic to find design context.
 
 If the issue was generated from a PRD and the parent Epic has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction.
 

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

@@ -27,7 +27,7 @@ The team lead does NOT read the input directly. The first task on the team's pla
 - If it's a ticket, calls `lisa:tracker-read` (preferred — vendor-agnostic; dispatches per `.lisa.config.json` `tracker`). **Mismatch guard**: if the ticket format doesn't match the configured tracker (e.g., a GitHub URL when `tracker` is `jira`), `tracker-read` stops and reports the error — never auto-translates vendors:
   - JIRA ticket → `lisa:tracker-read` → `lisa:jira-read-ticket`
   - GitHub Issue → `lisa:tracker-read` → `lisa:github-read-issue`
-  - Linear ticket → the Linear CLI (no `lisa:linear-*` build-side adapter; Linear is a PRD source only)
+  - Linear identifier or project URL → `lisa:tracker-read` → `lisa:linear-read-issue`
   - Captures comments and metadata, not just the description.
 - If it's a file, reads the entire file without offset or limit.
 - If it's a plain-text request, uses the provided text verbatim as the resolved input.

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

@@ -49,7 +49,7 @@ Detect the queue type from `$ARGUMENTS` and route:
 | A Confluence **parent page** URL or page ID (the page whose descendants are PRDs) | PRD queue (Confluence, narrowed) | Invoke `lisa:confluence-prd-intake` with the parent ID (CQL: `ancestor = <id> AND label = "prd-ready"`) |
 | A Linear **workspace** URL (e.g. `https://linear.app/acme`) | PRD queue (Linear) | Invoke `lisa:linear-prd-intake` (which queries `list_projects({label: "prd-ready"})` across the workspace, claims each by relabeling to `prd-in-review`, runs the dry-run validate → branch → write pipeline) |
 | A Linear **team** URL (e.g. `https://linear.app/acme/team/ENG/projects`) or a token already routed as a Linear team key | PRD queue (Linear, narrowed) | Invoke `lisa:linear-prd-intake` with the team key (`list_projects({team, label: "prd-ready"})`) |
-| The literal token `linear` | PRD queue (Linear, default workspace) | Invoke `lisa:linear-prd-intake linear` — only valid if `LINEAR_WORKSPACE` is configured |
+| The literal token `linear` | PRD queue (Linear, default workspace) | Invoke `lisa:linear-prd-intake linear` — only valid if `linear.workspace` is configured in `.lisa.config.json` |
 | A JIRA project key (e.g. `SE`) | Work queue (JIRA) | Invoke `lisa:jira-build-intake` (which scans the project for Status=Ready, claims each via In Progress, runs `lisa:implement` per ticket, transitions to On Dev on success) |
 | A full JQL filter (e.g. `project = SE AND component = "frontend"`) | Work queue (JIRA, narrowed) | Invoke `lisa:jira-build-intake` with the JQL |
 | A GitHub **repository** URL or `org/repo` token (e.g. `https://github.com/acme/product-prds` or `acme/product-prds`) when used for **PRDs** | PRD queue (GitHub) | Invoke `lisa:github-prd-intake` (which queries `gh issue list --label prd-ready`, claims each by relabeling to `prd-in-review`, runs the dry-run validate → branch → write pipeline). PRD discovery is independent of the destination tracker — the resulting tickets land wherever `.lisa.config.json` `tracker` says. |
@@ -62,10 +62,10 @@ Disambiguation rules:
 - An Atlassian Confluence URL containing `/wiki/spaces/<KEY>` with no `/pages/...` segment → Confluence space queue.
 - An Atlassian Confluence URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` → Confluence parent-page queue (the page is the parent whose descendants are PRDs). If the user actually meant "this single page is a PRD, plan it", route to `lisa:plan` instead — this skill is batch-only.
 - A `linear.app` URL → Linear queue. If the path is `/<workspace>` only or `/<workspace>/team/<KEY>/...`, route here. If the path includes `/project/<slug>-<id>` it's a single-PRD URL — direct the caller to `lisa:plan` instead, this skill is batch-only.
-- The literal token `linear` (case-insensitive) → Linear queue, default workspace from `LINEAR_WORKSPACE`.
+- The literal token `linear` (case-insensitive) → Linear queue, default workspace from `linear.workspace` in `.lisa.config.json`.
 - A `github.com` URL or an `<org>/<repo>` token → GitHub queue. The PRD-vs-build dispatch is determined by which label namespace the repo currently uses: PRD-side (`prd-ready`) → `lisa:github-prd-intake`; build-side (`status:ready` and `tracker = github` in `.lisa.config.json`) → `lisa:tracker-build-intake`. If both namespaces are present, prefer the PRD queue unless `$ARGUMENTS` includes `intake_mode=build`. If the URL points at a single issue (`https://github.com/<org>/<repo>/issues/<n>`), this skill is batch-only — direct the caller to `lisa:plan` (for a single PRD issue) or `lisa:implement` (for a single build issue).
 - The literal token `github` (case-insensitive) → GitHub queue, default repo from `.lisa.config.json` `github.org` / `github.repo`.
-- A bare alphanumeric token that matches the configured `JIRA_PROJECT` regex (uppercase letters / digits / hyphen, ≤10 chars) is treated as a JIRA project key by default. A token that does not match the regex is treated as a Confluence space key. If it does not resolve as a Confluence space key either, attempt to resolve as a Linear team key via `mcp__linear-server__list_teams({query})` before giving up. The only time to stop and ask is when the token resolves to more than one of {JIRA project, Confluence space, Linear team, GitHub `org/repo`} simultaneously — in that overlap the user must disambiguate which queue to scan.
+- A bare alphanumeric token that matches the JIRA project key regex (uppercase letters / digits / hyphen, ≤10 chars — typically the value of `jira.project` in `.lisa.config.json`) is treated as a JIRA project key by default. A token that does not match the regex is treated as a Confluence space key. If it does not resolve as a Confluence space key either, attempt to resolve as a Linear team key via `mcp__linear-server__list_teams({query})` before giving up. The only time to stop and ask is when the token resolves to more than one of {JIRA project, Confluence space, Linear team, GitHub `org/repo`} simultaneously — in that overlap the user must disambiguate which queue to scan.
 - An `<org>/<repo>` token (slash-separated, both halves are GitHub-name-shaped) → GitHub queue.
 - A string starting with `project = ` or containing JQL operators (`AND`, `OR`, `=`, `!=`, `~`, etc.) → JQL filter.
 

package/plugins/src/base/skills/jira-build-intake/SKILL.md

@@ -131,13 +131,16 @@ Total PRs opened: <n>
 
 ## Configuration
 
+Reads `atlassian.cloudId` and `jira.project` from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key). The project key is also accepted as `$ARGUMENTS` for ad-hoc invocations.
+
 Status names default to `Ready`, `In Progress`, `On Dev`. If a project uses different names (`Open` instead of `TODO`, `In Development` instead of `In Progress`, `Code Review` instead of `On Dev`), pass overrides in `$ARGUMENTS` as `claim_status="In Development" done_status="Code Review"`.
 
 If a `Ready` status does not exist in the JIRA project's workflow, this skill cannot run. The remediation is to add `Ready` to the project workflow scheme — JIRA admin task, not something this skill can do.
 
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `JIRA_PROJECT` | (from `$ARGUMENTS`) | Project key for the default JQL |
+| Field / variable | Default | Purpose |
+|------------------|---------|---------|
+| `.lisa.config.json` `jira.project` | (from `$ARGUMENTS`) | Project key for the default JQL |
+| `.lisa.config.json` `atlassian.cloudId` | — | Atlassian Cloud site UUID (required) |
 | Status: queue | `Ready` | The status that signals "human says this is buildable" |
 | Status: claim | `In Progress` | The intermediate status the agent sets on pickup |
 | Status: done | `On Dev` | The status set after a successful build |

package/plugins/src/base/skills/jira-create/SKILL.md

@@ -11,7 +11,7 @@ Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans struc
 ## Process
 
 1. **Analyze**: Read $ARGUMENTS to understand scope.
-2. **Extract source artifacts**: invoke the `lisa:jira-source-artifacts` skill, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain per its rules. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
+2. **Extract source artifacts**: invoke the `lisa:tracker-source-artifacts` skill, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain per its rules. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
 3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill to capture current behavior, design-vs-product divergence, and reuse candidates. Skip when the work is purely backend or affects a screen that does not yet exist. See "Live Product Walkthrough" below.
 4. **Determine structure**:
    - Epic needed if: multiple features, major changes, >3 related files
@@ -20,8 +20,8 @@ Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans struc
    ```text
    Epic → User Story → Tasks (test, implement, document, cleanup)
    ```
-6. **Delegate every write to `lisa:jira-write-ticket`** in dependency order (epic first, then stories with the epic as parent, then sub-tasks with their story as parent). Pass the artifacts (filtered by domain per `lisa:jira-source-artifacts` inheritance rules) and the walkthrough findings (under `## Current Product`). See "Delegation to jira-write-ticket" below.
-7. **Run the artifact preservation gate** (`lisa:jira-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created tickets. Fail loudly if anything was dropped.
+6. **Delegate every write to `lisa:jira-write-ticket`** in dependency order (epic first, then stories with the epic as parent, then sub-tasks with their story as parent). Pass the artifacts (filtered by domain per `lisa:tracker-source-artifacts` inheritance rules) and the walkthrough findings (under `## Current Product`). See "Delegation to jira-write-ticket" below.
+7. **Run the artifact preservation gate** (`lisa:tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created tickets. Fail loudly if anything was dropped.
 
 ## Mandatory for Every Code Issue
 
@@ -89,7 +89,7 @@ h3. Assertions
 
 If $ARGUMENTS includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as remote links on the created tickets. Silent artifact loss is the single most common quality failure in this pipeline.
 
-**Invoke the `lisa:jira-source-artifacts` skill** for the canonical rules: domains, per-tool classification (Figma `/proto/` vs design, Lovable, Loom, screenshots), source precedence, conflict handling under `## Open Questions`, inheritance from epic → story → sub-task, and the existing-component reuse expectation. Do not restate the rules here — invoke the skill so any rule change propagates uniformly.
+**Invoke the `lisa:tracker-source-artifacts` skill** for the canonical rules: domains, per-tool classification (Figma `/proto/` vs design, Lovable, Loom, screenshots), source precedence, conflict handling under `## Open Questions`, inheritance from epic → story → sub-task, and the existing-component reuse expectation. Do not restate the rules here — invoke the skill so any rule change propagates uniformly.
 
 When delegating actual writes to `lisa:jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
 

package/plugins/src/base/skills/jira-validate-ticket/SKILL.md

@@ -174,7 +174,7 @@ Either way the gate emits `FAIL`, not a third state. Strictness is the caller's
 
 When `artifacts_attached = true`, description must include source-precedence guidance covering: business rules → PRD body, visual treatment → mocks, flow → prototypes, API/data → data artifacts. Cross-axis conflicts surfaced under `## Open Questions`.
 
-Accept either placement — both are valid per `lisa:jira-source-artifacts`:
+Accept either placement — both are valid per `lisa:tracker-source-artifacts`:
 - A dedicated `## Source Precedence` (or `h2. Source Precedence`) subsection, OR
 - A "Source Precedence" / "source precedence" / "authoritative source" paragraph under `Technical Approach` that covers the four axes above.
 

package/plugins/src/base/skills/jira-write-ticket/SKILL.md

@@ -170,15 +170,15 @@ Identify and attach:
 - Confluence pages (design docs, RFCs, runbooks)
 - Dashboards (Grafana, Datadog, Sentry issue)
 - Incident tickets (PagerDuty, Statuspage)
-- **Source artifacts from the originating PRD / parent epic**: classify and inherit per the rules in `lisa:jira-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). The short version: enumerate the parent epic's remote links and inherit the ones whose domain matches this ticket's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`). Never assume a developer will walk up to the epic to find design context — attach it here.
+- **Source artifacts from the originating PRD / parent epic**: classify and inherit per the rules in `lisa:tracker-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). The short version: enumerate the parent epic's remote links and inherit the ones whose domain matches this ticket's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`). Never assume a developer will walk up to the epic to find design context — attach it here.
 
 If the ticket was generated from a PRD (by `lisa:notion-to-tracker` or similar) and the parent epic 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 ticket)
 
-Source precedence rules and cross-axis conflict handling are defined in `lisa:jira-source-artifacts` §3 and §4. When a ticket carries both design artifacts and a description, record the precedence explicitly in the ticket 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.
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-source-artifacts` §3 and §4. When a ticket carries both design artifacts and a description, record the precedence explicitly in the ticket 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 tickets, include the existing-component reuse expectation per `lisa:jira-source-artifacts` §7.
+For UI-touching tickets, include the existing-component reuse expectation per `lisa:tracker-source-artifacts` §7.
 
 ### 4e. Live Product Walkthrough Findings (UI-touching tickets)
 

package/plugins/src/base/skills/linear-add-journey/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: linear-add-journey
+description: "Add a Validation Journey section to an existing Linear Issue by analyzing the change type and generating appropriate verification steps with evidence markers. Linear counterpart of lisa:jira-add-journey."
+allowed-tools: ["Bash", "Read", "Glob", "Grep", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue"]
+---
+
+# Add Validation Journey to Existing Linear Issue
+
+Read an existing Linear Issue, analyze the change type, and append a Validation Journey section to the description with appropriate verification steps based on the project's verification patterns.
+
+This skill is the destination of the `lisa:tracker-add-journey` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Arguments
+
+`$ARGUMENTS`: `<IDENTIFIER>` — Linear Issue identifier (e.g. `ENG-123`).
+
+## Workflow
+
+### Step 1: Read the Issue
+
+Fetch via `mcp__linear-server__get_issue` and extract: title, description (markdown), labels, project, parent, attachments.
+
+### Step 2: Check for Existing Journey
+
+If the description already contains a `## Validation Journey` section, report and stop — never overwrite an existing journey without explicit instruction.
+
+### Step 3: Analyze the Change Type
+
+Examine the description, acceptance criteria, and codebase to determine the change type:
+
+1. **API/GraphQL** — New or modified endpoints, request/response schemas
+2. **Database migration** — Schema changes, new tables/columns, indexes
+3. **Background job/queue** — New job processors, queue consumers, event handlers
+4. **Library/utility** — Exported functions, shared modules, npm package changes
+5. **Security fix** — Auth, authorization, input validation, OWASP vulnerabilities
+6. **Authentication/authorization** — Role-based access, session management, tokens
+7. **UI/frontend** — Components, flows, browser-driven verification
+
+Use Explore agents or read the codebase to understand which files are affected and what verification approach is appropriate.
+
+### Step 4: Map Change Type to Verification Pattern
+
+| Change Type | Verification Approach |
+|---|---|
+| API/GraphQL | curl commands verifying endpoints, status codes, response schemas |
+| Database migration | Migration execution + schema verification + rollback check |
+| Background job/queue | Enqueue + process + state change verification |
+| Library/utility | Test execution + build verification + export check |
+| Security fix | Exploit reproduction pre-fix + exploit failure post-fix |
+| Auth/authz | Multi-role verification with explicit status codes |
+| UI/frontend | Playwright browser flow + visual evidence |
+
+### Step 5: Draft the Validation Journey (markdown)
+
+Linear descriptions are markdown. Use `##` and `###` headings — not Jira wiki markup.
+
+```markdown
+## Validation Journey
+
+### Prerequisites
+- List required services, database, env vars
+
+### Steps
+1. Verify current state before changes
+2. Apply the change
+3. Verify expected new state [EVIDENCE: state-name]
+4. Test error/edge cases [EVIDENCE: error-case]
+5. Verify rollback if applicable [EVIDENCE: rollback]
+
+### Assertions
+- Describe what must be true after verification
+```
+
+### Guidelines for Drafting
+
+1. **2–5 evidence markers** — Focus on proving the change works and handles errors.
+2. **Concrete, runnable steps** — `Run \`curl -s localhost:3000/health | jq .status\`` not "Check the endpoint".
+3. **Include environment setup** — Database connection, running services, env vars.
+4. **Evidence names in kebab-case** — `api-response`, `schema-check`, `rate-limit-hit`.
+5. **Assertions are measurable** — "Returns 200 with `{status: ok}`" not "API works correctly".
+6. **Cover happy path and error path** — At minimum, one success and one failure evidence marker.
+
+### Step 6: Present to User for Approval
+
+Display the drafted journey and ask for confirmation before appending.
+
+### Step 7: Append to Issue Description
+
+After approval, fetch the current description, append the new Validation Journey section, and update via `mcp__linear-server__save_issue({id, description: <new-description>})`. Preserve all existing description content — never overwrite.
+
+### Step 8: Verify
+
+Re-fetch the issue and confirm the section is present.
+
+## When to Use This Skill
+
+- Issue was created before the Validation Journey convention was established
+- Issue was created manually without following `lisa:linear-create` guidelines
+- Issue needs a journey added or updated based on implementation progress
+- Before starting work on an Issue, to ensure verification steps are documented

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

@@ -0,0 +1,160 @@
+---
+name: linear-build-intake
+description: "Symmetric counterpart to lisa:jira-build-intake on the Linear side. Scans a Linear team for Issues labeled status:ready, claims each by relabeling to status:in-progress, runs the implementation/build flow via lisa:linear-agent, and relabels to status:on-dev on completion. status:ready is the human-flipped signal that an Issue is truly ready for development — mirroring how Notion PRDs work Draft → Ready → (us) In Review → Blocked|Ticketed."
+allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_teams", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label"]
+---
+
+# Linear Build Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A Linear team key (e.g. `ENG`) — scans that team for `status:ready` Issues.
+2. The literal token `linear` — falls back to `linear.teamKey` from `.lisa.config.json`.
+3. A pre-built Linear MCP filter (advanced) — used as-is.
+
+Run one build-intake cycle. Each `status:ready` Issue is claimed, built via the `lisa:linear-agent` flow, and relabeled to `status:on-dev` on completion. The cycle is the symmetric mirror of `lisa:jira-build-intake` and `lisa:github-build-intake`: humans flip `status:ready`, agents pick up and progress.
+
+This skill is the destination of the `lisa:tracker-build-intake` shim when `tracker = "linear"`.
+
+## Why labels, not native states
+
+Linear's per-team workflow state names vary (`Todo` / `Backlog` / `Up Next` / etc.). Labels are workspace-scoped or team-scoped and stable across teams, so we drive the build queue off labels rather than chasing renamed native states. The native `state` field is informational only for this skill.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Confirmation policy
+
+Do NOT ask the caller whether to proceed. Once invoked with a team key, run the cycle to completion — claim, dispatch each Issue through `lisa:linear-agent`, transition successful builds to `status:on-dev`, write the summary. The caller (a human or a cron) has already authorized the run by invoking the skill.
+
+Specifically forbidden:
+
+- Previewing projected scope (Issue count, projected PR count, build duration) and asking whether to continue.
+- Offering A/B/C-style choices like "proceed / skip a few / dry-run only" — the documented behavior IS the default.
+- Pausing because the queue is large, items look complex, or items are likely to be `status:blocked` by `lisa:linear-agent`'s pre-flight gate. The pre-flight `status:blocked` outcome is a valid terminal state of the per-Issue lifecycle.
+- Pausing because the build flow looks expensive.
+
+The only legitimate reasons to stop early:
+
+- Missing team key or required configuration. Surface and exit.
+- Label convention not yet adopted (`status:ready` does not exist on the team's labels). Surface and exit with an Adoption hint.
+- Empty `status:ready` set. Exit cleanly with `"No Linear Issues labeled status:ready. Nothing to do."`
+
+## Lifecycle assumed
+
+Linear build queue uses these issue-level labels:
+
+```text
+status:ready → status:in-progress → status:code-review → status:on-dev → status:done
+(human/PM)    (us claim)            (us PR ready)        (us build done)  (downstream)
+```
+
+This skill ONLY transitions `status:ready → status:in-progress` on claim, and `status:in-progress → status:on-dev` on completion. It never touches `status:done`, `status:code-review` (owned by `lisa:linear-agent` / `lisa:linear-evidence`), or `status:blocked` (owned by `lisa:linear-agent`'s pre-flight gate).
+
+**Pre-flight check**: at start of each cycle, confirm `status:ready`, `status:in-progress`, `status:on-dev` exist on the team via `mcp__linear-server__list_issue_labels`. If `status:ready` is missing, stop and report adoption needed. The other labels can be created on demand.
+
+## Phases
+
+### Phase 1 — Resolve scope
+
+1. Parse `$ARGUMENTS`:
+   - Bare team key → use as-is.
+   - Literal `linear` → fall back to `linear.teamKey` from config.
+2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
+
+### Phase 2 — Find Ready Issues
+
+Query: `mcp__linear-server__list_issues({team: <teamId>, label: "status:ready"})`.
+
+Capture each Issue's: identifier, title, type label, priority, assignee, project, labels, description summary.
+
+If empty, report `"No Linear Issues labeled status:ready. Nothing to do."` and exit. Common idle case.
+
+### Phase 3 — Process each Ready Issue (serial)
+
+#### 3a. Claim
+
+Update labels via `mcp__linear-server__save_issue`: remove `status:ready`, add `status:in-progress`. Resolve label IDs via `list_issue_labels` (create `status:in-progress` if missing).
+
+Post a `[claude-build-intake]` comment via `save_comment`: `"Claimed by Claude. Starting build."`
+
+This is the idempotency lock — a re-entrant cycle's `label: status:ready` filter will not see this Issue again.
+
+If the relabel fails (permission, race), record under "Errors" and skip. **Do not invoke the build flow on an Issue you didn't successfully claim.**
+
+#### 3b. Run the build flow
+
+Invoke `lisa:linear-agent` (per-Issue lifecycle agent) with the Issue identifier. `lisa:linear-agent` owns:
+- Reading the full Issue graph (`lisa:linear-read-issue`)
+- Running its own pre-flight quality gate (`lisa:linear-verify`)
+- Running ticket triage (`lisa:ticket-triage`)
+- Routing to the appropriate flow (Build / Fix / Investigate / Improve based on type)
+- Posting progress comments via `lisa:linear-sync`
+- Posting evidence via `lisa:linear-evidence`
+
+Wait for the agent to return. Capture its outcome:
+- **Success** — PR is ready (open or merged); evidence posted; ready for next status.
+- **Blocked by linear-verify pre-flight gate** — `lisa:linear-agent` itself relabels to `status:blocked` and assigns to creator. Let it stand. Record and move on.
+- **Blocked by ticket-triage ambiguities** — agent posts findings and stops. The Issue stays at `status:in-progress`. Surface to human; do not auto-transition. Record under "Errors".
+- **Errored** — exception, missing config, etc. Leave at `status:in-progress`. Record with exception summary.
+
+#### 3c. Relabel to status:on-dev (only on Success)
+
+If `lisa:linear-agent` returned Success:
+1. Update labels via `mcp__linear-server__save_issue`: remove `status:in-progress`, add `status:on-dev`. (Note: at this point `lisa:linear-evidence` has typically already moved the Issue to `status:code-review` after PR creation. The transition is `status:code-review → status:on-dev` if that's the current state.)
+2. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. Transitioned to status:on-dev."`
+
+For any non-Success outcome, do NOT transition. The Issue sits where the agent left it — humans take it from there.
+
+#### 3d. Continue
+
+Move to the next Ready Issue. One Issue failing does not stop others.
+
+### Phase 4 — Summary report
+
+```text
+## linear-build-intake summary
+
+Team: <teamKey>
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+Issues processed: <n>
+- status:on-dev (build complete, PR ready): <n>
+  - <ID> <title> → PR <URL>
+- status:blocked (pre-flight verify failed): <n>
+  - <ID> <title> — see Issue comments
+- Held (triage found ambiguities): <n>
+  - <ID> <title> — see Issue comments
+- Errors: <n>
+  - <ID> <title> — <reason>
+
+Total PRs opened: <n>
+```
+
+## Idempotency & safety
+
+- **Claim-first ordering**: `status:in-progress` set BEFORE agent invocation — no double-pickup.
+- **No writes outside the lifecycle**: this skill only adds/removes `status:ready`, `status:in-progress`, `status:on-dev`. Every other label change (and the native state) is owned by the agent or `lisa:linear-evidence`.
+- **Failure isolation**: per-Issue exceptions caught and recorded; the cycle continues.
+- **Single cycle per team**: do not run two concurrent cycles against the same team — concurrent claims could race.
+- **Single-label invariant**: after every transition, verify exactly one `status:*` label is present. Two simultaneously breaks the build queue.
+
+## Adoption (one-time per team)
+
+Before this skill can run against a Linear team, the team must adopt the `status:*` issue-label convention:
+
+1. Create labels `status:ready`, `status:in-progress`, `status:code-review`, `status:on-dev`, `status:done`, `status:blocked` on the team (or workspace).
+2. Apply `status:ready` to Issues that are ready for development.
+3. Reserve `status:in-progress`, `status:code-review`, `status:on-dev` for Lisa — humans should not set them manually except to recover from an error.
+
+If the team hasn't adopted these labels, the first run exits with an adoption hint.
+
+## Rules
+
+- Never relabel an Issue the cycle didn't claim. The `status:in-progress` transition is the signature of cycle ownership.
+- Never bypass `lisa:linear-agent` to do build work directly. The agent owns the per-Issue lifecycle.
+- Never auto-transition past `status:on-dev`. Downstream labels (`status:done`) are owned by QA / product / a future verification-intake skill.
+- If the Issue has no Validation Journey or no sign-in credentials in its description, `lisa:linear-agent`'s pre-flight verify will catch it and relabel to `status:blocked` — don't try to fix the Issue from here.
+- On any unexpected response from `lisa:linear-agent` (label it doesn't claim, missing PR URL on success, etc.), record as Error and surface — never assume.

package/plugins/src/base/skills/linear-create/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: linear-create
+description: "Creates Linear Projects (Epic-equivalent), Issues (Story / Task / Bug / Spike), and sub-Issues (Sub-task) from code files or descriptions. Analyzes the input, determines the appropriate hierarchy, and creates items with comprehensive quality requirements including test-first development and Validation Journey. The Linear counterpart of lisa:jira-create — delegates every write to lisa:linear-write-issue."
+allowed-tools: ["Read", "Glob", "LS", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__list_projects", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+---
+
+# Create Linear Work Items from $ARGUMENTS
+
+Analyze the provided file(s) and plan a Linear hierarchy. **This skill plans structure only — every individual write is delegated to `lisa:linear-write-issue`.** Do not call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` from this skill; those write tools are intentionally not in `allowed-tools`.
+
+This skill is the destination of the `lisa:tracker-create` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Process
+
+1. **Analyze**: Read `$ARGUMENTS` to understand scope.
+2. **Extract source artifacts**: invoke `lisa:tracker-source-artifacts`, then enumerate every external URL, embed, attachment, or example payload in the input and classify each by domain. Build the `artifacts` map (one entry per artifact: url, title, domain, source page, classification reason). See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke `lisa:product-walkthrough` to capture current behavior, design-vs-product divergence, and reuse candidates. Skip when the work is purely backend or affects a screen that does not yet exist.
+4. **Determine structure**:
+   - Project (Epic) needed if: multiple features, major changes, >3 related files
+   - Direct Issues if: bug fix, single file, minor change
+5. **Plan hierarchy**:
+   ```text
+   Project (Epic) → Issue (Story) → sub-Issue (Sub-task)
+   ```
+   Mapping per Linear best practices: Epic → Linear Project, Story → Issue with `projectId`, Sub-task → Issue with `parentId`. See `config-resolution.md` "Linear destination semantics".
+6. **Delegate every write to `lisa:linear-write-issue`** in dependency order (Project first, then Issues with `projectId` set, then sub-Issues with `parentId`). Pass artifacts (filtered by domain per `lisa:tracker-source-artifacts` inheritance rules) and walkthrough findings (under `## Current Product`).
+7. **Run the artifact preservation gate** (`lisa:tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created items. Fail loudly if anything was dropped.
+
+## Mandatory for Every Code Issue
+
+- **Test-First**: Write tests before implementation
+- **Quality Gates**: All tests / checks must pass, no SonarCloud violations
+- **Documentation**: Check existing, update / create new, remove obsolete
+- **Cleanup**: Remove temporary code, scripts, dev configs
+
+## Validation Journey
+
+Items that change runtime behavior should include a `## Validation Journey` section. This section is consumed by `lisa:linear-journey` to automate verification.
+
+### When to Include
+
+- API endpoint changes (new, modified, or removed routes)
+- Database schema changes (migrations, new columns, index changes)
+- Background job / queue processing changes
+- Library / utility function changes that affect exports
+- Security fixes (authentication, authorization, input validation)
+- Performance-critical changes requiring measurement
+
+### When to Skip
+
+- Documentation-only changes
+- Config-only changes (env vars, CI/CD, feature flags with no code)
+- Type-definition-only changes
+
+### How to Write
+
+Design the journey based on the **change type**. Place `[EVIDENCE: name]` markers at key verification points.
+
+```markdown
+## Validation Journey
+
+### Prerequisites
+- Local dev server running
+- Database accessible
+- Required environment variables set
+
+### Steps
+1. Verify the current state before changes
+2. Apply the change (run migration, deploy, etc.)
+3. Verify the expected new state [EVIDENCE: state-after-change]
+4. Test error/edge cases [EVIDENCE: error-handling]
+5. Verify rollback or cleanup if applicable [EVIDENCE: rollback-check]
+
+### Assertions
+- Describe what must be true after verification
+- Each assertion is verified against the captured evidence
+```
+
+## Source Artifacts
+
+If `$ARGUMENTS` includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as attachments / remote links on the created items. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke `lisa:tracker-source-artifacts`** for the canonical rules: domains, per-tool classification, source precedence, conflict handling under `## Open Questions`, inheritance from Project → Issue → sub-Issue, and the existing-component reuse expectation. Do not restate the rules here — invoke the skill so any rule change propagates uniformly.
+
+When delegating actual writes to `lisa:linear-write-issue`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke `lisa:product-walkthrough` before drafting items. The walkthrough findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the item plan and surface under `## Current Product` on the resulting items. Skip only when the work is purely backend or affects a screen that does not yet exist.
+
+## Item Requirements
+
+Each item must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default team: from `linear.teamKey` config (override via arguments).
+
+## Delegation to linear-write-issue
+
+**Mandatory.** Every item created by this skill MUST go through `lisa:linear-write-issue`. This skill never calls `mcp__linear-server__save_*` itself — those tools are intentionally excluded from `allowed-tools` so the gate cannot be bypassed.
+
+`lisa:linear-write-issue` enforces:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Project parent for Stories; parentId for Sub-tasks
+- Explicit relationship discovery (`blocks` / `blocked_by` / `relates_to` / `duplicates`)
+- Remote links / attachments
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+### Invocation order
+
+Items must be created in parent-before-child order so each child can be passed its parent ID:
+
+1. Invoke `lisa:linear-write-issue` for the Epic (Project). Capture the returned Project ID.
+2. For each Story, invoke `lisa:linear-write-issue` with the Project ID as `parent_project_id`. Capture each Issue identifier.
+3. For each Sub-task, invoke `lisa:linear-write-issue` with the Story Issue ID as `parent_issue_id`.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, team key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent ID (Project for Stories; Story for Sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules
+- For items that change runtime behavior: the Validation Journey draft (or instruct it to call `lisa:linear-add-journey` after create)
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's a Project vs. Issue vs. sub-Issue)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent IDs through subsequent writes
+- Running the Phase 5.5-style preservation check after all writes complete
+
+It does not own the actual Linear write — that's `lisa:linear-write-issue`'s job.

package/plugins/src/base/skills/linear-evidence/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: linear-evidence
+description: "Uploads text evidence to the GitHub `pr-assets` release, updates the PR description, posts a comment on the originating Linear Issue with code blocks, and transitions the Issue from in-progress to code-review by relabeling. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/code-blocks.md. Linear counterpart of lisa:jira-evidence and lisa:github-evidence."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label"]
+---
+
+# Linear Evidence: $ARGUMENTS
+
+Post verification evidence to a Linear Issue and transition it to the code-review state. This skill is the destination of the `lisa:tracker-evidence` shim when `tracker = "linear"`.
+
+`$ARGUMENTS` is the Linear Issue identifier (e.g. `ENG-123`) and the path to the evidence directory. Caller passes both: `<IDENTIFIER> <evidence-dir>`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Inputs (in `<evidence-dir>`)
+
+The caller must produce:
+
+- `evidence/comment.txt` — the human-readable comment body posted on the Linear Issue.
+- `evidence/code-blocks.md` — fenced code blocks (test outputs, command output, log excerpts) appended to the comment.
+- `evidence/files/` (optional) — any text files that should be uploaded to the GitHub `pr-assets` release for permalink-style references.
+
+If any of these are missing, stop and report.
+
+## Phase 1 — Resolve Linear Issue
+
+1. Parse the identifier from `$ARGUMENTS`.
+2. Fetch via `mcp__linear-server__get_issue` to confirm it exists and capture its current state, label set, and Project membership.
+
+## Phase 2 — Upload Evidence Files (optional)
+
+If `evidence/files/` is non-empty, upload each text file to the GitHub `pr-assets` release on the current repo via `gh release upload`. The release is the permalink store — keeps the Linear comment lightweight while preserving large outputs.
+
+For each uploaded file, capture the public release URL.
+
+## Phase 3 — Update PR Description
+
+If a PR is open on the current branch (`gh pr view --json url,number,body 2>/dev/null`), append an "Evidence" section to its description with:
+
+- The Linear identifier and URL (constructed as `https://linear.app/<workspace>/issue/<IDENTIFIER>`).
+- Links to any uploaded evidence files.
+- A short summary line (first 2 lines of `evidence/comment.txt`).
+
+If no PR is open, skip this phase.
+
+## Phase 4 — Post Linear Comment
+
+Call `mcp__linear-server__save_comment({issueId: <id>, body: <body>})` where `<body>` is:
+
+```markdown
+[<comment.txt contents verbatim>]
+
+<details>
+<summary>Evidence</summary>
+
+[<code-blocks.md contents verbatim>]
+
+</details>
+
+[<bullet list of uploaded evidence file URLs, if any>]
+```
+
+Linear comments support markdown including `<details>` collapsibles, fenced code, and links — preserve the formatting.
+
+## Phase 5 — Transition Status
+
+Update labels via `mcp__linear-server__save_issue` to remove `status:in-progress` and add `status:code-review`. Resolve label IDs first via `mcp__linear-server__list_issue_labels` (create the label via `create_issue_label` if it doesn't exist on the team).
+
+The native Linear `state` field is also updated to the team's "In Review" state if one exists — but the label remains the source of truth for cross-team consistency.
+
+## Phase 6 — Report
+
+Return:
+
+- Linear Issue URL with new label state
+- PR URL (if updated)
+- List of uploaded evidence file URLs
+
+## Rules
+
+- Never modify the Issue description as part of evidence posting — comments only. Description edits go through `lisa:linear-write-issue`.
+- Never skip the label transition. The build queue is keyed off `status:*` labels; an item that ships without transitioning is invisible to monitoring.
+- If `mcp__linear-server__save_comment` fails, retry once. If it fails again, surface the error — don't pretend the comment was posted.
+- Do not delete prior comments. The history is the audit trail.