@codyswann/lisa 2.10.1 → 2.11.1

package/README.md

@@ -12,9 +12,9 @@ A request to fix a bug routes to a different flow than a request to build a feat
 
 ### Flows and Agents
 
-A flow is a pipeline. Each step in the pipeline is an **agent** — a scoped AI with specific tools and skills. One agent investigates git history, another reproduces bugs, another writes code, another verifies the result.
+A flow is a pipeline. Each step in the pipeline is an **agent** — a scoped AI with specific tools and instructions. One agent investigates git history, another reproduces bugs, another writes code, another verifies the result.
 
-Agents delegate domain-specific work to **skills** — reusable instruction sets that can be invoked by agents, by slash commands, or by CI workflows. The same skill that triages a JIRA ticket interactively is the same skill invoked by the nightly triage workflow.
+Behind the scenes, agents delegate domain-specific work to reusable instruction sets that are loaded automatically when a command runs. The same logic that triages a JIRA ticket interactively is the same logic invoked by the nightly triage workflow — you don't need to know which one is running.
 
 Flows can nest. A build flow includes a verification sub-flow, which includes a ship sub-flow. This composition keeps each flow focused while enabling complex end-to-end workflows.
 
@@ -28,13 +28,13 @@ Lisa enforces quality through layered gates:
 
 ### Location Agnostic
 
-The same rules, skills, and quality gates apply everywhere:
+The same rules, workflows, and quality gates apply everywhere:
 
 - On a developer's workstation running Claude Code interactively
 - In a GitHub Action running a nightly improvement job
 - In a CI workflow responding to a PR review comment
 
-The analytical logic lives in skills. The enforcement lives in hooks and rules. The orchestration adapts to context — using MCP integrations locally and REST APIs in CI — but the standards don't change.
+The orchestration adapts to context — using MCP integrations locally and REST APIs in CI — but the standards don't change.
 
 ### Template Governance
 
@@ -44,7 +44,7 @@ Lisa distributes its standards to downstream projects as templates. When a proje
 - Test and coverage infrastructure
 - CI/CD workflows
 - Git hooks
-- AI agent definitions, skills, and rules
+- AI agent definitions and project rules
 
 Templates follow governance rules: some files are overwritten on every update (enforced standards), some are created once and left alone (project customization), and some are merged (shared defaults with project additions).
 
@@ -58,15 +58,66 @@ curl -fsSL https://claude.ai/install.sh | bash
 
 ## Working With Lisa
 
-> Ask Claude: "I have JIRA ticket [TICKET-ID]. Research, plan, and implement it."
+Lisa exposes a small set of top-level commands that map to the work lifecycle. Run them in Claude Code; everything underneath — agents, sub-flows, and the supporting libraries that power each step — happens automatically.
 
-Or use slash commands directly:
+### The Lifecycle
 
-- `/fix` — route through the bug fix flow
-- `/build` — route through the feature build flow
-- `/improve` — route through the improvement flow
-- `/investigate` — route through the investigation flow
-- `/jira:triage <TICKET-ID>` — analytical triage gate: detect ambiguities, edge cases, and verification methodology
-- `/plan:improve-tests <target>` — improve test quality by analyzing and strengthening weak or brittle tests
+A piece of work moves through five stages. Each stage has one command.
 
-> Ask Claude: "What commands are available?"
+| Stage | Command | What it does |
+| --- | --- | --- |
+| Research | `/lisa:research <problem>` | Investigates the codebase and problem space, then produces a PRD ready for planning. |
+| Plan | `/lisa:plan <PRD>` | Decomposes a PRD into ordered work items in your tracker (JIRA, GitHub Issues, or Linear). |
+| Implement | `/lisa:implement <ticket>` | Takes one work item from spec to shipped: assembles an agent team, runs the build, opens a PR, handles review, merges. |
+| Verify | `/lisa:verify` | Commits, pushes, opens a PR, monitors deploy, and verifies behavior in the target environment. Folded into `/lisa:implement` but available standalone. |
+| Debrief | `/lisa:debrief <epic>` | After shipping, mines tickets and PRs to surface edge cases, gotchas, and friction. Produces a triage doc; `/lisa:debrief:apply` persists accepted learnings. |
+
+Most users only ever call `/lisa:research`, `/lisa:plan`, and `/lisa:implement`. The rest run automatically as sub-flows.
+
+### Batch and Scheduled Work
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:intake <queue-url>` | Scans a Ready queue (Notion PRD database, JIRA project, GitHub repo, Linear team, Confluence space) and dispatches each item through the right lifecycle command. Designed as the cron target for unattended runs. |
+
+### Maintenance and Operations
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:monitor [environment]` | Checks application health, logs, error rates, and performance for the named environment. |
+| `/lisa:product-walkthrough <route>` | Walks the live product through a real browser to ground PRD or ticket reasoning in current behavior. |
+| `/lisa:codify-verification <type> <what>` | Converts a passing manual verification into a regression test in the appropriate framework (Playwright, integration test, benchmark). Runs automatically after `/lisa:verify`. |
+| `/lisa:review:local` | Reviews local branch changes against `main`. |
+| `/lisa:pull-request:review <pr-url>` | Pulls down review comments on a PR and implements the valid ones. |
+| `/lisa:security:zap-scan` | Runs an OWASP ZAP baseline scan against the local app. |
+
+### Targeted Improvements
+
+These commands tighten a specific quality threshold and fix every violation in one pass — useful for incremental hardening or nightly jobs.
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:improve:test-coverage <pct>` | Raises coverage to the target percentage by adding tests for uncovered code. |
+| `/lisa:improve:tests <target>` | Strengthens weak, brittle, or poorly-written tests. |
+| `/lisa:improve:code-complexity` | Lowers the cognitive-complexity threshold by 2 and fixes resulting violations. |
+| `/lisa:improve:max-lines <n>` | Reduces the max-file-lines threshold and fixes violations. |
+| `/lisa:improve:max-lines-per-function <n>` | Reduces the max-lines-per-function threshold and fixes violations. |
+| `/lisa:fix:linter-error <rule> [...]` | Fixes every violation of one or more ESLint rules across the codebase. |
+
+### Git Helpers
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:git:commit [hint]` | Creates conventional commits from the current changes. |
+| `/lisa:git:submit-pr [hint]` | Pushes and opens or updates a PR. |
+| `/lisa:git:prune` | Prunes local branches whose remotes have been deleted. |
+
+### Talking to Lisa in Plain English
+
+You don't have to remember any of this. Tell Claude what you want and the right command will run:
+
+> "I have JIRA ticket PROJ-1234. Research, plan, and implement it."
+> "Walk through the checkout flow and tell me what's broken."
+> "Get test coverage to 90%."
+
+> Ask Claude: "What commands are available?" for the full list at any time.

