@codyswann/lisa 2.119.0 → 2.121.0

package/plugins/lisa-copilot/skills/linear-write-issue/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: linear-write-issue
+description: "Creates or updates a Linear work item — Project (Epic), Issue (Story), or sub-Issue (Sub-task) — following organizational best practices. Polymorphic: dispatches internally on issue_type to save_project (Epic) or save_issue (Story / Sub-task). Enforces description quality (three audiences), Gherkin acceptance criteria, project-as-parent for Stories, parentId for Sub-tasks, explicit relationship discovery (blocks / is blocked by / relates to / duplicates), labels, components-as-labels, project milestones for fix versions, native priority and estimate fields, and Validation Journey. Rejects thin items — use this skill any time a Linear work item is created or significantly edited."
+allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_team", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment"]
+---
+
+# Write Linear Work Item: $ARGUMENTS
+
+Create or update a Linear work item — Project (for Epics), Issue (for Stories), or sub-Issue (for Sub-tasks) — with all required relationships, metadata, and quality gates. Every section below is mandatory. Thin items are rejected.
+
+Repository name for scoped comments: `basename $(git rev-parse --show-toplevel)`.
+
+## Configuration
+
+This skill reads configuration from `.lisa.config.json` (with `.lisa.config.local.json` overriding per key). Required keys:
+
+- `linear.workspace` — Linear workspace slug
+- `linear.teamKey` — Linear team key (e.g. `ENG`); the team owns the destination items
+
+If either is missing, stop and report — never invent values.
+
+## Polymorphic dispatch
+
+Linear's data model maps Epic / Story / Sub-task to **different entity types**. This skill dispatches on `issue_type`:
+
+| `issue_type` | Linear entity | MCP write tool | Parent field |
+|--------------|---------------|----------------|--------------|
+| `Epic` | **Project** | `mcp__linear-server__save_project` | (none — Projects are top-level within a team) |
+| `Story` / `Task` / `Improvement` | **Issue** | `mcp__linear-server__save_issue` | `projectId` (the Epic Project) |
+| `Sub-task` | **sub-Issue** | `mcp__linear-server__save_issue` | `parentId` (the Story Issue) |
+| `Bug` | **Issue** | `mcp__linear-server__save_issue` | `projectId` if part of an Epic; else top-level |
+| `Spike` | **Issue** | `mcp__linear-server__save_issue` | `projectId` if part of an Epic; else top-level |
+
+Status workflow uses **labels** (`status:ready`, `status:in-progress`, `status:on-dev`, `status:done`) for portability across teams — Linear's per-team workflow state names vary, but labels are workspace-scoped and stable. Native Linear `state` is set to the team's default `Todo` state on create.
+
+## Phase 1 — Resolve Intent
+
+Determine from `$ARGUMENTS` and context whether this is a CREATE or UPDATE:
+
+- **CREATE**: no existing identifier provided.
+- **UPDATE**: identifier provided (`<TEAM>-<n>` for Issue, project slug + short-id for Project) — call `/linear-read-issue <ref>` first to load the full current state. Never overwrite without reading.
+
+Resolve the team ID for `linear.teamKey` via `mcp__linear-server__list_teams({query: <teamKey>})`. Cache it.
+
+## Phase 2 — Gather Required Inputs
+
+Required fields (stop and ask if missing — never invent values):
+
+| Field | Required For | Notes |
+|-------|--------------|-------|
+| `team_key` | CREATE | From `linear.teamKey` config; required for both Project and Issue creation |
+| `issue_type` | CREATE | One of: Epic, Story, Task, Bug, Spike, Sub-task, Improvement |
+| Summary | CREATE, UPDATE | One line, imperative voice, under 100 chars |
+| Description | CREATE, UPDATE | Multi-section markdown — see Phase 3 |
+| Project parent (for Story / Task / Bug / Spike / Improvement when part of an Epic) | non-Epic, non-Sub-task in Epic context | Linear Project ID — the Epic |
+| Sub-task parent | Sub-task | Linear Issue ID — the Story |
+| Priority | CREATE | Native Linear priority: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low |
+| Acceptance criteria | Story, Task, Bug, Sub-task, Improvement | Gherkin — see Phase 3 |
+| Validation Journey | Runtime-behavior changes | Delegate to `/linear-add-journey` |
+| Target backend environment | Runtime-behavior changes | `dev` / `staging` / `prod`; recorded in description (Phase 3). Skip only for doc/config/type-only items. |
+| Sign-in account / credentials | Items that touch authenticated surfaces | Name the account (or source — 1Password item, env var, seeded fixture) and role; recorded in description. Omit when sign-in is not required. |
+| Single-repo scope | Bug, Task, Sub-task | These types MUST cover one repo only. If the work crosses repos, split it before creating. Epic / Spike / Story may span repos. |
+
+Optional but recommended: assignee, estimate (story points), labels, project milestone (fix-version equivalent), cycle.
+
+## Phase 3 — Description Quality
+
+Linear descriptions are markdown (NOT Jira wiki markup — no `h2.` headings, use `##` instead). The description MUST address three audiences. Reject and rewrite if any are missing.
+
+```markdown
+## Context / Business Value
+[Why this matters. Stakeholder-facing. Concrete user impact or business outcome.
+ Link to the originating Slack thread, Notion doc, incident, or customer report.]
+
+## Technical Approach
+[Developer-facing. Integration points, impacted modules, data model implications,
+ relevant tradeoffs. Not a full design doc — a pointer for someone picking it up.]
+
+## Acceptance Criteria
+1. Given <precondition>
+   When <action>
+   Then <observable outcome>
+2. Given <precondition>
+   When <action>
+   Then <observable outcome>
+
+## Out of Scope
+[Explicit list of what this item does NOT cover. Forces scope discipline.]
+
+## Target Backend Environment
+[Required when the item changes runtime behavior. One of: dev / staging / prod.
+ Skip section entirely for doc-only, config-only, or type-only items.]
+
+## Sign-in Required
+[Include this section ONLY if the work touches authenticated surfaces.
+ Specify: the account/role to sign in as, where to get the credentials
+ (1Password item name, env var, seeded fixture), and any MFA/SSO notes.
+ Omit the section entirely when sign-in is not required.]
+
+## Repository
+[Required for Bug / Task / Sub-task. Name the single repo this item covers.
+ If the work spans repos, this issue type is wrong — split into per-repo
+ Tasks/Sub-tasks under a parent Story or Epic.]
+
+## Validation Journey
+[Delegate to /linear-add-journey if the item changes runtime behavior.
+ Skip only for doc-only, config-only, or type-only items.]
+```
+
+Rules:
+- Every acceptance criterion uses Given/When/Then. No vague "should work" language.
+- Every criterion is independently verifiable (UI, API, data, or performance check).
+- If the item is a Bug, include reproduction steps, expected vs. actual behavior, and environment.
+- If the item is a Spike, include the question being answered and the definition of done (decision doc, prototype, or findings).
+- If sign-in is required, the implementer must be able to sign in from the description alone — never assume they will guess the account or hunt for credentials.
+
+## Phase 4 — Relationship Discovery (Mandatory)
+
+Before creating or updating, find candidate relationships. Do NOT skip — this is the step agents most often omit.
+
+### 4a. Project Parent (Epic-equivalent)
+
+If the item is **not an Epic** and **not a top-level Bug/Spike**, it MUST have a parent context:
+
+- **Story / Task / Improvement** → must have a `projectId` (the Epic Project) set.
+- **Sub-task** → must have a `parentId` (the Story Issue) set.
+
+If the parent is explicitly provided, use it. Otherwise:
+
+1. Search active Projects in the team:
+   ```text
+   mcp__linear-server__list_projects({team: <teamKey>, state: ["backlog", "planned", "started"]})
+   ```
+   Match on keywords from the summary and description.
+2. If no matching Project exists, stop and ask the human to create or pick one. Do NOT orphan the item.
+
+### 4b. Related Items
+
+Relationship discovery is **mandatory** on every create and every update — never declare "no related work" without doing both searches below and recording their outcomes on the item.
+
+**Search 1: local git history** (catches PRs / commits that touched the same area but were never linked):
+
+```bash
+git log --all --oneline --grep="<keyword>"
+git log --all --oneline -- <path-or-glob>
+git log --since=90.days --oneline -- <path-or-glob>
+```
+
+If the git search surfaces a PR or commit that relates to this work, capture the PR URL — it becomes a remote link (Phase 4c) and may also point to a sibling item worth linking.
+
+**Search 2: Linear MCP** (catches open and recently-closed items):
+
+```text
+# Open items in the same Project
+mcp__linear-server__list_issues({project: <projectId>, state_type: ["unstarted", "started"]})
+
+# Open items with overlapping keywords (workspace-wide)
+mcp__linear-server__list_issues({query: "<keyword>", state_type: ["unstarted", "started"]})
+
+# Items with shared labels
+mcp__linear-server__list_issues({label: "<label>", updatedAt: ">-30d"})
+
+# Recently closed items in the same Project
+mcp__linear-server__list_issues({project: <projectId>, state_type: ["completed", "canceled"], updatedAt: ">-30d"})
+```
+
+**Record the outcome.** Add a `## Relationship Search` subsection (or a comment if updating) listing the queries you ran and what they returned. If the searches yielded nothing, write that explicitly — "Searched git history for `<keywords>` and Linear for project=`X`, label=`Y`; no related work found." An item with zero relations and no documented search is rejected.
+
+For each candidate, classify the relationship:
+
+| Relation Type | When to Use |
+|---------------|-------------|
+| `blocks` | This item must ship before the linked item can proceed |
+| `blocked_by` | The linked item must ship before this one can proceed |
+| `relates_to` | Shared context, no ordering constraint |
+| `duplicates` | This item already exists — close one as duplicate |
+
+Linear native relations are set on the Issue via `save_issue`'s `relations` field (or via a paired `save_issue_relation` call if available in the MCP). For Project-level (Epic) relationships, capture them in the description under `## Related Projects` since Linear doesn't model relations between Projects natively.
+
+### 4c. Remote Links
+
+Identify and attach (Linear stores attachments / links on the Issue or in description body):
+
+- GitHub PRs, branches, or commits related to this work
+- Confluence pages (design docs, RFCs, runbooks)
+- Dashboards (Grafana, Datadog, Sentry issue)
+- Incident items (PagerDuty, Statuspage)
+- **Source artifacts from the originating PRD / parent Project**: classify and inherit per the rules in `lisa:tracker-source-artifacts` (invoke that skill if you haven't loaded the rules in this session). Enumerate the parent Project's links and inherit the ones whose domain matches this item's scope (UI → `ui-design` + `ux-flow`; backend → `data`; infra → `ops`; always inherit `reference`). Never assume a developer will walk up to the Project to find design context — attach it here.
+
+If the item was generated from a PRD (by `lisa:notion-to-tracker` or similar) and the parent Project has no source artifacts, surface that as a smell and ask whether artifacts were missed during extraction before proceeding.
+
+### 4d. Source Precedence (must appear on the item)
+
+Source precedence rules and cross-axis conflict handling are defined in `lisa:tracker-source-artifacts` §3 and §4. When an item carries both design artifacts and a description, record the precedence explicitly in the description (under Technical Approach or a dedicated `## Source Precedence` subsection) so the implementer doesn't silently reconcile conflicts. Cross-axis conflicts go under `## Open Questions` as BLOCKER items.
+
+For UI-touching items, include the existing-component reuse expectation per `lisa:tracker-source-artifacts` §7.
+
+### 4e. Live Product Walkthrough Findings (UI-touching items)
+
+If the item modifies an existing user-facing surface, a `lisa:product-walkthrough` should already have been run upstream. Inherit its findings under a `## Current Product` subsection in the description so the implementer sees what's shipped today before changing it. If the upstream skill skipped the walkthrough but this item clearly modifies an existing surface, invoke `lisa:product-walkthrough` here before proceeding.
+
+## Phase 5 — Set Metadata
+
+Before create/update, verify each field is populated where applicable:
+
+- **Labels**: include `status:ready` for a new **leaf** work unit (Bug / Task / Sub-task / Improvement with no child work) per `leaf-only-lifecycle`, **unless `build_ready: false`** (see the Build-ready control input below); component labels (`component:<name>`); status / priority labels are NOT redundant with native fields — labels exist for portability and downstream queries. A container (Epic Project / Story with sub-issues / Spike) never receives `status:ready`.
+- **Native priority field**: 0–4 per Linear's scale; explicit, not "unset".
+- **Native estimate**: per Linear's team-configured estimate scale (often 0–8 Fibonacci); skip for Epic / Spike.
+- **ProjectMilestone**: when the team uses dated milestones, set the milestone on the Project (Epic) or on the Issue (when an Issue belongs to a milestone).
+- **Cycle**: only if actively in a cycle.
+- **Assignee**: leave unset if unknown rather than auto-assigning.
+
+For Bug / Task / Sub-task, ensure the summary is prefixed with `[<repo-name>]`.
+
+### Build-ready control input (`build_ready`)
+
+`build_ready` is an optional write-control input (default: **omitted**). It governs whether a **leaf** work unit's `status:ready` label is applied on create. It never overrides `leaf-only-lifecycle` — a container is never stamped build-ready regardless of `build_ready`. "Not build-ready" is not a special state: the Issue is still created with Linear's default native `Todo` state; it just lacks the `status:ready` **label** the build lifecycle keys off, so a human can promote it later.
+
+- **Omitted** → current behavior: a leaf work unit receives `status:ready`. Preserves what every existing caller (`lisa:plan`, the `*-to-tracker` skills) relies on.
+- **`build_ready: false`** → create the leaf **without** the `status:ready` label, so it sits in the backlog for a human to review and promote into the queue.
+- **`build_ready: true`** → ensure the leaf carries `status:ready` so `lisa:intake` / `lisa:linear-build-intake` auto-picks it up.
+
+## Phase 5.5 — Validate (Pre-write Gate)
+
+Before any write, invoke `lisa:linear-validate-issue` with the full proposed spec assembled from Phases 2 / 3 / 4 / 5. Pass it as a YAML block per the `lisa:linear-validate-issue` schema, including `runtime_behavior_change`, `authenticated_surface`, and `artifacts_attached` flags so the right gates run.
+
+The validator is the **single source of truth** for what makes a valid Linear work item. The same gates are used by `lisa:linear-to-tracker` dry-run, by `lisa:linear-verify` post-write, and here. Do not re-implement gate logic in this skill.
+
+If the validator reports `FAIL`:
+- Surface the failure list and the per-gate remediation to the user.
+- Do NOT proceed to Phase 6. Fix the spec (or stop and ask the human) and re-run validation.
+- Never call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` while the validator's verdict is FAIL.
+
+If the validator reports `PASS`, continue to Phase 6.
+
+## Phase 6 — Create or Update
+
+### CREATE — Epic (Project)
+
+1. Resolve any required Project labels (`prd-ticketed`, etc.) via `mcp__linear-server__list_project_labels` (create via `create_project_label` if missing).
+2. Call `mcp__linear-server__save_project` with: `name` (summary), `description` (markdown), `teamIds: [<teamId>]`, `labelIds`, `priority` (Linear Project priority is also 0–4), `state` (default `backlog`), milestones if dated.
+3. Capture the returned Project ID and slug — Phase 4 children need these.
+4. If the Project is the parent for downstream Stories, record the ID for `lisa:linear-to-tracker` Phase 4 to use.
+
+### CREATE — Story / Task / Bug / Spike / Improvement (Issue with projectId)
+
+1. Resolve any required Issue labels (`component:<name>`, `prd-intake-feedback` only if this is a sentinel issue, etc.) via `mcp__linear-server__list_issue_labels` (create via `create_issue_label` if missing). Include `status:ready` in `labelIds` only for a **leaf** work unit and only when `build_ready` is not `false` (per the Build-ready control input) — omit it for a container, and for a `build_ready: false` leaf which then waits in the backlog for a human to promote it.
+2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (summary), `description` (markdown), `projectId` (the Epic Project), `priority` (0–4), `estimate`, `labelIds`, `assignee` if known.
+3. Capture the returned identifier (e.g. `ENG-123`) — Phase 4 sub-tasks need it as `parentId`.
+4. Add relationships from Phase 4b via `save_issue` (relations field) or paired relation calls.
+5. If the item changes runtime behavior, invoke `lisa:linear-add-journey` to append the Validation Journey section.
+
+### CREATE — Sub-task (Issue with parentId)
+
+1. Resolve labels as above.
+2. Call `mcp__linear-server__save_issue` with: `team` (teamId), `title` (`[<repo>] <summary>` prefix is mandatory), `description` (markdown), `parentId` (the Story Issue ID), `projectId` (inherit from parent), `priority`, `estimate`, `labelIds`.
+3. Capture identifier.
+4. Add relationships via Phase 4b.
+
+### UPDATE
+
+1. Call `mcp__linear-server__save_project` or `mcp__linear-server__save_issue` with **only the fields being changed**. Do NOT resend fields that weren't in the change set — Linear treats the call as a full overwrite of the listed fields.
+2. Preserve description sections you are not editing — re-read via `/linear-read-issue` first, including any existing canonical managed `## Lisa Usage` section unless the caller intentionally supplied an updated canonical section. Use the shared `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
+
+## Phase 7 — Verify
+
+Call the `lisa:linear-verify` skill on the resulting item. `lisa:linear-verify` fetches the live item and runs `lisa:linear-validate-issue` against it — same gates as Phase 5.5, but applied to what Linear actually stored. If it reports failures, fix them before returning. Do not report success on an item that fails verify.
+
+## Phase 8 — Announce
+
+Post a creation comment via `mcp__linear-server__save_comment` (on the Issue, or on a sentinel issue under the Project for Epic-level announcements) with:
+
+- `[<repo>]` prefix if the item is repo-scoped
+- Who the item is assigned to (if known)
+- The relationships that were set (`blocks`, `blocked_by`, `relates_to`) with Linear identifiers
+- Any remote PRs attached
+
+Skip this step only on UPDATE when no material change was made.
+
+## Rules
+
+- Never create a non-Epic, non-top-level item without a parent context (Project for Stories, parentId for Sub-tasks).
+- Never skip relationship discovery — both the git history search AND the Linear MCP search must run, and their outcomes must be recorded on the item. "None found" is acceptable only when it's documented.
+- Never create a Bug, Task, or Sub-task that spans multiple repos. Split it before creating.
+- Never include a runtime-behavior item without a target backend environment, and never include an authenticated-surface item without sign-in credentials in the description.
+- Never invent custom field values. If the team requires a field you don't have, stop and ask.
+- Never overwrite a description without reading the current version first.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
+- All Linear writes go through this skill so best practices are enforced uniformly. Downstream skills (e.g. `lisa:linear-create`) should delegate here rather than calling the MCP write tools directly.
+- The gate logic (what makes a valid item) lives in `lisa:linear-validate-issue`, NOT in this skill. This skill calls the validator at Phase 5.5 (pre-write) and Phase 7 (via `lisa:linear-verify` post-write). When a gate needs to change, change it in `lisa:linear-validate-issue` — every caller picks it up automatically.
+- This skill is the destination of the `lisa:tracker-write` shim when `tracker = "linear"`. Vendor-neutral callers (`notion-to-tracker`, `confluence-to-tracker`, `linear-to-tracker`, `github-to-tracker`) MUST go through `lisa:tracker-write`, not call this skill directly.

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

@@ -0,0 +1,96 @@
+---
+name: linear-write-prd
+description: "Creates or idempotently updates a PRD as a Linear Project carrying exactly one PRD lifecycle project-label (`prd-draft` by default, or `prd-ready` when initial_role is ready so lisa:linear-prd-intake auto-claims it). The Linear PRD-source writer behind lisa:prd-source-write. Dedupes by a stable marker embedded in the Project description (matched by marker, never by name). Uses the Linear MCP."
+allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_teams", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__create_project_label"]
+---
+
+# Write Linear PRD: $ARGUMENTS
+
+Create (or update) a PRD as a Linear **Project** in the configured workspace/team. Invoked by
+`lisa:prd-source-write` when `source = linear`; do not call directly from a vendor-neutral caller.
+
+Linear's PRD lifecycle uses **project-level labels** (`prd-*`), per `config-resolution`. (The Linear
+PRD source models a PRD as a Project — the same shape `lisa:linear-prd-intake` scans.)
+
+`$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 workspace/team + PRD lifecycle labels
+
+```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}}"; }
+WORKSPACE=$(read_g '.linear.workspace' '')
+TEAM=$(read_g '.linear.teamKey' '')
+# Resolve the FULL PRD lifecycle vocabulary from config (never hard-code names) so the one-of
+# reconcile and the past-ready check are correct even when a project renamed any label.
+PRD_DRAFT=$(read_g '.linear.labels.prd.draft' 'prd-draft')
+PRD_READY=$(read_g '.linear.labels.prd.ready' 'prd-ready')
+PRD_IN_REVIEW=$(read_g '.linear.labels.prd.in_review' 'prd-in-review')
+PRD_BLOCKED=$(read_g '.linear.labels.prd.blocked' 'prd-blocked')
+PRD_TICKETED=$(read_g '.linear.labels.prd.ticketed' 'prd-ticketed')
+PRD_SHIPPED=$(read_g '.linear.labels.prd.shipped' 'prd-shipped')
+PRD_VERIFIED=$(read_g '.linear.labels.prd.verified' 'prd-verified')
+ALL_PRD_LABELS=("$PRD_DRAFT" "$PRD_READY" "$PRD_IN_REVIEW" "$PRD_BLOCKED" "$PRD_TICKETED" "$PRD_SHIPPED" "$PRD_VERIFIED")
+PROGRESSED=("$PRD_IN_REVIEW" "$PRD_BLOCKED" "$PRD_TICKETED" "$PRD_SHIPPED" "$PRD_VERIFIED")
+[ -z "$WORKSPACE" ] && { echo "Error: linear.workspace not set in .lisa.config.json."; exit 1; }
+[ -z "$TEAM" ] && { echo "Error: linear.teamKey not set in .lisa.config.json. A team key is required to create or scope a Linear Project."; exit 1; }
+```
+
+Resolve the target project-label from `initial_role`: `ready` → `$PRD_READY`, else `$PRD_DRAFT`.
+Resolve its label id via `mcp__linear-server__list_project_labels` (create via
+`mcp__linear-server__create_project_label` if missing).
+
+## Phase 2 — Dedupe by marker (search before create)
+
+The `marker` is embedded in the Project description. Find an existing Project carrying it — match the
+marker, **never** the project name:
+
+1. `mcp__linear-server__list_projects` scoped to the team/workspace (filtered by the `prd-*` label
+   set when supported), then inspect each candidate's description via
+   `mcp__linear-server__get_project` for the marker. If `source_ref` was passed, target it directly.
+2. If a Project with the marker exists → **update**; else → **create**.
+
+## Phase 3 — Create or update
+
+**Marker + usage-ledger preservation (both paths).** Before writing the `description`, ensure it
+contains **exactly one** marker line — inject the marker if the synthesized description lacks it.
+**Never write a markerless description** (including UPDATE / `source_ref`): that breaks future
+dedupe. If the live Project description already contains the canonical managed `## Lisa Usage`
+section, preserve it verbatim unless the caller intentionally supplied an updated canonical section;
+use the shared `usage-accounting` serializer/merge path rather than hand-editing ledger rows.
+
+**CREATE:** `mcp__linear-server__save_project` with:
+- `name`: `$TITLE`
+- `description`: the marker-normalized full PRD markdown
+- `teamIds`: `[<resolved team id>]`
+- `labelIds`: `[<role label id>]` (exactly one PRD lifecycle label)
+- `state`: Linear Project default (e.g. `backlog`)
+
+**UPDATE** (existing project or `source_ref`): `save_project` with the project id and **only** the
+changed fields — regenerate the marker-normalized `description` without dropping the managed
+`## Lisa Usage` section, and reconcile labels to **exactly one** PRD lifecycle label: add the role
+label, remove every other label in the resolved
+`${ALL_PRD_LABELS[@]}` set (config-resolved names, not a hard-coded list). Do **not** down-rank a
+Project whose current label is in the resolved `${PROGRESSED[@]}` set (already past `ready`) — leave
+it and report `reused (already past ready)`.
+
+## Phase 4 — Return
+
+```yaml
+ref: "<linear-project-id-or-slug>"
+url: "<project url>"
+role: draft | ready          # (or the Project's current role when reused past ready)
+marker: "<MARKER>"
+outcome: created | reused
+```
+
+## Rules
+
+- Exactly one PRD lifecycle project-label at all times.
+- Match dedupe by marker, never by project name.
+- Preserve an existing canonical `## Lisa Usage` section on update; never append a second usage
+  section or silently drop ledger rows.
+- Never down-rank a Project already past `ready`.
+- Source-side writer (`prd-*` project labels) — never touches issue-level build labels (`status:*`),
+  which are `lisa:linear-write-issue`'s lane (see `config-resolution` self-host separation).
+- Resolve label names from config (`linear.labels.prd.*`) — never hardcode.

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

