@codyswann/lisa 2.10.1 → 2.11.0

package/plugins/lisa/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/lisa/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/lisa/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.

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

@@ -0,0 +1,134 @@
+---
+name: linear-journey
+description: "Parse a Linear Issue's Validation Journey section, execute the verification steps using appropriate tools (curl, test commands, database queries, Playwright), capture evidence at each [EVIDENCE: name] marker, and post to Linear + GitHub PR using the linear-evidence skill. Linear counterpart of lisa:jira-journey."
+allowed-tools: ["Bash", "Read", "Glob", "Grep", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue"]
+---
+
+# Linear Validation Journey
+
+Parse a Linear Issue's Validation Journey, execute the verification steps using the appropriate tools for the change type, capture evidence at each `[EVIDENCE: name]` marker, and post to Linear + GitHub PR.
+
+This skill is the destination of the `lisa:tracker-journey` shim when `tracker = "linear"`.
+
+## Configuration
+
+Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
+
+## Arguments
+
+`$ARGUMENTS`: `<IDENTIFIER> [PR_NUMBER]`
+
+- `IDENTIFIER` (required): Linear Issue identifier (e.g. `ENG-123`)
+- `PR_NUMBER` (optional): GitHub PR number to update description
+
+## Prerequisites
+
+- Linear MCP authenticated
+- `gh` CLI authenticated
+- Appropriate services running for the verification type (dev server, database, etc.)
+
+## Workflow
+
+### Step 1: Parse the Validation Journey
+
+Fetch the Issue via `mcp__linear-server__get_issue` and extract the `## Validation Journey` section from the markdown description. Parse:
+
+- `### Prerequisites` — list of required services / env / setup
+- `### Steps` — numbered steps, each potentially containing `[EVIDENCE: name]` markers
+- `### Assertions` — what must be true after verification
+
+If the section is missing or has no steps, report `"No Validation Journey on <IDENTIFIER>. Run /linear-add-journey first."` and stop.
+
+### Step 2: Satisfy Prerequisites
+
+Before executing steps, verify each prerequisite:
+
+1. Required services running (dev server, database, queue worker)
+2. Database connectivity if needed
+3. Environment variables set
+4. Run any setup commands mentioned in prerequisites
+
+Stop and report if any prerequisite is not satisfied.
+
+### Step 3: Execute Steps and Capture Evidence
+
+Execute each step sequentially. Determine the verification approach based on the step text and change type:
+
+- **API endpoints** → Run curl commands, capture HTTP response to `evidence/NN-name.txt` (or `.json` for structured data)
+- **Database changes** → Run psql / migration commands, capture schema output
+- **Background jobs** → Trigger the job, check queue / state, capture logs
+- **Library / utility changes** → Run tests, capture output
+- **Security fixes** → Reproduce exploit attempt, verify fix
+- **UI / frontend** → Playwright browser flow, capture screenshots / DOM state
+
+At each `[EVIDENCE: name]` marker, capture stdout / stderr to a numbered file:
+
+#### Evidence Naming Convention
+
+`{NN}-{evidence-name}.{ext}`
+
+- `NN`: zero-padded sequential number (`01`, `02`, `03`...)
+- `evidence-name`: the value from `[EVIDENCE: name]`
+- `ext`: `.txt` for plain output, `.json` for structured data
+
+Example:
+
+```text
+evidence/
+  01-health-check.json
+  02-schema-after-migration.txt
+  03-rate-limit-response.txt
+  comment.txt
+  code-blocks.md
+```
+
+### Step 4: Generate Evidence Comment + Code Blocks
+
+After capturing all evidence, build:
+
+- `evidence/comment.txt` — human-readable summary of the verification (Linear comment body, markdown-supported)
+- `evidence/code-blocks.md` — fenced code blocks containing the captured evidence outputs (appended below `comment.txt` inside a `<details>` block)
+
+### Step 5: Post Evidence
+
+Invoke `lisa:linear-evidence` with `<IDENTIFIER> ./evidence` to:
+
+1. Upload large evidence files to the GitHub `pr-assets` release (if files present in `evidence/files/`).
+2. Update the GitHub PR description with an Evidence section (when a PR is open).
+3. Post the Linear comment (`comment.txt` + collapsible `code-blocks.md`).
+4. Transition labels: remove `status:in-progress`, add `status:code-review`.
+
+### Step 6: Verify
+
+Confirm:
+- Evidence appears as a comment on the Linear Issue.
+- The PR description shows the Evidence section.
+- The Issue's `status:*` label transitioned to `code-review`.
+
+## Verification Patterns Reference
+
+Use patterns from the project's `verification.md`:
+
+| Change Type | Verification Method | Evidence Format |
+|---|---|---|
+| API endpoint | `curl -s localhost:PORT/endpoint` | JSON response |
+| Database migration | `psql -c "\d table"` or migration output | Schema text |
+| Background job | Trigger + check state | Log output |
+| Library / utility | `bun run test -- path/to/test` | Test output |
+| Security fix | Reproduce + verify fix | Request / response |
+| Auth/authz | Multi-role verification | Status codes per role |
+| UI / frontend | Playwright `browser_*` MCP tools | Screenshot + DOM |
+
+## Troubleshooting
+
+### Evidence file is empty
+
+Ensure the command succeeded and produced output. Use `2>&1` to capture both stdout and stderr.
+
+### Parser returns no steps
+
+The Issue may not have a Validation Journey section. Run `/linear-add-journey <IDENTIFIER>` to add one.
+
+### Label transition fails
+
+Ensure `status:in-progress` and `status:code-review` exist on the team. `lisa:linear-evidence` creates them on demand if missing.

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

@@ -1,6 +1,6 @@
 ---
 name: linear-prd-intake
-description: "Scans a Linear workspace (or a specific team) for projects labelled `prd-ready` and runs each one through the dry-run validation pipeline. Projects that pass every gate get tickets written and the label flipped to `prd-ticketed`; projects that fail get clarifying-question comments (on a sentinel feedback issue under the project) and the label flipped to `prd-blocked`. Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (linear-to-tracker, tracker-validate, jira-source-artifacts, product-walkthrough)."
+description: "Scans a Linear workspace (or a specific team) for projects labelled `prd-ready` and runs each one through the dry-run validation pipeline. Projects that pass every gate get tickets written and the label flipped to `prd-ticketed`; projects that fail get clarifying-question comments (on a sentinel feedback issue under the project) and the label flipped to `prd-blocked`. Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (linear-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough)."
 allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_teams"]
 ---
 
@@ -10,7 +10,7 @@ allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_projects", "mcp__line
 
 - A Linear **workspace** URL — scans every project in the workspace whose labels include `prd-ready`. Example: `https://linear.app/acme`.
 - A Linear **team** URL or team key — scans every project on the team whose labels include `prd-ready`. Example: `https://linear.app/acme/team/ENG/projects` or bare `ENG`.
-- The literal token `linear` — equivalent to "the default Linear workspace"; only valid if `LINEAR_WORKSPACE` is configured.
+- The literal token `linear` — equivalent to "the default Linear workspace"; only valid if `linear.workspace` is configured in `.lisa.config.json`.
 
 Run one intake cycle against that scope. Each project with the `prd-ready` label is claimed, validated, and routed to either `prd-blocked` (with clarifying comments on a sentinel feedback issue) or `prd-ticketed` (with JIRA tickets created).
 
@@ -29,7 +29,7 @@ Specifically forbidden:
 
 The only legitimate reasons to stop early:
 
-- Missing scope argument or required configuration (`JIRA_PROJECT`, `JIRA_SERVER`, `LINEAR_WORKSPACE`, `E2E_BASE_URL`, etc.). Surface the missing key(s) and exit this cycle — never invent values.
+- Missing scope argument or required configuration (`linear.workspace` in `.lisa.config.json`, `E2E_BASE_URL`, etc.). Surface the missing key(s) and exit this cycle — never invent values.
 - Workspace/team unreachable, or the labelling convention not yet adopted (no projects carry any of `prd-ready` / `prd-in-review` / `prd-blocked` / `prd-ticketed`). Surface and exit.
 - Empty `prd-ready` set. Exit cleanly with `"No Linear projects labelled prd-ready. Nothing to do."`
 
@@ -63,7 +63,7 @@ If the project does not yet use `prd-*` labels, this skill cannot run. Adopting
    - Workspace URL (`https://linear.app/<workspace>`) → extract workspace slug; the scope is the entire workspace.
    - Team URL containing `/team/<KEY>/...` → extract team key; the scope is that team.
    - Bare team key → use as-is; the scope is that team.
-   - The literal `linear` → fall back to `LINEAR_WORKSPACE` env var; error if not set.
+   - The literal `linear` → fall back to `linear.workspace` from `.lisa.config.json`; error if not set.
 2. Verify the scope is reachable:
    - For a workspace: call `mcp__linear-server__list_teams` and confirm at least one team is returned (non-empty workspaces are readable; empty results indicate auth or workspace-mismatch).
    - For a team: call `mcp__linear-server__list_teams({query: <KEY>})` and confirm the team resolves.
@@ -106,7 +106,7 @@ Invoke the `lisa:linear-to-tracker` skill with `dry_run: true` and the project's
 - 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:linear-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:linear-to-tracker` calls per ticket.
 
 #### 3c. Branch on the verdict
 
@@ -250,7 +250,12 @@ Idempotency: the helper finds-or-creates. Re-runs of the cycle reuse the same se
 
 ## Configuration
 
-Same env vars as `lisa:linear-to-tracker` — `JIRA_PROJECT`, `JIRA_SERVER`, `LINEAR_WORKSPACE`, `E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL`. If any required value is missing, surface the missing key(s) and exit this cycle — never invent values.
+Same configuration as `lisa:linear-to-tracker`. See that skill for the full table. Key items:
+
+- **From `.lisa.config.json`**: `linear.workspace` (required for Linear MCP). When the destination tracker is `linear`, also `linear.teamKey`.
+- **From environment variables**: `E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL` (operational E2E test config).
+
+Destination tracker config (jira / github / linear) is consumed by `lisa:tracker-write` internally — this skill does NOT read it. If any required value is missing, surface the missing key(s) and exit this cycle — never invent values.
 
 ## Rules