@codyswann/lisa 1.95.0 → 2.0.0

package/plugins/src/base/commands/{plan/add-test-coverage.md → improve/test-coverage.md}

@@ -4,4 +4,4 @@ allowed-tools: ["Skill"]
 argument-hint: "<threshold-percentage>"
 ---
 
-Use the /lisa:plan-add-test-coverage skill to increase test coverage. $ARGUMENTS
+Use the /lisa:improve-test-coverage skill to increase test coverage. $ARGUMENTS

package/plugins/src/base/commands/{plan/improve-tests.md → improve/tests.md}

@@ -4,4 +4,4 @@ allowed-tools: ["Skill"]
 argument-hint: "<target-description>"
 ---
 
-Use the /lisa:plan-improve-tests skill to improve test quality. $ARGUMENTS
+Use the /lisa:improve-tests skill to improve test quality. $ARGUMENTS

package/plugins/src/base/commands/plan.md

@@ -1,14 +1,26 @@
 ---
-description: "Plan work. Defines acceptance criteria, researches codebase, maps dependencies, and breaks down into ordered work items."
-argument-hint: "<description-or-ticket-id-or-url>"
+description: "Plan work. Vendor-agnostic intake — given a PRD URL/path or description, extracts requirements, walks the live product, validates, and creates work items in the configured tracker."
+argument-hint: "<PRD-url | @file | ticket-id-or-url | description>"
 ---
 
 Apply the `intent-routing` rule (loaded via the lisa plugin) and execute the **Plan** flow.
 
 **Orchestration: agent team.** Plan is a multi-specialist flow feeding a shared decomposition. After echoing the flow and orchestration mode, your FIRST tool call MUST be `TeamCreate`. Do not call `TaskCreate`, `Agent`, or implementation tools before the team exists.
 
+## Source dispatch
+
+Detect the source type from `$ARGUMENTS` and route accordingly. The Plan flow is vendor-agnostic — the public interface speaks "PRD" and "work items", not "Notion" or "JIRA".
+
+| If `$ARGUMENTS` is... | Hand off to |
+|------------------------|-------------|
+| A Notion URL (`notion.so/...` or a Notion database/page ID) | The `notion-prd-intake` skill (single-PRD mode if one page; database-scan mode if a database URL). It runs the full pipeline: extract artifacts, walk live product, dry-run validate, create tickets in the configured tracker, run the coverage audit, transition Notion `Status`. |
+| A JIRA ticket ID or URL (e.g. `SE-123` or `*.atlassian.net/browse/SE-123`) | The `jira-agent`, which reads the ticket and extracts context. (Used when an existing JIRA epic *is* the spec — Plan decomposes it into stories/sub-tasks.) |
+| A Linear / GitHub Issues URL or key | *Not yet implemented.* Stop and tell the user the adapter doesn't exist yet — the architecture supports it, but no `linear-prd-intake` / `github-prd-intake` skill has been built. Don't fall back. |
+| A file path (`@plan.md`, `./spec.md`) | Read the file as the spec; run the Plan flow's core decomposition with the file content as input. |
+| A plain-text description | Use the description as the spec; run the Plan flow's core decomposition. |
+
 If no PRD or specification exists, suggest running the **Research** flow first to produce one.
 
-If the argument is a JIRA ticket ID or URL, hand off to the `jira-agent` which will read the ticket and extract context.
+The underlying intake skills (e.g. `notion-prd-intake`) are internal — developers don't invoke them directly. They speak in vendor-agnostic terms (`/plan <PRD>`); the source/tracker choice is config.
 
 $ARGUMENTS

package/plugins/src/base/commands/product-walkthrough.md

@@ -0,0 +1,7 @@
+---
+description: "Walk through the live product via a real browser (Playwright MCP) to ground PRD evaluation or ticket creation in what exists today. Captures current behavior, design-vs-product divergence, reuse candidates, and behavioral surprises."
+allowed-tools: ["Skill"]
+argument-hint: "<route or feature area to walk>"
+---
+
+Use the /lisa:product-walkthrough skill to walk through the live product, capture current state, and produce findings that ground PRD/ticket reasoning. $ARGUMENTS