@@ -0,0 +1,209 @@
+---
+name: lisa-review-implementation
+description: This skill should be used when comparing a project's Lisa-managed files against Lisa's source templates to identify drift. It reads the project manifest, locates source templates, generates diffs for drifted files, and offers to upstream improvements back to Lisa.
+---
+
+# Lisa Implementation Review
+
+This skill compares the current project's Lisa-managed files against Lisa's source templates to identify drift and offer to upstream improvements back to Lisa.
+
+## Prerequisites
+
+This skill requires access to the Lisa installation directory. Either:
+1. Start Claude Code with `--add-dir ~/lisa` (or your Lisa path)
+2. Pass the Lisa directory as an argument: `/lisa-review-implementation ~/lisa`
+
+## Instructions
+
+### Step 1: Locate Lisa Directory
+
+First, determine the Lisa installation directory:
+
+1. If an argument was provided, use that path
+2. Otherwise, check if any `--add-dir` paths contain a `src/core/lisa.ts` file (Lisa's signature file)
+3. Common locations to check: `~/lisa`, `~/workspace/lisa`, `../lisa`
+
+If Lisa directory cannot be found, inform the user:
+```
+Unable to locate Lisa installation directory.
+
+Please either:
+1. Start Claude Code with: claude --add-dir /path/to/lisa
+2. Run this command with the path: /lisa-review-implementation /path/to/lisa
+```
+
+### Step 2: Read the Manifest
+
+Read the project's `.lisa-manifest` file to get the list of managed files.
+
+Parse each line to extract:
+- `strategy`: The copy strategy used (copy-overwrite, copy-contents, merge, create-only)
+- `relativePath`: The file path relative to project root
+
+Skip:
+- Lines starting with `#` (comments)
+- Empty lines
+- Files with `create-only` strategy (these are meant to be customized)
+- Files with `merge` strategy (these are intentionally combined)
+
+### Step 3: Find Source Templates
+
+For each managed file, locate its source in Lisa by checking these directories in order:
+1. `npm-package/copy-overwrite/` and `npm-package/copy-contents/`
+2. `cdk/copy-overwrite/` and `cdk/copy-contents/`
+3. `nestjs/copy-overwrite/` and `nestjs/copy-contents/`
+4. `expo/copy-overwrite/` and `expo/copy-contents/`
+5. `typescript/copy-overwrite/` and `typescript/copy-contents/`
+6. `all/copy-overwrite/` and `all/copy-contents/`
+
+The FIRST match wins (most specific type takes precedence).
+
+Detect which project types apply by checking the project for:
+- `npm-package`: package.json without `"private": true` AND has `main`, `bin`, `exports`, or `files`
+- `cdk`: presence of `cdk.json` or `aws-cdk` in dependencies
+- `nestjs`: presence of `nest-cli.json` or `@nestjs` in dependencies
+- `expo`: presence of `app.json`, `eas.json`, or `expo` in dependencies
+- `typescript`: presence of `tsconfig.json` or `typescript` in dependencies
+
+Only check type directories that match the project.
+
+### Step 4: Compare Files
+
+For each file, compare the project version against the Lisa source:
+
+1. Read both files
+2. If identical, mark as "in sync"
+3. If different, generate a diff summary
+
+Use the Bash tool with `diff` to generate readable diffs:
+```bash
+diff -u "/path/to/lisa/source" "/path/to/project/file" || true
+```
+
+### Step 5: Generate Report
+
+Create a markdown report with these sections:
+
+```markdown
+# Lisa Implementation Review
+
+**Project:** [project name from package.json]
+**Lisa Source:** [lisa directory path]
+**Generated:** [current date/time]
+
+## Summary
+
+- **Total managed files:** X
+- **In sync:** X
+- **Drifted:** X
+- **Source not found:** X
+
+## Drifted Files
+
+### [relative/path/to/file]
+
+**Source:** [lisa-type]/copy-overwrite/[path]
+**Strategy:** copy-overwrite
+
+<details>
+<summary>View diff</summary>
+
+```diff
+[diff output]
+```
+
+</details>
+
+**Recommendation:** [Brief analysis of whether this change should be upstreamed]
+
+---
+
+[Repeat for each drifted file]
+
+## Files Not Found in Lisa
+
+These files are in the manifest but their source templates couldn't be located:
+
+- [list of files]
+
+## In Sync Files
+
+<details>
+<summary>X files are in sync with Lisa</summary>
+
+- [list of files]
+
+</details>
+```
+
+### Step 6: Offer to Upstream Changes
+
+After presenting the report, ask the user which drifted files they want to copy back to Lisa.
+
+For each file the user wants to upstream:
+
+1. Confirm the target path in Lisa (e.g., `typescript/copy-overwrite/.github/workflows/ci.yml`)
+2. Use the Write tool to copy the project's version to Lisa
+3. Report success
+
+Example prompt:
+```
+I found X files that have drifted from Lisa's templates.
+
+Which files would you like to copy back to Lisa?
+1. .github/workflows/ci.yml - [brief description of changes]
+2. .claude/settings.json - [brief description of changes]
+3. All of the above
+4. None - just show me the report
+
+Select an option (or list specific numbers):
+```
+
+### Important Notes
+
+- **Never auto-upstream without confirmation** - always ask the user first
+- **Preserve the most specific type directory** - if a file exists in both `typescript/` and `all/`, upstream to where it currently exists
+- **Handle binary files gracefully** - skip comparison for non-text files
+- **Respect .gitignore patterns** - some generated files shouldn't be compared
+- For `copy-contents` files like `.gitignore`, the comparison is trickier since the project may have additional lines - highlight only if Lisa's required lines are missing
+
+## Example Usage
+
+```
+User: /lisa-review-implementation
+
+Claude: I'll review your project's Lisa-managed files against the Lisa source templates.
+
+[Locates Lisa directory]
+[Reads manifest]
+[Compares files]
+[Generates report]
+
+# Lisa Implementation Review
+
+**Project:** my-awesome-app
+**Lisa Source:** /Users/dev/lisa
+**Generated:** 2026-01-18 10:30:00
+
+## Summary
+
+- **Total managed files:** 45
+- **In sync:** 42
+- **Drifted:** 3
+- **Source not found:** 0
+
+## Drifted Files
+
+### .github/workflows/ci.yml
+
+**Source:** typescript/copy-overwrite/.github/workflows/ci.yml
+**Strategy:** copy-overwrite
+
+[diff details]
+
+**Recommendation:** This adds a new caching step that improves CI performance. Good candidate for upstreaming.
+
+---
+
+I found 3 files that have drifted. Would you like to upstream any of these changes back to Lisa?
+```

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

@@ -0,0 +1,48 @@
+---
+name: monitor
+description: "Monitor application health across environments. Checks health endpoints, recent logs (CloudWatch / Sentry / browser console), error-rate spikes, performance hotspots, pending migrations, and runs Playwright smoke flows when relevant. Routes to the stack-specific ops-specialist agent (Expo, Rails, etc.). Also invoked as the post-deploy step of the lisa:verify skill."
+allowed-tools: ["Skill", "Bash", "Read", "Grep"]
+---
+
+# Monitor: $ARGUMENTS
+
+Spot-check application health in the named environment (`dev` / `staging` / `prod`). Useful both reactively (after a deploy, after a Sentry alert, before pushing a hot change) and as the post-deploy verification step inside `lisa:verify`.
+
+## 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 / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Hitting health endpoints, pulling logs, querying Sentry — 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.
+
+## Flow
+
+Execute the **Monitor** sub-flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The Monitor sub-flow delegates to a stack-specific `ops-specialist` agent (Expo, Rails, etc.), which composes the underlying ops skills:
+
+- `ops-verify-health` — health endpoints
+- `ops-check-logs` — CloudWatch / browser console / device / Serverless logs
+- `ops-monitor-errors` — Sentry issues, error-rate spikes, regressions
+- `ops-performance` — slow queries, p99 latency, hotspots
+- `ops-browser-uat` — Playwright smoke flows against the deployed env
+- `ops-db-ops` — pending migrations, replication lag
+- `ops-deploy` — deploy status / rollback readiness
+
+The agent decides which subset to run based on the env, the situation, and any extra context provided. The rule contains the canonical decision logic.
+
+## Output
+
+A health summary with the relevant findings (failures, warnings, no-issue confirmations). For post-deploy verification (when called from `lisa:verify`), the summary becomes evidence on the originating work item.