@codyswann/lisa 2.119.1 → 2.121.0

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

@@ -0,0 +1,357 @@
+---
+name: notion-to-tracker
+description: >
+  Break down a Notion PRD into Epics, Stories, and Sub-tasks in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json). Use this skill whenever the user
+  shares a Notion PRD URL and wants it converted into tracker tickets, or asks to "break down a PRD",
+  "create tickets from a PRD", "turn this PRD into tickets", or similar. Also trigger when the user
+  mentions creating epics/stories/tasks from a Notion document. This skill handles the full pipeline:
+  fetching the PRD, analyzing comments, researching the codebase, identifying blockers, and creating
+  all tickets with empirical verification plans.
+---
+
+# Notion PRD to Tracker Breakdown
+
+Convert a Notion PRD into a structured ticket hierarchy in the configured destination tracker (JIRA, GitHub Issues, or Linear per .lisa.config.json): Epics > Stories > Sub-tasks.
+Each sub-task is scoped to exactly one repo and includes an empirical verification plan.
+
+> **Notion access policy**: all Notion operations in this skill go through `lisa:notion-access`. Do not call Notion REST APIs (`api.notion.com/...`), Notion MCP tools (`mcp__*notion*`), or the `@notionhq/client` library directly. Invoke `lisa:notion-access` via the Skill tool with an operation name and arguments per its dispatch table.
+
+## Modes
+
+This skill supports two modes, controlled by a `dry_run` flag in `$ARGUMENTS`:
+
+- **`dry_run: false`** (default — full mode): run all phases, write tickets via `lisa:tracker-write`, run the preservation gate, report.
+- **`dry_run: true`** (planning + validation only — no writes): run Phases 1, 1.5, 1.6, 2, 3, 4 to plan the hierarchy and draft each ticket spec, then call `lisa:tracker-validate` (with `--spec-only`) on every drafted ticket. Aggregate the per-ticket validator reports into a single dry-run report. **Skip Phase 5 (sub-task creation), Phase 5.5 (preservation gate), and Phase 6 (results report)** — none of those make sense without writes. Return the dry-run report so the caller (e.g. `lisa:notion-prd-intake`) can decide whether to proceed.
+
+Dry-run output format:
+
+```text
+## notion-to-tracker dry-run: <PRD title>
+
+### Planned hierarchy
+- Epic: <summary>
+  prd_section: "<heading text from the PRD that produced this epic>"
+  prd_anchor: "<first ~10 chars>...<last ~10 chars>"   # for selection_with_ellipsis; null if no specific section
+  - Story 1.1: <summary>
+    prd_section: "<heading or user-story line>"
+    prd_anchor: "<start>...<end>"
+    - Sub-task [<repo>]: <summary>
+      prd_section: "<heading or AC bullet>"
+      prd_anchor: "<start>...<end>"
+    - ...
+  - Story 1.2: ...
+
+### Per-ticket validation
+- <ticket-id>: PASS | FAIL — <count> failures
+  prd_section: "<heading text>"
+  prd_anchor: "<start>...<end>"   # mirrored from Planned hierarchy for caller convenience
+  failures:
+    - gate: <gate-id>
+      category: <category from validator>
+      product_relevant: <true|false>
+      what: <plain-language description from validator>
+      recommendation: <1–3 candidate resolutions from validator>
+
+### Verdict: PASS | FAIL
+### Total failures: <n>
+```
+
+`prd_anchor` and `prd_section` exist so downstream callers (notably `lisa:notion-prd-intake`) can post block-anchored Notion comments via `lisa:notion-access` operation `create-comment`. Build them as you parse the PRD: when you assign a planned ticket to a heading, user-story line, or AC bullet, capture the first ~10 and last ~10 characters of that section's text and emit them in the report. If a planned ticket genuinely doesn't trace to a specific section (cross-cutting infrastructure, derived sub-tasks), set both fields to `null` — the caller will fall back to a page-level comment.
+
+The `failures` array passes the validator's `Failure details` block through verbatim. Do not re-format `what` or `recommendation` here — those fields are already product-readable per the validator's contract, and re-summarizing risks losing concrete recommendations.
+
+The dry-run mode never writes to JIRA and never calls `mcp__atlassian__createJiraIssue`. It also never sets a Notion status — that is the orchestrating skill's responsibility.
+
+## Hard Rule: All Writes Go Through `lisa:tracker-write`
+
+**Every JIRA ticket created by this skill — every epic, story, and sub-task — MUST be created by invoking the `lisa:tracker-write` skill. Never call `mcp__atlassian__createJiraIssue`, `mcp__atlassian__editJiraIssue`, `mcp__atlassian__createIssueLink`, or any other Atlassian write tool directly from this skill or from any sub-agent it spawns.**
+
+`lisa:tracker-write` enforces gates this skill does not:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation
+- Explicit issue-link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Single-repo scope check on Bug / Task / Sub-task / Improvement
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+Bypassing `lisa:tracker-write` produces thin tickets that the rest of the lifecycle (triage, ticket-verify, journey, evidence) treats as broken. This is the most common failure mode this skill has had — calling `createJiraIssue` directly is a regression, not an optimization. The Atlassian read tools (`getJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssueRemoteIssueLinks`, `getAccessibleAtlassianResources`, `getJiraProjectIssueTypesMetadata`, `getVisibleJiraProjects`) ARE allowed for context gathering and the Phase 5.5 preservation gate.
+
+## Input
+
+A Notion PRD URL. The PRD is expected to have:
+- A main page with context, problems, and links to Epic sub-pages
+- Epic sub-pages with User Stories and functional/non-functional requirements
+- Comments/discussions on each page with engineering notes and product decisions
+
+## Configuration
+
+This skill reads project configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key) and operational E2E test config from environment variables. See the `config-resolution` rule for the full schema.
+
+### From `.lisa.config.json`
+
+This skill is a **PRD source** (Notion); destination tracker resolution is handled by `lisa:tracker-write` and `lisa:tracker-validate` internally — this skill does NOT read `tracker` directly. The relevant config for the source side:
+
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `notion.prdDatabaseId` | Notion database hosting PRDs | invoked without an explicit Notion page URL (batch / arg-less mode) |
+
+### From environment variables (E2E test config — operational, not tracker)
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `E2E_TEST_PHONE` | Test user phone number for verification plans | `0000000099` |
+| `E2E_TEST_OTP` | Test user OTP code | `555555` |
+| `E2E_TEST_ORG` | Test organization name | `Arsenal` |
+| `E2E_BASE_URL` | Frontend base URL for Playwright tests | `https://dev.example.io/` |
+| `E2E_GRAPHQL_URL` | GraphQL API URL for curl verification | `https://gql.dev.example.io/graphql` |
+
+If env vars are not available, ask the user to provide them explicitly before proceeding. Do not retrieve credentials from repository files or local agent settings.
+
+## Workflow
+
+### Phase 1: Fetch & Analyze the PRD
+
+1. **Fetch the main PRD page** by invoking `lisa:notion-access` via the Skill tool with operation `read-page` and `id: <PRD-page-id>`. The returned payload includes the page's properties and content blocks.
+2. **Identify all Epic sub-pages** from the content (look for child page references in the returned block tree).
+3. **Fetch all Epic pages** in parallel — for each child page ID, invoke `lisa:notion-access` operation `read-page`.
+4. **Fetch full comments** from every page by invoking `lisa:notion-access` operation `list-comments` with `block_id: <page-id>` (page comments and block-anchored comments alike). If `list-comments` is not in the access skill's dispatch table yet, surface that to the caller — comments are required for engineering-decision synthesis below.
+5. **Synthesize decisions and blockers** from the PRD content + all comments:
+   - Decisions already confirmed by the team (look for agreement in comment threads)
+   - Open questions that need product/engineering input
+   - Engineering comments (prefixed with "Engineering:" or wrench emoji) that identify technical constraints
+   - Cross-PRD dependencies (references to other features or shared infrastructure)
+
+### Phase 1.5: Extract Source Artifacts
+
+PRDs typically reference external design, UX, and data artifacts (Figma files, Lovable prototypes, Loom walkthroughs, screenshots, example payloads, Confluence pages). These MUST be preserved onto the resulting tickets — otherwise developers picking up a ticket lose the source of truth. This is the failure mode this step exists to prevent.
+
+1. **Scan the PRD main page, all Epic sub-pages, and every fetched comment thread** for:
+   - URLs to design/prototype tools (Figma, FigJam, Figma Make, Lovable, Framer, Penpot)
+   - URLs to recording/walkthrough tools (Loom, YouTube, Vimeo, Descript)
+   - URLs to collaborative docs (Google Docs/Slides/Sheets, Confluence, Notion peer pages)
+   - URLs to code sandboxes (CodeSandbox, StackBlitz, Replit, GitHub permalinks/gists)
+   - URLs to diagramming tools (Miro, Mural, Excalidraw, Mermaid Live, draw.io, Lucid)
+   - URLs to data/observability tools (Grafana, Datadog, Sentry, Metabase, Looker)
+   - Embedded images and file attachments on the page itself
+   - Fenced code blocks with example data (JSON, SQL, GraphQL, cURL request/response)
+
+2. **Classify each artifact and apply taxonomy rules** by invoking the `lisa:tracker-source-artifacts` skill. That skill is the single source of truth for: domains (`ui-design` / `ux-flow` / `data` / `ops` / `reference`), per-tool classification rules (Figma `/proto/` vs design, Lovable as `ux-flow`, Loom, screenshots), and coverage smells. Do not restate the rules here — invoke the skill so any drift in the rules propagates uniformly.
+
+3. **Build an `artifacts` map** keyed by domain. Each entry: `{ url, title, domain, source_page, source_page_url, classification_reason }`. The `classification_reason` makes disambiguation auditable ("Figma URL contains `/proto/` → ux-flow"). The `source_page` lets you trace each reference back to where it appeared in the PRD.
+
+4. **Surface coverage smells** as defined in `lisa:tracker-source-artifacts` §5 (zero artifacts, prototype-without-mock, mock-without-prototype, Lovable-without-business-rules). Record any detected smells on the epic.
+
+### Phase 1.6: Source Precedence & Conflict Resolution
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-source-artifacts` §3 and §4. Apply them during ticket synthesis: every conflict between artifacts must be recorded under `## Open Questions` on the affected ticket, never silently reconciled.
+
+The existing-component reuse expectation (mocks define visual intent, not implementation shortcut) is defined in `lisa:tracker-source-artifacts` §7. Encode it on every UI-touching story.
+
+### Phase 2: Codebase + Live Product Research
+
+Two complementary inputs ground PRD analysis: the **code** (what's there to reuse / extend) and the **live product** (what users see today). Skipping either produces tickets that misjudge the change.
+
+**2a. Codebase research.** If the session doesn't already have codebase context, explore the repos to understand what exists. Use Explore agents for repos not yet examined. Skip repos already explored in the current session.
+
+Key things to look for:
+- Existing entities/modules that overlap with the PRD
+- Patterns to reuse (auth decorators, S3 services, existing UI components)
+- Data model gaps the PRD requires (new fields, new entities)
+- The tech stack per repo (framework, ORM, UI library, deployment)
+
+**2b. Live product walkthrough.** If the PRD touches existing user-facing surfaces (modifies a screen, adds something next to existing functionality, fixes current behavior, re-styles an existing flow), invoke the `lisa:product-walkthrough` skill against `E2E_BASE_URL` using the test user from config. This grounds the ticket plan in what's actually shipped — design-vs-current-product divergence, reuse candidates, and behavioral surprises that the PRD didn't anticipate become inputs to ticket creation rather than discoveries during implementation.
+
+Skip 2b only when the work is purely backend with no user-visible surface, or affects a screen that does not yet exist in dev/prod.
+
+Walkthrough findings are attached to the originating Notion PRD as a comment ("Current product walkthrough — `<route>`") and inherited onto the resulting epic / stories under a `## Current Product` subsection.
+
+### Phase 3: Create Epics
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:tracker-write` in this phase. Instead, draft the epic spec (summary, description_body, artifacts) and validate it with `lisa:tracker-validate --spec-only`. Record the drafted spec (including a placeholder epic key like `DRY-RUN-EPIC-1`) for Phase 4 to use as parent references. In `dry_run: false` mode (default), proceed as described below.
+
+For each PRD epic, **invoke the `lisa:tracker-write` skill** (do not call `createJiraIssue` directly). Pass it everything it needs to enforce its quality gates:
+
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
+- `issue_type`: `Epic`
+- `summary`: epic title from the PRD
+- `description_body`: a draft of the 3-audience description containing:
+  - **Context / Business Value**: epic summary from the PRD, originating Notion URL, business outcome
+  - **Technical Approach**: cross-cutting integration points and constraints surfaced in Phase 2 codebase research
+  - List of user stories the epic contains
+  - Key decisions from comments (with attribution)
+  - Blockers and open questions
+  - Dependencies on other epics or PRDs
+  - A **Source Artifacts** section listing every artifact extracted in Phase 1.5 (grouped by domain)
+- `artifacts`: the full Phase 1.5 artifact list — every artifact, regardless of domain. The epic is the canonical hub, and anyone working on the epic or its descendants must be able to reach the full set from one place. No filtering at the epic level. `lisa:tracker-write` Phase 4c attaches them as remote links.
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: an Epic is a container, not a leaf work unit. Do NOT mark it build-ready — `lisa:tracker-write` must not be passed `status:ready` for an Epic, and the Epic's lifecycle state rolls up from its children. The build-ready label is applied only in Phase 5.
+
+Capture the returned epic key — Phase 4 needs it as the parent for stories.
+
+### Phase 4: Create Stories
+
+> **Mode guard**: In `dry_run: true` mode, do not invoke `lisa:tracker-write` in this phase. Instead, draft each story spec and validate it with `lisa:tracker-validate --spec-only`. Use placeholder keys (e.g. `DRY-RUN-STORY-1.1`) for any downstream references. In `dry_run: false` mode (default), proceed as described below.
+
+For each Epic, plan two kinds of stories:
+- **One "X.0 Setup" story** for data model and infrastructure prerequisites (new entities, migrations, new fields, infrastructure like S3 buckets or SQS queues)
+- **One story per user story** from the PRD (numbered to match the PRD)
+
+**Story naming convention**: Prefix the summary with a short code derived from the PRD title:
+- "Contract Upload" -> `[CU-1.1]`
+- "Squad Planning" -> `[SP-1.1]`
+- Use your judgment for other PRDs
+
+For each story, **invoke `lisa:tracker-write`** with:
+
+- `project_key`: resolved by `lisa:tracker-write` from `.lisa.config.json`
+- `issue_type`: `Story`
+- `epic_parent`: the Epic key captured in Phase 3 (mandatory — `lisa:tracker-write` rejects non-bug, non-epic tickets without an epic parent)
+- `summary`: prefixed per the naming convention above
+- `description_body`: a draft of the 3-audience description containing:
+  - **Context / Business Value**: the user story statement from the PRD
+  - **Technical Approach**: notes from engineering comments and Phase 2 codebase research
+  - **Acceptance Criteria** (Gherkin) derived from the functional requirements — `lisa:tracker-write` will reject prose-only acceptance criteria
+  - Blockers with recommendation + alternatives (if any), under `## Open Questions`
+  - A **Source Artifacts** section listing the artifacts inherited from the epic that match this story's scope (see propagation rules below)
+- `artifacts`: the Phase 1.5 artifacts filtered by domain per the inheritance table below — `lisa:tracker-write` Phase 4c attaches them as remote links
+- `priority`, `labels`, `components`, `fix_version`: as appropriate
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: a Story is a container (it has child Sub-tasks), not a leaf work unit. Do NOT mark it build-ready — never pass `status:ready` to `lisa:tracker-write` for a Story. Its lifecycle state rolls up from its Sub-tasks. The build-ready label is applied only in Phase 5.
+
+Capture each returned story key — Phase 5 needs it as the parent for sub-tasks.
+
+**Inherit domain-matching artifacts as story remote links**. For each story, the artifact set passed to `lisa:tracker-write` should be the Phase 1.5 artifacts whose domain matches the story's 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 a link, but they can't inherit one that wasn't attached. Classification mistakes are caught by the preservation gate in Phase 5.5 and by the human reviewing the final report.
+
+### Phase 5: Create Sub-tasks
+
+**Auto-split cross-repo work before delegation.** For each candidate sub-task, apply `lisa:task-decomposition` step 1.5: if the work touches more than one repo, split it into one sub-task per repo under the same parent Story (e.g., `[backend-api] Add field` + `[mobile-app] Display field`), and encode the producer-before-consumer ordering via dependencies. Work units that may span repos (Epic, Story, Spike) stay as planned; work units that must be single-repo (Bug, Task, Sub-task, Improvement) are split now. Splitting is this skill's responsibility — the validator's S10 gate is `product_relevant: false` because cross-repo failures are decomposition errors caught here, not product questions sent back to the PRD.
+
+Delegate sub-task creation to **parallel agents** (one per epic or batch of stories) for efficiency. **Every spawned agent must invoke `lisa:tracker-write` for each sub-task — no agent may call `createJiraIssue` directly.** This is non-negotiable; see the Agent Prompt Template at the bottom of this skill for the exact instructions to pass.
+
+Each sub-task MUST:
+1. **Be scoped to exactly ONE repo** — indicated in brackets in the summary: `[repo-name]`. `lisa:tracker-write` enforces single-repo scope on Sub-task; cross-repo sub-tasks will be rejected and must be split before delegation.
+2. **Include an Empirical Verification Plan** — real user-like verification, NOT unit tests, linting, or typechecking
+
+**Leaf-only build-ready (`leaf-only-lifecycle`)**: Sub-tasks are the **leaf work units** of the decomposition — they are the ONLY items in the hierarchy that receive the build-ready label. `lisa:tracker-write` applies `status:ready` here so downstream build intake (`lisa:tracker-build-intake`) claims the leaves and never the Epic or Stories. Apply `status:ready` to each Sub-task; never to its parent Story or Epic (Phases 3–4). `lisa:tracker-write` enforces the same invariant on the write side, so a Sub-task split into per-repo children (the cross-repo case above) carries build-ready on the children, not on any intermediate parent that gains child work.
+
+**Verification plan examples by stack:**
+- **Backend APIs**: curl GraphQL/REST calls with auth token, database queries, checking audit entries
+- **Frontend web**: Playwright browser tests (login with test user, navigate, interact, screenshot)
+- **Infrastructure**: `cdk synth` / `terraform plan` verification, CLI checks after deploy
+
+Use the test user credentials from config for all verification plans. The credentials are passed to `lisa:tracker-write` as the sign-in account so it can record them in the description per its own rules.
+
+For each sub-task, the spawned agent invokes `lisa:tracker-write` with `issue_type: "Sub-task"` and `parent` set to the Story key. The Story key is the parent — the epic relationship is inherited transitively.
+
+Sub-tasks inherit their parent story's artifacts by reference (the parent link). Do not pass the same artifact list to every sub-task — that creates noise. The only exception is when a sub-task depends on an artifact that the parent story doesn't (e.g., a sub-task spec'd from a specific Figma frame that the broader story doesn't cite) — in that case, pass the specific artifact in the `artifacts` parameter to `lisa:tracker-write`.
+
+### Phase 5.5: Artifact Preservation Gate (mandatory)
+
+Run the preservation gate defined in `lisa:tracker-source-artifacts` §8 against the artifacts extracted in Phase 1.5 and the tickets just created. Do NOT restate or modify the gate logic here — invoke the rules from `lisa:tracker-source-artifacts` so any rule change propagates uniformly.
+
+To run the gate, this skill must:
+
+1. Pull the remote links of every epic and story created in this run via `lisa:tracker-read (vendor-neutral; dispatches to jira-read-ticket or github-read-issue)`.
+2. Apply the §8 preservation matrix and verdict rules.
+3. If the gate fails: list each dropped/misrouted artifact (domain, title, source page, why it was dropped) and either re-attach via `lisa:tracker-write` (UPDATE mode) or stop and ask the human. Never silently proceed past a gate failure.
+4. If the gate passes: print the matrix compactly and proceed to Phase 6.
+
+This gate is not optional. Skipping it is the failure mode the architecture exists to prevent.
+
+### Phase 6: Report Results
+
+After all tickets are created, present a summary table to the user:
+- All Epics with keys and URLs
+- All Stories grouped by Epic
+- All Sub-tasks grouped by Story with repo tags
+- Repo distribution (how many tasks per repo)
+- **Artifact Preservation Matrix** — one row per artifact showing which epic/stories reference it
+- Blockers list with recommendations and alternatives
+- Cross-PRD dependencies
+
+### Phase 7: PRD Back-link
+
+> **Mode guard**: In `dry_run: true` mode, skip this phase entirely — no tickets exist to link.
+
+After Phase 6, invoke the `lisa:prd-backlink` skill to write a `## Tickets` section back into the source PRD. The section becomes the canonical anchor for the **Debrief** flow once the initiative ships, and gives any human reading the PRD months later a one-click path to every work item created from it.
+
+Invoke `lisa:prd-backlink` with:
+
+- `source_type: "notion"`
+- `source_ref`: the original PRD URL
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+
+If `lisa:prd-backlink` fails (PRD permission denied, Notion unreachable, source mutated mid-run), surface the error in the Phase 6 report rather than aborting — the tickets are already created and their value to the team is not blocked by the back-link write. Recommend the user re-run `lisa:prd-backlink` standalone once the source is reachable again.
+
+## Handling Ambiguities and Blockers
+
+When you encounter something the PRD + comments + codebase can't resolve:
+
+1. **Don't guess** — mark the ticket with a BLOCKER section
+2. **Include your recommendation** with rationale (what you'd pick and why)
+3. **List 2-3 alternatives** so the user/product can choose
+4. **State what's needed to unblock** (e.g., "Product decision on X", "Sync with Y on Z")
+
+Common blocker categories:
+- Missing data model decisions (field types, entity relationships)
+- Permission model unclear (who can view/edit)
+- UX decisions not finalized (display format, input mechanism)
+- Cross-team dependencies (shared infrastructure, coordinated rollouts)
+- Preset values not defined (enums, tags, labels)
+
+## Agent Prompt Template for Sub-task Creation
+
+When delegating to agents, provide this context. **The "MUST invoke jira-write-ticket" instruction is load-bearing — do not edit it out when adapting this template.**
+
+```text
+Create JIRA sub-tasks in the [PROJECT] project at [CLOUD_ID].
+
+CRITICAL: For each sub-task, invoke the `lisa:tracker-write` skill via the Skill tool.
+Do NOT call `mcp__atlassian__createJiraIssue` directly. The `lisa:tracker-write` skill
+enforces required quality gates (Gherkin acceptance criteria, 3-audience description,
+single-repo scope, sign-in/environment fields, post-create verification). Bypassing it
+produces broken tickets that downstream skills (triage, journey, evidence) cannot use.
+
+For each sub-task, invoke `lisa:tracker-write` with:
+- issue_type: "Sub-task"
+- parent: the parent story key
+- project_key: [PROJECT]
+- summary: prefixed with the repo in brackets, e.g. "[backend-api] Add audit log table"
+- description_body: a 3-section draft (Context / Technical Approach / Acceptance Criteria)
+- gherkin_acceptance_criteria: derived from the story's functional requirements
+- sign_in_account: [test user credentials from config — name + role + how to obtain]
+- target_environment: "dev"
+- empirical_verification_plan: real user-like verification (curl + auth token,
+  Playwright browser flow, CLI check after deploy) using the test credentials.
+  NOT unit tests, linting, or typechecking.
+
+Each sub-task must:
+1. Be scoped to ONE repo only — repo named in brackets in the summary
+2. Include the Empirical Verification Plan in the description
+3. Be created via `lisa:tracker-write`, not via direct MCP calls
+
+If `lisa:tracker-write` rejects a sub-task (cross-repo scope, missing Gherkin, missing
+sign-in, etc.), fix the input and re-invoke. Do NOT fall back to a direct
+`createJiraIssue` call to bypass the gate.
+
+Test user info: [credentials from config]
+
+[Then list all sub-tasks grouped by parent story with details]
+```
+
+## Cross-PRD Shared Infrastructure
+
+Track tickets that are shared across PRDs to avoid duplication.
+When a sub-task overlaps with an existing ticket, reference it instead of creating a duplicate.
+Search JIRA for existing tickets in the project before creating new ones for shared infrastructure.

package/plugins/lisa-copilot/skills/notion-write-prd/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: notion-write-prd
+description: "Creates or idempotently updates a PRD as a page in the configured Notion PRD database, setting the lifecycle Status property to the draft value by default (or the ready value when initial_role is ready so lisa:notion-prd-intake auto-claims it). The Notion PRD-source writer behind lisa:prd-source-write. Dedupes by a stable marker embedded in the page (matched by marker, never by title). All Notion access goes through lisa:notion-access — never call the Notion API or MCP directly."
+allowed-tools: ["Skill", "Bash"]
+---
+
+# Write Notion PRD: $ARGUMENTS
+
+Create (or update) a PRD page in the configured Notion PRD database. Invoked by
+`lisa:prd-source-write` when `source = notion`; do not call directly from a vendor-neutral caller.
+**All Notion operations go through `lisa:notion-access`** (the access chokepoint) — never curl the
+Notion API or call a `mcp__*notion*` tool yourself.
+
+`$ARGUMENTS` carries the `lisa:prd-source-write` spec: `title`, `body` (full PRD markdown),
+`initial_role` (`draft` | `ready`, default `draft`), `dedupe_key`, `marker`, optional `source_ref`.
+
+## Phase 1 — Resolve database + Status vocabulary
+
+```bash
+read_g() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv:-$2}}"; }
+PRD_DB=$(read_g '.notion.prdDatabaseId' '')
+[ -z "$PRD_DB" ] && { echo "Error: notion.prdDatabaseId not set in .lisa.config.json."; exit 1; }
+STATUS_PROP=$(read_g '.notion.statusProperty' 'Status')
+# Resolve the FULL PRD Status vocabulary from config (never hard-code) so the past-ready check is
+# correct even when a project renamed any Status value.
+DRAFT=$(read_g '.notion.values.draft' 'Draft')
+READY=$(read_g '.notion.values.ready' 'Ready')
+IN_REVIEW=$(read_g '.notion.values.in_review' 'In Review')
+BLOCKED=$(read_g '.notion.values.blocked' 'Blocked')
+TICKETED=$(read_g '.notion.values.ticketed' 'Ticketed')
+SHIPPED=$(read_g '.notion.values.shipped' 'Shipped')
+VERIFIED=$(read_g '.notion.values.verified' 'Verified')
+# "Progressed past ready" set (never down-rank): the resolved in_review/blocked/ticketed/shipped/verified.
+PROGRESSED=("$IN_REVIEW" "$BLOCKED" "$TICKETED" "$SHIPPED" "$VERIFIED")
+```
+
+Resolve the target Status value from `initial_role`: `ready` → `$READY`, otherwise `$DRAFT`.
+
+## Phase 2 — Dedupe by marker (search before create)
+
+The `marker` is embedded in the page (as the first body block). Find an existing PRD page in the DB
+carrying it — match the marker, **never** the title:
+
+1. `lisa:notion-access` `operation: search query: "<marker>"` (Notion indexes page content).
+2. Filter results to pages whose parent is `$PRD_DB`. If `source_ref` was passed, target that page
+   directly and skip the search.
+3. If a matching page is found, this is an **update** — reuse it. If none is found, **create**.
+   Note: Notion search is eventually consistent; if a just-created page isn't found yet, the marker
+   still lives in the page so a later run will dedupe — surface "dedupe degraded (search lag)" rather
+   than silently creating a duplicate when uncertain.
+
+## Phase 3 — Create or update
+
+**Markdown → Notion blocks (conversion boundary).** Convert the PRD markdown to Notion block objects:
+`#`/`##`/`###` → `heading_1/2/3`, paragraphs → `paragraph`, `-`/`*` → `bulleted_list_item`, `1.` →
+`numbered_list_item`, fenced code → `code`. The Notion API caps a single request at **100 blocks**
+and ~2000 characters of rich text per block: split long paragraphs across blocks, and if the PRD
+exceeds 100 blocks, create the page with the first ≤100 blocks then add the remainder with batched
+`operation: append-blocks` calls (≤100 each). When the MCP substrate is active, `create-page` may
+accept the markdown content directly (it performs this conversion) — prefer that; the explicit block
+conversion is the curl-substrate path.
+
+**Marker + usage-ledger preservation (both paths).** The page must always carry **exactly one**
+marker. On CREATE the marker is the first body block; on UPDATE never remove it. Never write a markerless body. Never write a markerless page. If the existing page content already contains the canonical managed `## Lisa Usage` section, preserve that section when regenerating the page body unless the caller intentionally supplied an updated canonical section; use the shared `usage-accounting` serializer/merge path rather than freehand block edits to ledger rows.
+
+**CREATE:**
+
+1. Build the page body as Notion blocks per the conversion above: the **first block is the marker**
+   (a paragraph/callout containing `<!-- $MARKER -->`), then the converted PRD blocks.
+2. Invoke `lisa:notion-access` `operation: create-page` with:
+   ```json
+   { "parent_database_id": "<PRD_DB>",
+     "properties": { "<title-prop>": { "title": [{ "text": { "content": "<TITLE>" } }] },
+                     "<STATUS_PROP>": { "status": { "name": "<ROLE_VALUE>" } } },
+     "children": [ <marker block>, <PRD body blocks> ] }
+   ```
+   Use the DB's actual title property name (read it via `operation: read-database id: <PRD_DB>` if
+   unknown) and the correct property type for `$STATUS_PROP` (`status` vs `select`).
+3. Capture the returned page id + URL.
+
+**UPDATE** (existing page or `source_ref`):
+
+1. Set the Status to the resolved role via `lisa:notion-access` `operation: write-page payload: { "id": "<page-id>", "properties": { "<STATUS_PROP>": { "status": { "name": "<ROLE_VALUE>" } } } }` — **unless** the page's current Status is in the resolved `${PROGRESSED[@]}` set (already past `ready`), in which case leave the Status and report `reused (already past ready)`.
+2. Refresh the canonical spec, not append-only notes: keep the existing marker block, then make the
+   managed PRD body current — archive the previously generated body blocks below the marker
+   (`operation: archive-page` is page-level, so for blocks delete via the blocks API through
+   `notion-access` or, where block deletion isn't available, replace their text in place) and
+   `operation: append-blocks` the regenerated blocks. Do not duplicate the whole spec as a dated
+   note, and never drop the marker or an existing managed `## Lisa Usage` section.
+
+## Phase 4 — Return
+
+```yaml
+ref: "<notion-page-id>"
+url: "<page url>"
+role: draft | ready          # (or the page's current Status role when reused past ready)
+marker: "<MARKER>"
+outcome: created | reused
+```
+
+## Rules
+
+- All access via `lisa:notion-access`; never touch the Notion API/MCP directly.
+- Match dedupe by marker, never by title.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
+- Never down-rank a PRD whose Status is already past `ready`.
+- Resolve the Status vocabulary from config (`notion.statusProperty`, `notion.values.*`) — never
+  hardcode value names.

package/plugins/lisa-copilot/skills/performance-review/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: performance-review
+description: "Performance review methodology. N+1 queries, inefficient algorithms, memory leaks, missing indexes, unnecessary re-renders, bundle size issues. Evidence-based recommendations."
+---
+
+# Performance Review
+
+Identify bottlenecks, inefficiencies, and scalability risks in code changes.
+
+## Analysis Process
+
+1. **Read affected files** -- understand data access patterns, algorithmic complexity, and resource usage
+2. **Identify N+1 queries** -- look for ORM calls inside loops, missing eager loading, unbatched database access
+3. **Check algorithmic complexity** -- nested loops over collections, repeated linear scans, unnecessary sorting
+4. **Evaluate memory usage** -- large object allocations, unbounded caches, retained references, memory leaks
+5. **Review database patterns** -- missing indexes, full table scans, unoptimized joins, excessive round trips
+6. **Check caching** -- missing cache layers, cache invalidation issues, redundant computations
+7. **Assess bundle/payload size** -- unnecessary imports, large dependencies, uncompressed responses
+8. **Review rendering performance** -- unnecessary re-renders, missing memoization, layout thrashing (frontend)
+
+## Output Format
+
+Structure findings as:
+
+```
+## Performance Analysis
+
+### Critical Issues
+Issues that will cause noticeable degradation at scale.
+
+- [issue] -- where in the code, why it matters, estimated impact
+
+### N+1 Query Detection
+| Location | Pattern | Fix |
+|----------|---------|-----|
+| file:line | Description of the N+1 | Eager load / batch / join |
+
+### Algorithmic Complexity
+| Location | Current | Suggested | Why |
+|----------|---------|-----------|-----|
+| file:line | O(n^2) | O(n) | Description |
+
+### Database Concerns
+- Missing indexes, unoptimized queries, excessive round trips
+
+### Memory Concerns
+- Unbounded growth, large allocations, retained references
+
+### Caching Opportunities
+- Computations or queries that could benefit from caching
+
+### Recommendations
+- [recommendation] -- priority (critical/warning/suggestion), estimated impact
+```
+
+## Common Patterns to Flag
+
+### N+1 Queries
+```typescript
+// Bad: N+1 -- one query per user inside loop
+const users = await userRepo.find();
+const profiles = await Promise.all(users.map(u => profileRepo.findOne({ userId: u.id })));
+
+// Good: Single query with join or batch
+const users = await userRepo.find({ relations: ["profile"] });
+```
+
+### Unnecessary Re-computation
+```typescript
+// Bad: Recomputes on every call
+const getExpensiveResult = () => heavyComputation(data);
+
+// Good: Compute once, reuse
+const expensiveResult = heavyComputation(data);
+```
+
+### Unbounded Collection Growth
+```typescript
+// Bad: Cache grows without limit
+const cache = new Map();
+const get = (key) => { if (!cache.has(key)) cache.set(key, compute(key)); return cache.get(key); };
+
+// Good: LRU or bounded cache
+const cache = new LRUCache({ max: 1000 });
+```
+
+## Rules
+
+- Focus on the specific changes proposed, not a full performance audit of the entire codebase
+- Flag only real performance risks -- do not micro-optimize code that runs once at startup
+- Quantify impact where possible (O(n) vs O(n^2), number of database round trips, estimated payload size)
+- Distinguish between critical issues (will degrade at scale) and suggestions (marginal improvement)
+- If the changes have no performance implications, report "No performance concerns" and explain why
+- Always consider the data scale -- an O(n^2) over 5 items is fine, over 10,000 is not

package/plugins/lisa-copilot/skills/plan/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: plan
+description: "Decompose a single PRD or specification into ordered work items in the configured tracker. Vendor-agnostic — the source can be a Notion PRD URL, a Confluence PRD URL, a Linear project URL, a GitHub Issue URL, an existing JIRA epic key, a markdown file, or a free-form description; the destination tracker is whatever the project is configured to use via `.lisa.config.json` `tracker` (JIRA, GitHub Issues, or Linear). Single-PRD mode only — for batch scanning of all Ready PRDs in a queue, use the lisa:intake skill."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Plan: $ARGUMENTS
+
+Decompose the PRD/spec at `$ARGUMENTS` into ordered work items with acceptance criteria, dependencies, and recommended skills/agents.
+
+## Orchestration: agent team
+
+If you are NOT already operating inside an agent team (no prior successful team-creation or subagent-delegation tool call in this session, not spawned into a team context), the very first thing you do is establish team orchestration.
+
+Use the team tool for the current runtime:
+
+- Claude: use `TeamCreate`. If `TeamCreate` has not been loaded yet, first use `ToolSearch` with `query: "select:TeamCreate"` to load its schema.
+- Codex: do not call `TeamCreate`; Codex does not expose that Claude tool. Use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation. Treat the first successful `spawn_agent` call as establishing team orchestration.
+- Other runtimes: use the current runtime's tool-discovery mechanism to discover and call the appropriate multi-agent/team tool.
+
+If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally.
+
+Until the team is established, the first Codex teammate has been spawned, or the no-team fallback has been declared, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Reading the PRD, exploring the code, fetching context — all of those are tasks for the team you are about to create, not for the lead session before orchestration exists.
+
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT create a second team — many harnesses reject double-creates — and do NOT collapse the nested flow into a single inline worker. A nested team-first flow must still bring in the specialists it requires by adding them to the existing team, not by doing the work itself:
+
+- **Claude:** teams are flat and only the lead can add named teammates, so do NOT call `Agent` with a `name` from a teammate (the harness rejects it: *"Teammates cannot spawn other teammates — the team roster is flat"*). Send the team lead a message naming the specialist teammate(s) this flow needs, their task assignments, and completion criteria, then coordinate through the shared task list until they finish. An anonymous subagent (`Agent` with `name` omitted) is permitted only for bounded one-shot work whose result returns directly to you — it is not a substitute for the required lifecycle specialists.
+- **Codex:** do NOT call `TeamCreate`. If the lead/root agent is addressable (you were given its id/handle), send it a request to `multi_agent_v1.spawn_agent` the specialist agent(s), including each agent's prompt, ownership, and expected result. If no lead handle exists but `spawn_agent` is available to you, spawn only the bounded specialist agent(s) this flow needs, `wait_agent` for their results, and relay those results upward to the parent/lead.
+
+Treat the first successful lead-spawn request (or, on the Codex fallback, the first specialist spawn) as preserving team orchestration. Never satisfy a team-first lifecycle flow by doing all the work inline.
+
+## Source dispatch
+
+Detect the input type from `$ARGUMENTS` and route to the appropriate source skill:
+
+| If `$ARGUMENTS` is... | Hand off to |
+|------------------------|-------------|
+| A Notion **page** URL or page ID (single PRD) | `lisa:notion-to-tracker` (with the PRD URL; runs the full pipeline: extract artifacts → walk live product → validate → write tickets → coverage audit) |
+| A Notion **database** URL or database ID | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a database. |
+| A Confluence **page** URL containing `/wiki/spaces/<KEY>/pages/<ID>/...` (single PRD) | `lisa:confluence-to-tracker` (with the PRD URL; same full pipeline as the Notion path) |
+| A Confluence **space** URL (`/wiki/spaces/<KEY>` with no `/pages/...`) | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a space. |
+| A Linear **project** URL (`https://linear.app/<workspace>/project/<slug>-<id>`) | `lisa:linear-to-tracker` (with the project URL; same full pipeline as the Notion / Confluence paths). The Linear project's description, attached documents, and sub-issues form the PRD body. |
+| A Linear **workspace** URL (`https://linear.app/<workspace>` with no `/project/...`) or **team** URL | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a workspace or team. |
+| A JIRA ticket ID/URL of an Epic (existing epic *is* the spec) | `lisa:jira-agent` (read epic, decompose into stories/sub-tasks) |
+| A Linear Project URL of a Project that *is* the spec, when destination tracker = `linear` | `lisa:linear-agent` (read project, decompose into Issues / sub-Issues). Symmetric counterpart to the JIRA-Epic and GitHub-Epic branches. |
+| A GitHub **issue** URL (`https://github.com/<org>/<repo>/issues/<number>`) or `<org>/<repo>#<number>` token (single PRD) | `lisa:github-to-tracker` (with the issue ref; runs the full pipeline: extract artifacts → walk live product → validate → write tickets → coverage audit). The destination tracker is read from `.lisa.config.json` `tracker`. |
+| A GitHub **repository** URL or `<org>/<repo>` token (no issue number) | Stop and report — single-PRD mode only. Direct the caller to `lisa:intake` for batch scanning of a GitHub repo. |
+| A GitHub Issue URL of a build-side ticket (`type:Epic` / `type:Story` / etc., not `prd-*`-labelled) when `tracker = github` | `lisa:github-agent` (read issue, decompose into Sub-tasks). Symmetric counterpart to the JIRA-Epic branch above. |
+| 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 `lisa:research` skill first to produce one.
+
+## Flow
+
+Execute the **Plan** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gates, sub-flows, output structure). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+## Output
+
+Work items in the configured tracker (JIRA, GitHub Issues, or Linear, per `.lisa.config.json` `tracker`) with acceptance criteria, dependencies, and recommended skills/agents per item. Ordered by dependency. Before finishing, route usage writes through `lisa:usage-accounting`: record the Plan run as a direct entry on the source PRD/spec artifact, attach a plan usage entry (or an explicit `source: unavailable` entry with nullable token/cost fields) to each created work item, and refresh the PRD rollup after `lisa:prd-backlink` regenerates the `## Tickets` child refs. Do not invent plan-specific ledger formats or omit missing usage silently. If the specification cannot be decomposed without further clarification, stop and report what is missing.