package/plugins/{lisa/commands/plan/local-code-review.md → src/base/commands/review/local.md}

@@ -3,4 +3,4 @@ description: "Review local branch changes compared to main"
 allowed-tools: ["Skill"]
 ---
 
-Use the /lisa:plan-local-code-review skill to review local changes.
+Use the /lisa:review-local skill to review local changes.

package/plugins/{lisa/skills/plan-fix-linter-error → src/base/skills/fix-linter-error}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-fix-linter-error
+name: fix-linter-error
 description: This skill should be used when fixing all violations of one or more ESLint rules across the codebase. It runs the linter, groups violations by rule and file, generates a brief with fix strategies, and creates a plan with tasks to implement the fixes.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 
@@ -42,4 +42,4 @@ Fix strategies: extract functions, early returns, apply formatting, add types
 Verification: `bun run lint 2>&1 | grep -E "($ARGUMENTS)" | wc -l` → Expected: 0
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/src/base/skills/{plan-execute → implement}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-execute
+name: implement
 description: This skill should be used for any non-trivial request — features, bugs, stories, epics, spikes, or multi-step tasks. It accepts a ticket URL (Jira, Linear, GitHub), a file path containing a spec, or a plain-text prompt. It assembles an agent team, breaks the work into structured tasks, and manages the full lifecycle from research through implementation, code review, deploy, and empirical verification.
 ---
 

package/plugins/src/base/skills/{plan-lower-code-complexity → improve-code-complexity}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-lower-code-complexity
+name: improve-code-complexity
 description: This skill should be used when reducing the cognitive complexity threshold of the codebase. It lowers the threshold by 2, identifies functions that exceed the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to fix all violations.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 ---
@@ -41,4 +41,4 @@ Refactoring strategies: extract functions, early returns, extract conditions, us
 Verification: `bun run lint 2>&1 | grep "cognitive-complexity" | wc -l` → Expected: 0
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/src/base/skills/{plan-reduce-max-lines → improve-max-lines}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-reduce-max-lines
+name: improve-max-lines
 description: This skill should be used when reducing the maximum file lines threshold and fixing all violations. It updates the eslint threshold configuration, identifies files exceeding the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to split oversized files.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 
@@ -42,4 +42,4 @@ Refactoring strategies: extract modules, remove duplication, delete dead code, s
 Verification: `bun run lint 2>&1 | grep "max-lines" | wc -l` → Expected: 0
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/{lisa/skills/plan-reduce-max-lines-per-function → src/base/skills/improve-max-lines-per-function}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-reduce-max-lines-per-function
+name: improve-max-lines-per-function
 description: This skill should be used when reducing the maximum lines per function threshold and fixing all violations. It updates the eslint threshold configuration, identifies functions exceeding the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to split oversized functions.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 
@@ -43,4 +43,4 @@ Refactoring strategies: extract functions, early returns, extract conditions, us
 Verification: `bun run lint 2>&1 | grep "max-lines-per-function" | wc -l` → Expected: 0
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/src/base/skills/{plan-add-test-coverage → improve-test-coverage}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-add-test-coverage
+name: improve-test-coverage
 description: This skill should be used when increasing test coverage to a specified threshold percentage. It runs the coverage report, identifies files with the lowest coverage, generates a brief with coverage gaps, and creates a plan with tasks to add the missing tests.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 
@@ -41,4 +41,4 @@ Configuration: [config file path], update thresholds to $ARGUMENTS%
 Verification: `bun run test:cov` → Expected: All thresholds pass at $ARGUMENTS%
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

package/plugins/{lisa/skills/plan-improve-tests → src/base/skills/improve-tests}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plan-improve-tests
+name: improve-tests
 description: This skill should be used when improving test quality. It scans the test suite for weak, brittle, or poorly-written tests, generates a brief with improvement opportunities, and creates a plan with tasks to strengthen the tests.
 allowed-tools: ["Read", "Bash", "Glob", "Grep"]
 ---