package/package.json

@@ -79,7 +79,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.10.1",
+  "version": "2.11.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.10.1",
+  "version": "2.11.1",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/agents/confluence-prd-intake.md

@@ -5,7 +5,7 @@ skills:
   - confluence-prd-intake
   - confluence-to-tracker
   - tracker-validate
-  - jira-source-artifacts
+  - tracker-source-artifacts
   - product-walkthrough
   - tracker-write
   - prd-ticket-coverage

package/plugins/lisa/agents/github-prd-intake.md

@@ -1,11 +1,11 @@
 ---
 name: github-prd-intake
-description: PRD intake agent for GitHub Issues hosted PRDs. Runs one intake cycle against a GitHub repository — claims `prd-ready` issues (relabels to `prd-in-review`), validates each through the dry-run pipeline, and routes to `prd-blocked` (with clarifying comments on the PRD issue) or `prd-ticketed` (with destination tickets created in JIRA or GitHub Issues per .lisa.config.json). GitHub counterpart of `notion-prd-intake`, `confluence-prd-intake`, and `linear-prd-intake`. Designed to be invoked manually via /github-prd-intake or autonomously via a scheduled cron.
+description: PRD intake agent for GitHub Issues hosted PRDs. Runs one intake cycle against a GitHub repository — claims `prd-ready` issues (relabels to `prd-in-review`), validates each through the dry-run pipeline, and routes to `prd-blocked` (with clarifying comments on the PRD issue) or `prd-ticketed` (with destination tickets created in JIRA, GitHub Issues, or Linear per .lisa.config.json). GitHub counterpart of `notion-prd-intake`, `confluence-prd-intake`, and `linear-prd-intake`. Designed to be invoked manually via /github-prd-intake or autonomously via a scheduled cron.
 skills:
   - github-prd-intake
   - github-to-tracker
   - tracker-validate
-  - jira-source-artifacts
+  - tracker-source-artifacts
   - product-walkthrough
   - tracker-write
   - prd-ticket-coverage

package/plugins/lisa/agents/linear-agent.md