@@ -44,4 +44,4 @@ Test files needing improvement (ordered by impact):
 Verification: `bun run test` -> Expected: All tests pass, improved assertions and coverage
 ```
 
-Invoke `/plan-execute` with this brief to create the implementation plan.
+Invoke `/implement` with this brief to create the implementation plan.

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

@@ -0,0 +1,134 @@
+---
+name: jira-build-intake
+description: "Symmetric counterpart to notion-prd-intake on the JIRA side. Scans a JIRA project (or JQL filter) for tickets in Status=Ready, claims each by transitioning to In Progress, runs the implementation/build flow via jira-agent, and transitions to On Dev on completion. The Ready status is the human-flipped signal that a TODO ticket is truly ready for development — mirroring how Notion PRDs work product Draft → Ready → (us) In Review → Blocked|Ticketed."
+allowed-tools: ["Skill", "Bash", "mcp__atlassian__getAccessibleAtlassianResources", "mcp__atlassian__searchJiraIssuesUsingJql", "mcp__atlassian__getJiraIssue", "mcp__atlassian__getTransitionsForJiraIssue", "mcp__atlassian__transitionJiraIssue", "mcp__atlassian__addCommentToJiraIssue"]
+---
+
+# JIRA Build Intake: $ARGUMENTS
+
+`$ARGUMENTS` is one of:
+
+1. A JIRA project key (e.g. `SE`) — scans that project for `Status = Ready` tickets.
+2. A full JQL filter (e.g. `project = SE AND component = "frontend" AND Status = Ready`) — used as-is. The skill will not append a `Status = Ready` clause if the JQL already names a status, so callers can intentionally widen.
+
+Run one build-intake cycle. Each Ready ticket is claimed, built via the `jira-agent` flow, and transitioned to `On Dev` (or the equivalent next-status for that project). The cycle is the symmetric mirror of `notion-prd-intake`: humans flip `Ready`, agents pick up and progress.
+
+## Lifecycle assumed
+
+The JIRA workflow has these statuses (or equivalents — see Configuration for renaming):
+
+```text
+TODO → Ready → In Progress → On Dev → On QA → Done
+       (PM/   (us claim)    (us done; (downstream)
+        human)               PR ready)
+```
+
+This skill ONLY transitions `Ready → In Progress` on claim, and `In Progress → On Dev` on completion. It never touches `TODO`, `On QA`, `Done`, or any blocked/closed states.
+
+**Pre-flight check**: at start of each cycle, call `getTransitionsForJiraIssue` against a sample Ready ticket to confirm `In Progress` and `On Dev` are reachable transitions. If not, stop and report the workflow misconfiguration to the caller — do not invent transitions.
+
+## Phases
+
+### Phase 1 — Resolve the query
+
+1. Parse `$ARGUMENTS`:
+   - Project key: build JQL `project = <KEY> AND Status = "Ready" ORDER BY priority DESC, created ASC`.
+   - Full JQL: use as-is. If it does not include a `Status` clause, append `AND Status = "Ready"`.
+2. Resolve Atlassian cloud ID via `getAccessibleAtlassianResources`.
+
+### Phase 2 — Find Ready tickets
+
+Run the JQL via `searchJiraIssuesUsingJql`. Capture each ticket's: key, summary, issue type, priority, assignee, parent (epic), labels, components.
+
+If empty, report `"No tickets with Status=Ready. Nothing to do."` and exit. This is the common idle case.
+
+### Phase 3 — Process each Ready ticket (serial)
+
+#### 3a. Claim
+
+Transition the ticket from `Ready` to `In Progress` via `transitionJiraIssue`.
+- Use `getTransitionsForJiraIssue` to find the transition ID for `In Progress`.
+- Post a `[claude-build-intake]` comment via `addCommentToJiraIssue`: `"Claimed by Claude. Starting build."`
+- This is the idempotency lock — a re-entrant cycle's `Status = Ready` filter will not see this ticket again.
+
+If the transition fails (permission, missing transition, race), log under "Errors" in the cycle summary and skip this ticket. **Do not invoke the build flow on a ticket you didn't successfully claim.**
+
+#### 3b. Run the build flow
+
+Invoke the `jira-agent` (existing per-ticket lifecycle agent) with the ticket key. `jira-agent` owns:
+- Reading the full ticket graph (`jira-read-ticket`)
+- Running its own pre-flight quality gate (`jira-verify`)
+- Running ticket triage (`ticket-triage`)
+- Routing to the appropriate flow (Build / Fix / Investigate / Improve based on type)
+- Posting progress comments via `jira-sync`
+- Posting evidence via `jira-evidence`
+
+Wait for `jira-agent` to return. Capture its outcome:
+- **Success** — PR is ready (open or merged); evidence posted; ready for next status.
+- **Blocked by jira-verify pre-flight gate** — `jira-agent` itself transitions the ticket to `Blocked` and reassigns to Reporter. This is correct and expected — let it stand. Record the outcome and move on.
+- **Blocked by ticket-triage ambiguities** — `jira-agent` posts findings and stops. The ticket stays in `In Progress`. Surface to human; do not auto-transition. Record under "Errors" with reason `"Triage found ambiguities — see comments on <ticket-key>"`.
+- **Errored** — exception, missing config, etc. Leave the ticket in `In Progress` for human investigation. Record under "Errors" with the exception summary.
+
+#### 3c. Transition to On Dev (only on Success)
+
+If `jira-agent` returned Success:
+1. Use `getTransitionsForJiraIssue` to find the transition ID for `On Dev` (or the configured next-after-build status).
+2. Transition via `transitionJiraIssue`.
+3. Post a `[claude-build-intake]` comment: `"Build complete. PR <URL>. Transitioned to On Dev."`
+
+For any non-Success outcome, do NOT transition. The ticket sits in `In Progress` (or wherever `jira-agent` left it for the Blocked case) — the cycle's job is done; humans take it from there.
+
+#### 3d. Continue
+
+Move to the next Ready ticket. One ticket failing does not stop others.
+
+### Phase 4 — Summary report
+
+```text
+## jira-build-intake summary
+
+Query: <JQL or project key>
+Cycle started: <ISO timestamp>
+Cycle completed: <ISO timestamp>
+
+Tickets processed: <n>
+- On Dev (build complete, PR ready): <n>
+  - <ticket-key> <summary> → PR <URL>
+- Blocked (pre-flight verify failed): <n>
+  - <ticket-key> <summary> — see ticket comments
+- Held (triage found ambiguities): <n>
+  - <ticket-key> <summary> — see ticket comments
+- Errors: <n>
+  - <ticket-key> <summary> — <reason>
+
+Total PRs opened: <n>
+```
+
+## Idempotency & safety
+
+- **Claim-first ordering**: `In Progress` set BEFORE `jira-agent` invocation — no double-pickup.
+- **No writes outside the lifecycle**: this skill only transitions `Ready → In Progress` and `In Progress → On Dev`. Every other status change is owned by `jira-agent` (which suggests transitions but only auto-transitions on the verify-FAIL path).
+- **Failure isolation**: per-ticket exceptions caught and recorded; the cycle continues.
+- **Single cycle per query**: do not run two `jira-build-intake` cycles in parallel against overlapping queries — concurrent claims could race. The scheduling layer (when added) is responsible for serialization.
+- **Never invent a transition**: if `In Progress` or `On Dev` aren't valid transitions in the project's workflow, stop and report rather than guessing alternative names.
+
+## Configuration
+
+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 |
+| 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 |
+
+## Rules
+
+- Never transition a ticket the cycle didn't claim. The `In Progress` transition is the signature of cycle ownership.
+- Never bypass `jira-agent` to do build work directly. `jira-agent` owns the per-ticket lifecycle (read, verify, triage, route, sync, evidence). This skill is the dispatcher, not the builder.
+- Never auto-transition past `On Dev`. Downstream statuses (`On QA`, `Done`) are owned by QA / product / a future verification-intake skill — not this one.
+- If the ticket has no Validation Journey or no sign-in credentials in its description, `jira-agent`'s pre-flight verify will catch it and transition to `Blocked` — **don't try to fix the ticket from here**. Pre-flight gating is `jira-agent`'s job; running build work on a thin ticket produces broken work.
+- On any unexpected response from `jira-agent` (status it doesn't claim, missing PR URL on success, etc.), record as Error and surface — never assume.

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

@@ -6,18 +6,22 @@ allowed-tools: ["Read", "Glob", "LS", "Skill", "mcp__atlassian__getVisibleJiraPr
 
 # Create JIRA Issues from $ARGUMENTS
 
-Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all mandatory quality gates.
+Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans structure only — every individual ticket write is delegated to `jira-write-ticket`.** Do not call `mcp__atlassian__createJiraIssue` from this skill; the necessary write tools are intentionally not in `allowed-tools`.
 
 ## Process
 
-1. **Analyze**: Read $ARGUMENTS to understand scope
-2. **Determine Structure**:
+1. **Analyze**: Read $ARGUMENTS to understand scope.
+2. **Extract source artifacts**: invoke the `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.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `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
    - Direct tasks if: bug fix, single file, minor change
-3. **Create Issues** with hierarchy:
-   ```
+5. **Plan hierarchy**:
+   ```text
    Epic → User Story → Tasks (test, implement, document, cleanup)
    ```
+6. **Delegate every write to `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 `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** (`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.
 
 ## Mandatory for Every Code Issue
 
@@ -81,33 +85,17 @@ h3. Assertions
 4. **Assertions are testable statements** — "Health check returns 200 with status ok" not "API works"
 5. **Prerequisites include environment setup** — Database connection, env vars, running services
 
-## Source Artifact Preservation
-
-If $ARGUMENTS includes a PRD, design doc, Figma URL, Lovable prototype, or similar external artifact — or if a referenced file links out to one — those references MUST be preserved as remote links on the created tickets. Dropping source artifacts during ticket creation is the single most common quality failure in this pipeline, because developers picking up a ticket then lose the design/UX source of truth.
+## Source Artifacts
 
-Rules:
+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.
 
-1. **Extract before creating**: enumerate every external URL, embed, attachment, or example payload in the input. Classify by domain (`ui-design`, `ux-flow`, `data`, `ops`, `reference`) — see `notion-to-jira` Phase 1.5 for the canonical taxonomy.
-2. **Epic gets everything**: attach all extracted artifacts as remote links on the epic, regardless of domain.
-3. **Stories inherit by domain**: frontend stories get `ui-design` + `ux-flow` + `reference`; backend gets `data` + `reference`; infra gets `ops` + `reference`. When ambiguous, err on the side of inclusion.
-4. **Sub-tasks inherit via parent**: do not re-attach on every sub-task unless a specific artifact applies only to that sub-task.
-5. **Verify before reporting**: before declaring done, confirm every extracted artifact is reachable from the tickets. If any are missing, fail loudly and surface the dropped list to the human — do not silently drop.
+**Invoke the `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.
 
 When delegating actual writes to `jira-write-ticket`, pass the extracted artifact list so its Phase 4c (Remote Links) step can attach them.
 
-**Classification disambiguation** (applied during extraction):
-- Figma URL with `/proto/` or `starting-point-node-id=` → `ux-flow`; plain design frame URL → `ui-design`.
-- Lovable output → always `ux-flow` (its code/styling/logic is NOT authoritative).
-- Loom / annotated screenshot with flow arrows → `ux-flow`; bare screenshot → `ui-design`.
-
-**Source precedence** (must be recorded on every ticket carrying design artifacts):
-- Business rules (fields, validation, permissions, constraints) come from the **description / PRD body**.
-- Visual treatment (layout, spacing, typography, color) comes from **mocks** (`ui-design`).
-- Flow and interaction (navigation, transitions, state changes) come from **prototypes** (`ux-flow`).
-- API / data shape comes from **`data` artifacts**.
-- Cross-axis conflicts are surfaced as `## Open Questions` BLOCKERs, never silently reconciled.
+## Live Product Walkthrough
 
-**Existing-component reuse** (applies to every UI-touching ticket): the story description must instruct the implementer to locate the closest existing component in the codebase and prefer reuse over pixel-matching a mock. Design-vs-code divergence is raised on the ticket, not resolved by the implementer alone.
+When the work touches existing user-facing surfaces, invoke the `product-walkthrough` skill before drafting tickets. The walkthrough findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the ticket plan and surface under `## Current Product` on the resulting tickets. Skip only when the work is purely backend or affects a screen that does not yet exist.
 
 ## Issue Requirements
 
@@ -120,10 +108,45 @@ Each issue must clearly communicate to:
 Default project: from jira-cli config (override via arguments)
 Exclude unless requested: migration plans, performance tests
 
-Execute the analysis and create the complete JIRA structure with proper parent-child relationships.
-
 ## Delegation to jira-write-ticket
 
-For every individual ticket that will be created, delegate to the `jira-write-ticket` skill rather than calling `mcp__atlassian__createJiraIssue` directly. `jira-write-ticket` enforces description quality (Gherkin acceptance criteria, stakeholder/developer/assistant sections), relationship discovery (`blocks`, `is blocked by`, `relates to`, remote PR/Confluence/dashboard links), epic parent validation, and post-create verification.
+**Mandatory.** Every ticket created by this skill MUST go through `jira-write-ticket`. This skill never calls `mcp__atlassian__createJiraIssue` itself — that tool is intentionally excluded from `allowed-tools` so the gate cannot be bypassed.
+
+`jira-write-ticket` enforces things this skill does not, and which determine ticket quality:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation (non-bug, non-epic types)
+- Explicit link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Remote links (PRs, Confluence, dashboards)
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+### Invocation order
+
+Tickets must be created in parent-before-child order so each child can be passed its parent key:
+
+1. Invoke `jira-write-ticket` for the epic. Capture the returned key.
+2. For each story, invoke `jira-write-ticket` with the epic key as the epic parent. Capture each story key.
+3. For each sub-task, invoke `jira-write-ticket` with the parent story key.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, project key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent key (epic key for stories; story key for sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules — `jira-write-ticket` Phase 4c attaches them as remote links
+- For tickets that change runtime behavior: the Validation Journey draft (or instruct it to call `jira-add-journey` after create)
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's an epic vs. story vs. sub-task)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent keys through subsequent writes
+- Running the Phase 5.5-style preservation check after all writes complete
 
-This skill's role is to analyze the input and decide the hierarchy (which epics, which stories, which tasks, in what parent-child structure). `jira-write-ticket` handles the actual write with full quality gates.
+It does not own the actual JIRA write — that's `jira-write-ticket`'s job.

package/plugins/src/base/skills/jira-source-artifacts/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: jira-source-artifacts
+description: "Canonical taxonomy and rules for handling source artifacts (Figma, Lovable, Loom, screenshots, design docs, data samples) when generating or evaluating JIRA tickets. Defines: (1) artifact domains, (2) classification rules per tool, (3) source precedence (which artifact is authoritative for which question), (4) inheritance from epic to story to sub-task, (5) cross-axis conflict handling. Invoke this skill from any flow that extracts, attaches, or reasons about external design/UX/data artifacts so the rules don't drift across skills."
+allowed-tools: []
+---
+
+# JIRA Source Artifact Taxonomy and Rules
+
+This skill is doctrine, not action — it defines the rules. Skills that need to extract, classify, attach, or reason about external artifacts (design files, prototypes, recordings, data samples) invoke this skill to load the taxonomy and apply it.
+
+The reason this lives in one place: silent drift across skills is the failure mode this body of rules exists to prevent. If the rules differ between `notion-to-jira`, `jira-create`, and `jira-write-ticket`, agents will silently route artifacts wrong and developers will lose source of truth. Edit here, propagate everywhere.
+
+## 1. Domains
+
+Every artifact is classified into exactly one domain. The domain determines what the artifact is the source of truth for, and which tickets inherit it.
+
+| Domain | What it defines | Examples |
+|--------|-----------------|----------|
+| `ui-design` (mocks) | **Visual treatment only** — layout, spacing, typography, color, iconography | Figma design frames, Framer static frames, bare screenshots, mockup PNGs |
+| `ux-flow` (prototypes) | **Interaction and flow only** — navigation, transitions, state changes, timing, empty/error/loading states | Lovable output, Loom walkthroughs, Figma prototype links, annotated screenshots, Miro/Mural flow diagrams, user journey maps |
+| `data` | Request/response shape, schema constraints, contracts | Example JSON, SQL schemas, GraphQL snippets, API contracts, sample payloads |
+| `ops` | Deployment / runtime context | Runbooks, dashboards, Terraform refs, deployment diagrams |
+| `reference` | Cross-cutting context | Confluence, Notion peer pages, Google Docs, related PRDs, RFCs |
+
+## 2. Classification rules per tool
+
+These rules exist because agents consistently misclassify Figma and Lovable artifacts, which are the two most common sources of dropped or misrouted context.
+
+- **Figma**: classify as `ux-flow` if the URL is a prototype share link — it contains `/proto/`, has `starting-point-node-id=` in the query, or the sharing context labels it "prototype" / "play mode". Otherwise classify as `ui-design`. Never assume; inspect the URL.
+- **Figma file with both design frames and a prototype**: emit two entries — one `ui-design` for the file, one `ux-flow` for the prototype URL — so both propagate correctly.
+- **Lovable output**: always `ux-flow`. Lovable ships working code, but its code, styling, and any embedded business rules are NOT authoritative. Treat strictly as a UX/flow reference. Implementation uses existing project components; business rules come from the PRD body, not from Lovable.
+- **Loom / video walkthrough**: `ux-flow` in the vast majority of cases. The rare exception — a video that's purely a static-frame design review with no interaction — is still `ux-flow` for routing purposes (both UX and UI stories benefit).
+- **Screenshot**: bare unannotated screenshot → `ui-design`. Screenshot with arrows between frames, flow labels, or numbered steps → `ux-flow`. Side-by-side gallery of state variants (empty/error/loading) → `ui-design` with the state variants noted.
+- **Confluence / Notion peer / Google Doc**: `reference` unless it is specifically a runbook (`ops`) or contains canonical API contracts (`data`).
+- **Grafana / Datadog / Sentry**: `ops`.
+- **Code blocks with example payloads** (JSON, SQL, GraphQL, cURL): `data`.
+
+When an artifact could plausibly fit multiple domains and the rules above don't disambiguate, err on the side of inclusion — emit it under both, or use the broader domain. Misclassification is caught downstream by the preservation gate; underclassification is silent drop.
+
+## 3. Source precedence
+
+When artifacts disagree, silent reconciliation is a known failure mode. The rules below define which source wins which question. **Record this precedence on every ticket that carries design artifacts** (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't reconcile silently.
+
+| Question | Authoritative source |
+|----------|---------------------|
+| Does this field exist? Is it required? Who can see/edit it? What validation applies? Permission rules, edge cases, data constraints? | **Description / PRD body** (business rules) |
+| What does it look like — layout, spacing, typography, color, iconography? | **Mocks (`ui-design`)** |
+| How does it flow — navigation, transitions, state changes, timing, empty/error/loading states? | **Prototypes (`ux-flow`)** |
+| Where does the data come from, what shape is it, what are the API contracts? | **`data` artifacts** |
+| Where does it run, who's on call, what's the dashboard? | **`ops` artifacts** |
+
+## 4. Cross-axis conflict handling
+
+Conflicts MUST be surfaced under `## Open Questions` on the affected ticket — never silently reconciled.
+
+- Mock shows a field the description doesn't mention → BLOCKER: "Figma shows field `X` not in PRD; confirm it exists, and if so add business rules (required/optional, validation, permissions)."
+- Description mandates behavior the prototype contradicts → BLOCKER: "PRD says Y, prototype shows Z; which is correct?"
+- Prototype shows a flow the mocks don't cover (e.g., an error state) → Note: "Error state flow from prototype; no mock exists. Use existing error component or request mock."
+- Multiple artifacts of the same domain disagree (two Figma links showing different layouts) → BLOCKER: list both, ask which is current.
+- Lovable output without a description covering business rules → BLOCKER: "Business rules missing. Lovable's embedded logic is not authoritative; PRD must explicitly state required fields, validation, permissions, and edge cases."
+
+## 5. Coverage smells
+
+Incomplete artifact sets are a common root cause of implementation drift. Surface these on the epic when extracting:
+
+- **Zero artifacts on a non-trivial PRD**: almost always an extraction bug, not a design decision. Say so explicitly.
+- **`ux-flow` present, `ui-design` absent**: flag "missing UI mocks". UI will be inferred from prototype frames — note that prototype styling is typically placeholder and must NOT be treated as visual source of truth.
+- **`ui-design` present, `ux-flow` absent**: flag "missing UX prototype". UX will be inferred from static mock states (empty/error/loading/hover) — any flow not explicitly depicted must be raised as a BLOCKER with recommendation + alternatives, not silently invented.
+
+## 6. Inheritance: epic → story → sub-task
+
+Artifacts attach as Jira remote links and propagate down the hierarchy.
+
+- **Epic**: gets EVERY artifact, regardless of domain. The epic is the canonical hub — anyone working on the epic or its descendants must reach the full set from one place. No filtering.
+- **Story**: inherits the artifacts whose domain matches its scope:
+
+  | Story type | Inherits domains |
+  |------------|------------------|
+  | Frontend / UI | `ui-design`, `ux-flow`, `reference` |
+  | Backend / API / data model | `data`, `reference` |
+  | Infrastructure | `ops`, `reference` |
+  | Mixed / setup ("X.0") | All domains |
+
+  When classification is ambiguous, err on the side of inclusion — a developer can ignore an extra link, but they can't follow one that wasn't attached.
+
+- **Sub-task**: inherits via the parent story link. Do NOT re-attach the same artifacts on every sub-task — that creates noise. Only attach an artifact directly on a sub-task when the sub-task depends on something the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame the broader story doesn't cite).
+
+## 7. Existing-component reuse (UI-touching tickets)
+
+Mocks define visual *intent*, not implementation shortcut. Every UI-touching ticket description must include:
+
+> Before implementing, identify the closest existing component in the codebase. Prefer reuse even if the mock specifies different styling — flag the design-vs-code divergence as a discussion item on this ticket rather than pixel-matching from scratch.
+
+If no existing component fits, building a new one is an explicit decision that must be recorded in the ticket (with rationale) before implementation. Lovable-generated components are never the reuse target — always use the project's own components.
+
+## 8. Preservation gate (run after creating tickets)
+
+Before declaring done, verify every extracted artifact is reachable from the created tickets.
+
+1. Build a preservation matrix: `artifact URL → [ticket keys that reference it]`.
+2. For every artifact:
+   - It MUST appear on the epic it belongs to (no exceptions).
+   - It SHOULD appear on at least one story whose scope matches its domain (except `reference`-domain artifacts, which may be epic-only if no story is domain-matched).
+3. Any artifact with zero references anywhere, or missing from its epic: FAIL LOUDLY — list the dropped artifacts with domain, title, and source page; surface to the human; re-attach before continuing.
+4. If classification looks misrouted (e.g., a Figma link landed on a backend story and nowhere else), surface the misroute and offer to re-propagate.
+
+Skipping this gate is the most common cause of silent artifact loss. Do not skip it.