@@ -0,0 +1,128 @@
+---
+name: linear-agent
+description: Linear lifecycle agent. Reads Issues, determines intent (Bug → Implement/Fix, Story/Task → Implement/Build, Epic Project → Plan, Spike → Implement/Investigate), delegates to the appropriate flow, syncs progress at milestones, and posts evidence at completion. Linear counterpart of jira-agent and github-agent.
+skills:
+  - linear-read-issue
+  - linear-write-issue
+  - linear-sync
+  - linear-evidence
+  - linear-verify
+  - linear-add-journey
+  - ticket-triage
+---
+
+# Linear Agent
+
+You are a Linear lifecycle agent. Your job is to read a Linear work item, determine what kind of work it represents, delegate to the appropriate flow, and keep the item in sync throughout.
+
+## Workflow
+
+### 1. Read the Item
+
+Invoke the `linear-read-issue` skill with the identifier. This is mandatory — do NOT read the item ad-hoc via MCP calls. The skill fetches the primary item AND its full graph in one pass:
+
+- Full description, acceptance criteria, Validation Journey
+- All comments in chronological order (with thread structure)
+- All metadata (state, priority, assignee, labels, project, parent, cycle, milestone, estimate)
+- Attachments — PRs (with state and unresolved review comments via `gh`), Confluence pages, dashboards
+- Every native relation (`blocks`, `blocked_by`, `relates_to`, `duplicates`) with descriptions, states, recent comments
+- Project parent (Epic-equivalent) — full description, comments, milestones, attached documents
+- Project siblings — so you see in-flight related work before starting
+- Sub-Issues
+
+Pass the resulting context bundle verbatim to every downstream agent. Extract credentials, URLs, and reproduction steps from the bundle. If the skill reports the item is inaccessible, stop and report what access is needed.
+
+**Never act on an item in isolation.** If the bundle shows open blockers, flag them and stop. If it shows a Project sibling in progress with a different assignee, surface that before proceeding so work isn't duplicated.
+
+### 2. Validate Item Quality (Pre-flight Gate)
+
+Use the `linear-verify` skill to check the item against organizational standards:
+- Project parent exists (Stories under Epic), parent Issue exists (Sub-tasks under Story)
+- Description quality (audience sections, Gherkin acceptance criteria)
+- Validation Journey present (runtime-behavior items)
+- Target backend environment named in description (runtime-behavior items)
+- Sign-in credentials named in description (when item touches authenticated surfaces)
+- Single-repo scope (Bug / Task / Sub-task)
+- Relationship discovery (≥1 relation or documented git + Linear search)
+
+**Gating behavior — this is the one place auto-transitioning is allowed:**
+
+If `linear-verify` returns `FAIL` on any of the above, do NOT continue:
+1. Update labels via `mcp__linear-server__save_issue`: remove the current `status:*` label, add `status:blocked`. (Create `status:blocked` via `create_issue_label` if needed.)
+2. Reassign the item to the **Issue creator** (the human who filed it — Linear's `creator` field).
+3. Post a comment via `mcp__linear-server__save_comment` listing each missing requirement with a one-line remediation. Prefix with `[{repo}]`.
+4. Stop. Do not run triage, do not delegate to a flow, do not start work.
+
+If `linear-verify` returns `PASS`, proceed to Step 3.
+
+### 3. Analytical Triage Gate
+
+Determine the repo name: `basename $(git rev-parse --show-toplevel)`
+
+Check if the item already has the `claude-triaged-{repo}` label. If yes, skip to Step 4.
+
+If not triaged:
+1. Fetch the full item details from the context bundle.
+2. Invoke the `ticket-triage` skill with the item details.
+3. Post the skill's findings (ambiguities, edge cases, verification methodology) as comments via `save_comment`. Prefix all comments with `[{repo}]`.
+4. Add the `claude-triaged-{repo}` label via `save_issue` (creating it via `create_issue_label` if missing).
+
+**Gating behavior:**
+- `BLOCKED` (ambiguities found): post the ambiguities; do NOT proceed. Report to the human: "This item has unresolved ambiguities. Triage posted findings as comments. Please resolve and retry."
+- `NOT_RELEVANT`: add the label and report "Item is not relevant to this repository."
+- `PASSED` or `PASSED_WITH_FINDINGS`: proceed to Step 4.
+
+### 4. Determine Intent
+
+Map the item to a flow:
+
+| Item kind | Flow | Work Type |
+|-----------|------|-----------|
+| Project (Epic) | Plan | -- |
+| Story Issue (with `projectId`) | Implement | Build |
+| Task Issue | Implement | Build |
+| Bug Issue | Implement | Fix |
+| Spike Issue | Implement | Investigate Only |
+| Improvement Issue | Implement | Improve |
+| Sub-Issue | Implement | Same as parent's work type |
+
+Linear doesn't have a single "issue type" field like JIRA — type is typically encoded as a label (`type:story`, `type:bug`) or inferred from the description. If the type is ambiguous, read the description to classify. A "Task" describing broken behavior is a Fix; a "Bug" requesting new functionality is a Build.
+
+### 5. Delegate to Flow
+
+Hand off to the appropriate flow as defined in the `intent-routing` rule. Pass the full item context (description, acceptance criteria, credentials, reproduction steps) to the first agent in the flow.
+
+### 6. Sync Progress at Milestones
+
+Use the `linear-sync` skill to update the item at these milestones:
+- **Plan created** — post plan summary, branch name
+- **Implementation started** — post task completion progress
+- **PR ready** — post PR link, summary of changes
+- **PR merged** — post final summary
+
+### 7. Post Evidence at Completion
+
+Use the `linear-evidence` skill to:
+- Upload verification evidence to the GitHub PR
+- Post evidence summary as a Linear comment
+- Transition labels: remove `status:in-progress`, add `status:code-review`
+
+### 8. Suggest Status Transition
+
+Based on the milestone, suggest (but don't auto-transition the native Linear `state`):
+
+| Milestone | Suggested label transition |
+|-----------|---------------------------|
+| Plan created | `status:in-progress` |
+| PR ready | `status:code-review` |
+| PR merged | `status:on-dev` (build-intake will perform if dispatched via that flow) |
+
+The label transitions ARE the canonical signal. The native `state` field stays as the human / triage decision.
+
+## Rules
+
+- Never auto-transition the native Linear `state`, with one explicit exception: when `linear-verify` returns `FAIL` for the pre-flight gate (Step 2), update labels to `status:blocked` and reassign to the creator. Every other status change remains a label-driven suggestion.
+- Always read the full item graph via `linear-read-issue` before determining intent — don't rely on type labels alone.
+- Never create or materially edit an item by calling MCP write tools directly — always delegate to `linear-write-issue` so relationships, Gherkin criteria, and metadata gates are enforced. Two explicit exceptions are permitted: (1) the Step 2 pre-flight failure path (when `linear-verify` returns `FAIL`) may call `mcp__linear-server__save_issue` and `mcp__linear-server__save_comment` directly to set `status:blocked` and reassign to the creator — this narrow exception is already granted by the rule above; (2) the Step 3 triage path may call `mcp__linear-server__save_comment` to post triage findings and `mcp__linear-server__save_issue` to add the `claude-triaged-{repo}` label — these are lightweight metadata updates that do not create or materially edit ticket content and therefore do not need to route through `linear-write-issue`.
+- If sign-in credentials are in the item, extract and pass them to the flow. If the item touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.
+- If the item has a Validation Journey section, pass it to the verifier agent. The Validation Journey's local-verification step must point at the target backend environment named in the description.

package/plugins/lisa/agents/linear-build-intake.md

@@ -0,0 +1,62 @@
+---
+name: linear-build-intake
+description: Linear build-intake agent. Runs one build-intake cycle against a Linear team — claims status:ready Issues, dispatches each to the linear-agent build flow, relabels to status:on-dev on success. Symmetric counterpart of jira-build-intake and github-build-intake. Designed to be invoked manually via /linear-build-intake or autonomously via a scheduled cron.
+skills:
+  - linear-build-intake
+  - linear-read-issue
+  - linear-verify
+  - linear-validate-issue
+  - linear-write-issue
+  - linear-sync
+  - linear-evidence
+  - linear-add-journey
+  - ticket-triage
+---
+
+# Linear Build Intake Agent
+
+You are a Linear build-intake agent. Your single job is to run one cycle against a Linear team — find `status:ready` Issues, dispatch each through the build flow, relabel successful builds to `status:on-dev` — then report what happened.
+
+## Confirmation policy
+
+Once you have a team key, RUN. Do not ask the caller whether to proceed, do not preview projected scope (Issue counts, PR counts, build estimates), do not offer "proceed / skip / dry-run" choices. The caller has already authorized the run by invoking you. The pre-flight `status:blocked` outcome owned by `linear-agent` is a valid terminal state of the per-Issue lifecycle, not a failure mode — large queues and complex Issues are exactly what this skill is for. The `linear-build-intake` skill defines the only legitimate early-exit conditions (missing query, label convention not adopted, empty Ready set); ask only when one of those applies.
+
+## Workflow
+
+### 1. Receive the query
+
+The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear team key (e.g. `ENG`) or the literal token `linear` (which falls back to `linear.teamKey` in `.lisa.config.json`). You do not pick the team yourself.
+
+If no query is provided AND no `linear.teamKey` is configured, stop and ask. Never run intake against a default scope without explicit configuration — the side effects (label transitions, PRs opened, builds running) are too high to act without an explicit target.
+
+### 2. Run the intake skill
+
+Invoke the `linear-build-intake` skill with the query as `$ARGUMENTS`. The skill owns the cycle logic — Linear MCP queries, claim, dispatch to `linear-agent`, transition on success, summary. Do not duplicate that logic here.
+
+The skill in turn invokes `linear-agent` per Issue, which owns the per-Issue lifecycle (read full graph, verify, triage, route to flow, sync progress, post evidence). You do not call `linear-agent` directly — the intake skill does.
+
+### 3. Surface the summary
+
+Pass the skill's summary block through to the caller verbatim. The caller needs the structured record:
+
+- Total processed
+- Per-Issue outcomes (`status:on-dev` → which PR; `status:blocked` by verify → which gate; `Held` by triage → which ambiguities; Errors → reason)
+- PR count
+
+If the cycle errored before processing any Issues (e.g. label convention not adopted — `status:ready` doesn't exist on the team), surface the cause in plain language and stop. Do NOT attempt to invent labels.
+
+### 4. Suggest next actions when warranted
+
+After a successful cycle, if any Issues ended at `status:on-dev`, mention that the next phase (QA, deploy, or downstream verification) is owned by humans or a future intake skill. This skill does not own anything past `status:on-dev`.
+
+If any Issues ended at `status:blocked` (pre-flight verify failed) or `Held` (triage found ambiguities), point that out so the caller knows which Issues need human attention before they can be re-claimed. The `status:blocked` ones were transitioned by `linear-agent`'s gate logic — that is correct and expected.
+
+## Rules
+
+- **Never run a cycle without an explicit query or configured `linear.teamKey`.** Side effects too high to default.
+- **Never modify the lifecycle**: only `status:ready → status:in-progress → status:on-dev`. Never touch `status:done`, `status:blocked` (owned by `linear-agent`), or any other label. (Exception: `status:code-review` is set by `linear-evidence` mid-flow — that's not your concern.)
+- **Never bypass `linear-agent` to do build work directly.** The intake skill dispatches; `linear-agent` builds. Skipping the dispatch produces broken work.
+- **Never invent labels.** If a team's labels aren't adopted yet, the skill exits with an adoption hint. Don't guess label names.
+- **Never start a second cycle while one is in flight against an overlapping team.** Serial execution. Scheduling layer (when added) is responsible for not double-firing.
+- **Stop and surface failures rather than retry-loop.** If `linear-agent` returns an unexpected response or an error, the skill records it under "Errors" — pass that through. Do not auto-retry.
+- **Pre-flight failures are not your problem to fix.** If an Issue fails `linear-verify` (missing Validation Journey, sign-in, etc.), `linear-agent` transitions it to `status:blocked` and reassigns to the creator. Surface the count and move on. Do NOT try to add the missing pieces from this agent.

package/plugins/lisa/agents/linear-prd-intake.md

@@ -5,7 +5,7 @@ skills:
   - linear-prd-intake
   - linear-to-tracker
   - tracker-validate
-  - jira-source-artifacts
+  - tracker-source-artifacts
   - product-walkthrough
   - tracker-write
   - prd-ticket-coverage
@@ -25,7 +25,7 @@ Once you have a workspace or team scope, RUN. Do not ask the caller whether to p
 
 ### 1. Receive the scope URL or key
 
-The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear workspace URL, a team URL, a bare team key, or the literal token `linear` (which falls back to `LINEAR_WORKSPACE`). You do not pick the scope yourself.
+The invoking caller (a slash command, a scheduled cron, or a parent agent) hands you a Linear workspace URL, a team URL, a bare team key, or the literal token `linear` (which falls back to `linear.workspace` in `.lisa.config.json`). You do not pick the scope yourself.
 
 If no scope is provided, stop and ask. Never run intake against a default or guessed scope — the side effects (label changes, sentinel-issue creation, JIRA tickets created) are too high to act without an explicit target.
 

package/plugins/lisa/agents/notion-prd-intake.md

@@ -5,7 +5,7 @@ skills:
   - notion-prd-intake
   - notion-to-tracker
   - tracker-validate
-  - jira-source-artifacts
+  - tracker-source-artifacts
   - product-walkthrough
   - tracker-write
   - prd-ticket-coverage

package/plugins/lisa/commands/plan.md

@@ -1,5 +1,5 @@
 ---
-description: "Plan work from a single PRD or specification. Decomposes into ordered work items in the configured tracker (JIRA or GitHub Issues per .lisa.config.json). Source can be a Notion / Confluence / Linear / GitHub Issue URL, a JIRA epic key, a markdown file, or a free-form description. For batch scanning of all Ready PRDs in a queue, use /lisa:intake instead."
+description: "Plan work from a single PRD or specification. Decomposes into ordered work items in the configured tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json). Source can be a Notion / Confluence / Linear / GitHub Issue URL, a JIRA epic key, a markdown file, or a free-form description. For batch scanning of all Ready PRDs in a queue, use /lisa:intake instead."
 argument-hint: "<single-PRD-url | GitHub-issue-url | @file | ticket-id-or-url | description>"
 ---
 

package/plugins/lisa/rules/config-resolution.md

@@ -0,0 +1,187 @@
+# Config Resolution
+
+Lisa is vendor-agnostic. PRDs can be sourced from Notion, Confluence, Linear, GitHub Issues, or JIRA. Tickets can be written to JIRA, GitHub Issues, or Linear. Per-project configuration lives in `.lisa.config.json` at the repo root, with optional `.lisa.config.local.json` overriding on a per-key basis.
+
+This rule is the single source of truth for the `.lisa.config.json` schema, the resolution algorithm, and the dispatch tables every vendor-neutral skill follows.
+
+## File location and precedence
+
+Read configuration from the repo root in this order:
+
+1. `.lisa.config.local.json` — gitignored, per-developer overrides (e.g., a developer running with a different destination tracker for one branch).
+2. `.lisa.config.json` — committed, project-wide settings.
+
+Local overrides global on a **per-key basis**: missing keys in `.lisa.config.local.json` fall through to `.lisa.config.json`. Use `jq` from Bash for all reads — never hand-parse JSON.
+
+A typical Bash read:
+
+```bash
+local_value=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+global_value=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+tracker="${local_value:-${global_value:-jira}}"
+```
+
+## Schema
+
+```json
+{
+  "tracker": "jira",
+  "source":  "notion",
+
+  "atlassian":  { "cloudId": "<uuid>" },
+  "jira":       { "project": "<KEY>" },
+  "confluence": { "spaceKey": "<KEY>", "parentPageId": "<id>" },
+  "github":     { "org": "<org-or-user>", "repo": "<repo>" },
+  "notion":     { "prdDatabaseId": "<uuid>", "statusProperty": "Status", "readyValue": "Ready" },
+  "linear":     { "workspace": "<workspace-slug>", "teamKey": "<TEAM>" }
+}
+```
+
+### Top-level fields
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `tracker` | no | `"jira"` | Destination for ticket writes. One of `"jira"`, `"github"`, `"linear"`. Missing key resolves to `"jira"` for back-compat. |
+| `source` | no | — | Default PRD source for batch skills (`/lisa:intake`) and arg-less single-PRD skills. One of `"notion"`, `"confluence"`, `"linear"`, `"github"`, `"jira"`. Explicit URLs/keys passed to a skill always win over `source`; this is a default, not a lock. |
+
+### Vendor sections
+
+Each vendor section is **conditionally required**: required only when that vendor is referenced as `tracker`, as `source`, or by an explicit invocation. Skills validate their own required keys at entry and stop with a clear error if missing — never invent values.
+
+#### `atlassian`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `atlassian.cloudId` | `tracker = "jira"`, `source = "jira"`, `source = "confluence"`, or any `confluence-*` / `jira-*` skill is invoked | Atlassian Cloud site UUID. Resolve once via the Atlassian MCP `getAccessibleAtlassianResources` and paste in. Shared between JIRA and Confluence (same Atlassian site). If a project ever needs separate sites for JIRA vs Confluence, override via `jira.cloudId` / `confluence.cloudId` (not currently implemented — file an issue). |
+
+#### `jira`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `jira.project` | `tracker = "jira"` or any `jira-*` skill is invoked | JIRA project key (e.g. `SE`, `ENG`). |
+
+#### `confluence`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `confluence.spaceKey` | `source = "confluence"` and `parentPageId` is not set | Confluence space key (e.g. `ENG`). |
+| `confluence.parentPageId` | `source = "confluence"` and `spaceKey` is not set | Confluence parent page ID. Either `spaceKey` or `parentPageId` must be set; both is allowed (parent page ID narrows the scope). |
+
+#### `github`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `github.org` | `tracker = "github"` or `source = "github"` or any `github-*` skill is invoked | GitHub organization or user name. |
+| `github.repo` | same as above | GitHub repository name. |
+
+When `tracker = "github"` AND `source = "github"` (self-host), both reads and writes hit the same GitHub repo. Label namespaces are kept separate so the two flows don't collide — see "Self-host edge case" below.
+
+#### `notion`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `notion.prdDatabaseId` | `source = "notion"` | Notion database ID (UUID, dashes optional). The database is the PRD queue. |
+| `notion.statusProperty` | `source = "notion"` | Name of the database property that drives the lifecycle. Defaults to `"Status"` if absent. |
+| `notion.readyValue` | `source = "notion"` | Status value that means "ready for ticketing". Defaults to `"Ready"` if absent. The full lifecycle (Ready → In Review → Blocked / Ticketed → Shipped) is hardcoded; only the entry-point value name is configurable for now. |
+
+#### `linear`
+
+| Field | Required when | Notes |
+|-------|---------------|-------|
+| `linear.workspace` | `tracker = "linear"`, `source = "linear"`, or any `linear-*` skill is invoked | Linear workspace slug (e.g. `acme`). |
+| `linear.teamKey` | `tracker = "linear"` | Linear team key (e.g. `ENG`). The team owns the destination Issues. For source mode, projects are workspace-scoped or team-scoped per the URL passed. |
+
+## Resolution algorithm
+
+Every `tracker-*` shim and every vendor-neutral caller follows this:
+
+1. Read `.lisa.config.local.json` first (if present), then `.lisa.config.json`. Local overrides global on a per-key basis. Use `jq` — never hand-parse JSON.
+2. Extract the `tracker` field. If missing or null, default to `"jira"`.
+3. Dispatch:
+   - `tracker = "jira"` → delegate to the matching `jira-*` skill. Validate `atlassian.cloudId` and `jira.project` are present.
+   - `tracker = "github"` → delegate to the matching `github-*` skill. Validate `github.org` and `github.repo` are present.
+   - `tracker = "linear"` → delegate to the matching `linear-*` skill. Validate `linear.workspace` and `linear.teamKey` are present.
+4. Any other value: stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+For batch skills that consume `source`:
+
+1. If `$ARGUMENTS` contains an explicit URL or key, parse the source vendor from it (always wins).
+2. If `$ARGUMENTS` is the bare token `notion` / `confluence` / `linear` / `github` / `jira`, the source is that vendor; resolve location from the corresponding config section.
+3. If `$ARGUMENTS` is empty, fall back to `source` from config; if that's also empty, stop and report `"No source specified and no 'source' field in .lisa.config.json."`
+
+## Skill mapping
+
+The shim → vendor mapping is fixed:
+
+| Shim | jira tracker | github tracker | linear tracker |
+|------|--------------|----------------|----------------|
+| `lisa:tracker-write` | `lisa:jira-write-ticket` | `lisa:github-write-issue` | `lisa:linear-write-issue` |
+| `lisa:tracker-validate` | `lisa:jira-validate-ticket` | `lisa:github-validate-issue` | `lisa:linear-validate-issue` |
+| `lisa:tracker-verify` | `lisa:jira-verify` | `lisa:github-verify` | `lisa:linear-verify` |
+| `lisa:tracker-read` | `lisa:jira-read-ticket` | `lisa:github-read-issue` | `lisa:linear-read-issue` |
+| `lisa:tracker-evidence` | `lisa:jira-evidence` | `lisa:github-evidence` | `lisa:linear-evidence` |
+| `lisa:tracker-sync` | `lisa:jira-sync` | `lisa:github-sync` | `lisa:linear-sync` |
+| `lisa:tracker-add-journey` | `lisa:jira-add-journey` | `lisa:github-add-journey` | `lisa:linear-add-journey` |
+| `lisa:tracker-journey` | `lisa:jira-journey` | `lisa:github-journey` | `lisa:linear-journey` |
+| `lisa:tracker-create` | `lisa:jira-create` | `lisa:github-create` | `lisa:linear-create` |
+| `lisa:tracker-build-intake` | `lisa:jira-build-intake` | `lisa:github-build-intake` | `lisa:linear-build-intake` |
+
+The `tracker-source-artifacts` skill (formerly `tracker-source-artifacts`) is read-only and vendor-neutral — it has no shim and is invoked directly by every `*-to-tracker` skill and every destination write skill (`jira-write-ticket`, `github-write-issue`, `linear-write-issue`).
+
+## Caller responsibilities
+
+- **PRD-source skills** (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST invoke `tracker-write` and `tracker-validate` — never `jira-write-ticket` / `github-write-issue` / `linear-write-issue` directly. This is what makes a project's destination switchable via config.
+- **Lifecycle skills** (`implement`, `verify`, `monitor`) MUST invoke `tracker-read`, `tracker-evidence`, `tracker-sync` for ticket interaction — never the vendor-specific equivalents.
+- **Per-vendor PRD intake skills** (`notion-prd-intake`, `confluence-prd-intake`, `linear-prd-intake`, `github-prd-intake`) compose the PRD-source skills (which in turn invoke the shims) — they do not need to read `tracker` themselves.
+- **Vendor-specific destination skills** (`jira-*`, `github-*`, `linear-*`) read their own vendor config section directly. They do NOT consult `tracker` — they are the targets of dispatch, not the dispatchers.
+
+## Linear destination semantics (best practices)
+
+Linear's data model differs from JIRA / GitHub. The destination mapping follows Linear's recommended patterns:
+
+| Concept (JIRA / GitHub) | Linear equivalent | Linear MCP write |
+|---|---|---|
+| Epic | **Project** (with milestones, target dates, lead, state) | `save_project` |
+| Story | **Issue** with `projectId` set, no `parentId` | `save_issue` |
+| Sub-task | **Sub-issue** with `parentId` = Story issue ID | `save_issue` |
+| Fix version | Linear **ProjectMilestone** (native, dated) | `save_project` (milestones array) |
+| Priority | Native `priority` field (0=No, 1=Urgent, 2=High, 3=Medium, 4=Low) | issue field |
+| Estimate / story points | Native `estimate` field | issue field |
+| Status workflow | **Labels** (`status:ready`, `status:in-progress`, `status:on-dev`, `status:done`) — portable across teams | issue labels |
+| Component | Label prefix `component:` | issue labels |
+| Issue links (blocks / relates / duplicates) | Native Linear relations | `save_issue_relation` |
+
+`linear-write-issue` is **polymorphic**: dispatches internally on `issue_type` (Epic → `save_project`, Story / Sub-task → `save_issue`). Parity with `jira-write-ticket` / `github-write-issue` is preserved at the shim level.
+
+Initiatives (Linear's cross-Project rollup) are NOT used — they're intended for cross-quarter, cross-team groupings rarely appropriate for an Epic. If a project ever needs Initiative-level grouping, that's a future extension to this rule.
+
+## Self-host edge case (GitHub PRDs → GitHub destination)
+
+When `github-to-tracker` is invoked AND `tracker = "github"`, both reads and writes hit the same GitHub repo. Label namespaces are kept separate so the two flows don't collide:
+
+- PRD-source labels: `prd-draft`, `prd-ready`, `prd-in-review`, `prd-blocked`, `prd-ticketed`, `prd-shipped` — owned by `github-prd-intake` and the human PM.
+- Build-queue labels: `status:ready`, `status:in-progress`, `status:code-review`, `status:on-dev`, `status:done` — owned by `github-build-intake` and `github-agent`.
+- Sentinel issue label: `prd-intake-feedback` — owned by `github-prd-intake`.
+
+Never overload one label across both lifecycles.
+
+The same separation applies for Linear self-host (`source = "linear"` AND `tracker = "linear"`): project-level labels (`prd-*`) drive the PRD lifecycle; issue-level labels (`status:*`) drive the build lifecycle; the sentinel feedback issue carries the issue-level `prd-intake-feedback` label.
+
+## Invariants
+
+- Project tracker selection is **persistent** within a project — always read from config, never infer from the shape of `$ARGUMENTS`. If a developer wants a different destination for one run, they edit `.lisa.config.local.json`.
+- A vendor-neutral skill never embeds vendor-specific terminology in its prompts (no "JIRA ticket key", "epic parent" — use "tracker key", "parent issue"). The vendor skill is responsible for translating its inputs.
+- The shim layer is intentionally thin — its only job is dispatch. Gate logic, validation rules, and field schemas all live in the vendor skills.
+- Secrets stay in env (`JIRA_API_TOKEN`, `LINEAR_API_KEY`, `GH_TOKEN`, `NOTION_API_KEY`, `ATLASSIAN_API_TOKEN`). Configuration in `.lisa.config.json` is non-secret only — IDs, keys, slugs, project codes.
+- E2E test config (`E2E_BASE_URL`, `E2E_TEST_PHONE`, `E2E_TEST_OTP`, `E2E_TEST_ORG`, `E2E_GRAPHQL_URL`) stays in env for now — not tracker-related and frequently per-environment.
+
+## Migration from the previous schema
+
+The pre-expansion `.lisa.config.json` had only `tracker` and `github.{org,repo}`. Existing projects continue to work — the new fields are all conditionally required, and `tracker = "jira"` (the default) only requires `atlassian.cloudId` and `jira.project`, which were previously read from env (`JIRA_SERVER`, `JIRA_PROJECT`).
+
+To migrate a project off env vars:
+
+1. Add `atlassian.cloudId` (resolve via `getAccessibleAtlassianResources` once).
+2. Add `jira.project` (was `JIRA_PROJECT`).
+3. Drop `JIRA_SERVER` from env (replaced by `atlassian.cloudId`).
+4. Optionally add `source` to set the default PRD source for batch skills.

package/plugins/lisa/rules/intent-routing.md

@@ -310,33 +310,33 @@ Sequence:
 1. `ops-specialist` -- health checks, log inspection, error monitoring, performance analysis
 2. Report findings, escalate if action needed
 
-## Tracker Entry Point (JIRA or GitHub Issues)
+## Tracker Entry Point (JIRA, GitHub Issues, or Linear)
 
-When the request references a tracker ticket (a JIRA key like `PROJ-123`, a JIRA URL, a GitHub issue URL, or an `org/repo#<n>` token):
+When the request references a tracker ticket (a JIRA key like `PROJ-123`, a JIRA URL, a GitHub issue URL, an `org/repo#<n>` token, or a Linear identifier like `ENG-123` or a Linear project URL):
 
-1. Hand off to the matching vendor agent — `jira-agent` (for JIRA refs) or `github-agent` (for GitHub Issue refs). The configured destination tracker (`.lisa.config.json` `tracker`) is the default when the ref shape is ambiguous.
-2. The agent reads the ticket fully via the matching read skill (`jira-read-ticket` / `github-read-issue`) — description / body, comments, attachments, linked issues, parent (Epic / parent sub-issue), siblings.
-3. The agent validates ticket quality via the matching verify skill (`jira-verify` / `github-verify`).
+1. Hand off to the matching vendor agent — `jira-agent` (JIRA refs), `github-agent` (GitHub Issue refs), or `linear-agent` (Linear identifier or project URL). The configured destination tracker (`.lisa.config.json` `tracker`) is the default when the ref shape is ambiguous.
+2. The agent reads the work item fully via the matching read skill (`jira-read-ticket` / `github-read-issue` / `linear-read-issue`) — description / body, comments, attachments, linked items, parent (Epic / Project / parent Issue), siblings.
+3. The agent validates item quality via the matching verify skill (`jira-verify` / `github-verify` / `linear-verify`).
 4. The agent runs analytical triage via the vendor-neutral `ticket-triage` skill.
 5. If triage finds unresolved ambiguities (`BLOCKED` verdict), the agent posts findings and STOPS -- no work begins.
 6. The agent determines intent and delegates to the appropriate flow:
 
-| Ticket Type | Flow | Work Type |
-|-------------|------|-----------|
-| Epic | Plan | -- |
+| Item kind | Flow | Work Type |
+|-----------|------|-----------|
+| Epic (JIRA Epic / GitHub Epic-labeled / Linear Project) | Plan | -- |
 | Story | Implement | Build |
 | Task | Implement | Build |
 | Bug | Implement | Fix |
 | Spike | Implement | Investigate Only |
 | Improvement | Implement | Improve |
-| Sub-task | Implement | (per parent's intent) |
+| Sub-task / sub-Issue | Implement | (per parent's intent) |
 
-For JIRA, the type comes from the ticket's issue type. For GitHub, the type comes from the `type:<value>` label.
+For JIRA, the type comes from the ticket's issue type. For GitHub, the type comes from the `type:<value>` label. For Linear, the type typically comes from a label (`type:story`, `type:bug`) or is inferred from the description if unlabeled — `linear-agent` handles the inference.
 
-If the ticket type is ambiguous, read the description / body to classify. A "Task" that describes broken behavior is a Fix. A "Bug" that requests new functionality is a Build.
+If the item type is ambiguous, read the description / body to classify. A "Task" that describes broken behavior is a Fix. A "Bug" that requests new functionality is a Build.
 
-7. The agent syncs progress at milestones via the matching sync skill (`jira-sync` / `github-sync`).
-8. The agent posts evidence at completion via the matching evidence skill (`jira-evidence` / `github-evidence`).
+7. The agent syncs progress at milestones via the matching sync skill (`jira-sync` / `github-sync` / `linear-sync`).
+8. The agent posts evidence at completion via the matching evidence skill (`jira-evidence` / `github-evidence` / `linear-evidence`).
 
 Vendor-neutral callers (e.g., `implement`, `verify`) should invoke the `tracker-*` shims — they dispatch to the right vendor automatically.