@codyswann/lisa 2.195.3 → 2.195.6

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

@@ -0,0 +1,292 @@
+---
+name: lisa-linear-write-issue
+description: "Creates or updates a Linear…"
+allowed-tools: ["Bash", "Skill"]
+---
+
+# 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** | `lisa-linear-access operation: save-project` | (none — Projects are top-level within a team) |
+| `Story` / `Task` / `Improvement` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` (the Epic Project) |
+| `Sub-task` | **sub-Issue** | `lisa-linear-access operation: save-issue` | `parentId` (the Story Issue) |
+| `Bug` | **Issue** | `lisa-linear-access operation: save-issue` | `projectId` if part of an Epic; else top-level |
+| `Spike` | **Issue** | `lisa-linear-access operation: 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 `lisa-linear-access operation: 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
+   lisa-linear-access operation: 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
+lisa-linear-access operation: list-issues({project: <projectId>, state_type: ["unstarted", "started"]})
+
+# Open items with overlapping keywords (workspace-wide)
+lisa-linear-access operation: list-issues({query: "<keyword>", state_type: ["unstarted", "started"]})
+
+# Items with shared labels
+lisa-linear-access operation: list-issues({label: "<label>", updatedAt: ">-30d"})
+
+# Recently closed items in the same Project
+lisa-linear-access operation: 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 `lisa-linear-access operation: save-project` or `lisa-linear-access operation: 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 `lisa-linear-access operation: list-project-labels` (create via `lisa-linear-access operation: create-project-label` if missing).
+2. Call `lisa-linear-access operation: 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 `lisa-linear-access operation: list-issue-labels` (create via `lisa-linear-access operation: 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 `lisa-linear-access operation: 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 `lisa-linear-access operation: 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 `lisa-linear-access operation: save-project` or `lisa-linear-access operation: 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 `lisa-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 `lisa-linear-access operation: 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/.codex-plugin/skills/lisa-linear-write-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Write Issue"
+short_description: "Creates or updates a Linear…"
+default_prompt:
+  - "Use $lisa-linear-write-issue: Creates or updates a Linear…."

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

@@ -0,0 +1,96 @@
+---
+name: lisa-linear-write-prd
+description: "Creates or idempotently updates…"
+allowed-tools: ["Skill", "Bash"]
+---
+
+# 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 `lisa-linear-access operation: list-project-labels` (create via
+`lisa-linear-access operation: 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. `lisa-linear-access operation: list-projects` scoped to the team/workspace (filtered by the `prd-*` label
+   set when supported), then inspect each candidate's description via
+   `lisa-linear-access operation: 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 `lisa-usage-accounting` serializer/merge path rather than hand-editing ledger rows.
+
+**CREATE:** `lisa-linear-access operation: 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/.codex-plugin/skills/lisa-linear-write-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Linear Write PRD"
+short_description: "Creates or idempotently updates…"
+default_prompt:
+  - "Use $lisa-linear-write-prd: Creates or idempotently updates…."

package/plugins/lisa/.codex-plugin/skills/lisa-monitor/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: lisa-monitor
+description: "Monitor application health AND…"
+allowed-tools: ["Skill", "Bash", "Read", "Grep", "Glob"]
+---
+
+# Monitor: $ARGUMENTS
+
+Spot-check application health, **audit observability completeness**, and **file build-ready tickets** for the problems and instrumentation gaps it finds — all scoped to the current repo. Useful reactively (after a deploy, after a Sentry alert, before pushing a hot change), as a periodic manual observability sweep, and as the post-deploy verification step inside `lisa-verify`.
+
+**Arguments:** `<environment>` (`dev` / `staging` / `prod`) `[--dry-run] [--report-only] [--all-gaps] [max_candidates=<n>]`.
+
+- `--dry-run` — audit and report which tickets *would* be filed, but create nothing.
+- `--report-only` — health/audit summary only; no filing and no would-file analysis. This is the mode `lisa-verify` passes for its post-deploy check, so monitor never files during a verify run.
+- `--all-gaps` — also file `recommended`-tier gaps (session replay, product analytics, etc.), not just `core`. Does not change anomaly thresholds.
+- `max_candidates=<n>` — cap tickets filed this run (default 20; config `monitor.maxCandidates`).
+
+## 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 Code >= 2.1.178: there is no `TeamCreate` tool; the team forms automatically when you spawn the first teammate with `Agent`. That first spawn should be the bounded specialist needed to start this flow. On older Claude Code that still exposes `TeamCreate`, the explicit team-create path is also acceptable.
+- 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: `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion / Sentry), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. The initial Claude `Agent` spawn described above is the only pre-team exception because it establishes the team. 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): **discover → collect live signals → audit completeness → report → file (standalone only)**. The `observability-audit` rule owns the profile detection, the completeness rubric, the conservative anomaly thresholds, the gate-passing ticket templates, the fingerprint/idempotency contract, the cap, and the Verify report-only guard — follow it; do not restate it here.
+
+**Live-signal collection** delegates to a stack-specific `ops-specialist` agent when the stack overlay ships one. The **Expo** ops-specialist composes the full set below:
+
+- `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 **Rails** ops-specialist composes a different subset (`ops-run-local`, `ops-deploy`, `ops-check-logs`, `ops-verify-jobs`, `ops-verify-telemetry` — X-Ray/CloudWatch traces and metrics via `ops-verify-telemetry`). When no `ops-specialist` overlay is present (e.g. NestJS, CDK, or a generic TypeScript repo), fall back to **stack-agnostic base probing** — read manifests/config to discover what's wired, then probe live sources directly (Sentry CLI/REST, `aws logs` / `aws cloudwatch` / `aws xray`, the Playwright MCP for client-side console/network), exactly as the `observability-audit` "read-then-probe" detection prescribes. The agent decides which subset to run based on the env, the repo profile, and any extra context.
+
+## Ticket filing (standalone only)
+
+After report, file what was found — **only when run standalone**, never under `--report-only`/`--dry-run` and never when nested inside `lisa-verify` (which passes `--report-only`):
+
+- **Anomalies** (live signals over the conservative bar) → `Bug` leaves. **Gaps** (in-scope MISSING rubric dimensions) → `Task`/`Improvement` leaves.
+- Every ticket is filed via the vendor-neutral `lisa-tracker-write` shim with `build_ready: true` (never a vendor write skill directly), as a **single-repo leaf** stamped `repo:<current>`, with a real three-audience description, Gherkin AC, Target Backend Environment, and a Validation Journey + `EVIDENCE:` marker so it passes the `tracker-validate` gates.
+- **Idempotent:** embed the `<!-- lisa:monitor-finding: <fingerprint> -->` sentinel and search-before-create; never duplicate a live or just-resolved finding.
+- **Capped** at `max_candidates` (default 20), `core`/high-severity first; report how many were filed vs dropped.
+- **`--dry-run`** previews would-file tickets and creates nothing. **`--all-gaps`** widens gap filing to `recommended` tiers.
+
+`monitor` files only. The `intake` / `tracker-build-intake` cron picks the ready tickets up and implements them.
+
+## Output
+
+A single report: the health/anomaly summary (failures, warnings, no-issue confirmations) + the observability audit table (each in-scope dimension as `OK` / `WARN` / `MISSING` / `PRESENT (unverified)`) + the filing summary (tickets filed with refs + fingerprints, duplicates skipped, dropped count if the cap truncated; or would-file tickets under `--dry-run`). For post-deploy verification (when called from `lisa-verify`), the report-only summary becomes evidence on the originating work item.

package/plugins/lisa/.codex-plugin/skills/lisa-monitor/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Monitor"
+short_description: "Monitor application health AND…"
+default_prompt:
+  - "Use $lisa-monitor: Monitor application health AND…."

package/plugins/lisa/.codex-plugin/skills/lisa-nightly-add-test-coverage/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: lisa-nightly-add-test-coverage
+description: "Nightly direct-execution skill…"
+allowed-tools: ["Edit", "MultiEdit", "Write", "Read", "Glob", "Grep", "Bash"]
+---
+
+# Nightly Test Coverage Improvement
+
+The caller provides pre-computed context:
+- **Package manager** (`npm`, `yarn`, or `bun`)
+- **Thresholds file** path (vitest.thresholds.json or jest.thresholds.json)
+- **Current thresholds** (statements, branches, functions, lines percentages)
+- **Proposed thresholds** (each metric increased by the coverage increment, capped at 90%)
+- **Metrics being bumped** (which metrics are below target)
+
+## Instructions
+
+### Phase 1: Identify gaps
+
+1. Run the project's coverage script with the provided package manager (e.g., `npm run test:cov`, `yarn test:cov`, or `bun run test:cov`) to get the coverage report -- identify gaps BEFORE reading any source files
+2. Parse the coverage output to identify the specific files and lines with the lowest coverage. Prioritize files with the most uncovered lines/branches.
+3. Read ONE existing test file to learn the project's testing patterns (mocks, imports, assertions). Do not read more than one.
+
+### Phase 2: Write tests incrementally — one file at a time
+
+For each source file with low coverage (starting with the lowest):
+
+4. Read only the uncovered sections of the source file using the coverage report line numbers -- do not explore the codebase broadly
+5. Write a test file targeting the uncovered branches/lines for that source file
+6. Run the test file in isolation (e.g., `npx vitest run tests/my-new-test.test.ts`) to verify it passes before moving on
+7. If the test fails, fix it immediately. Do not move to the next file until the current test passes.
+8. Repeat steps 4-7 for the next source file. Stop once you estimate the proposed thresholds will be met.
+
+### Phase 3: Verify and ship
+
+9. Run the full coverage script to verify the new thresholds pass
+10. Update the thresholds file with the proposed new threshold values
+11. Re-run the coverage script to confirm the updated thresholds pass
+12. Commit all changes (new tests + updated thresholds file) with conventional commit messages
+13. Create a PR with `gh pr create` with a title like "test: increase test coverage: [metrics being bumped]" summarizing coverage improvements

package/plugins/lisa/.codex-plugin/skills/lisa-nightly-add-test-coverage/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Nightly Add Test Coverage"
+short_description: "Nightly direct-execution skill…"
+default_prompt:
+  - "Use $lisa-nightly-add-test-coverage: Nightly direct-execution skill…."

package/plugins/lisa/.codex-plugin/skills/lisa-nightly-improve-tests/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: lisa-nightly-improve-tests
+description: "Nightly direct-execution skill…"
+allowed-tools: ["Edit", "MultiEdit", "Write", "Read", "Glob", "Grep", "Bash"]
+---
+
+# Nightly Test Quality Improvement
+
+The caller provides:
+- **Mode**: "nightly" or "general"
+- **Changed files** (nightly mode only): list of source files changed in the last 24 hours
+
+## Nightly Mode
+
+1. For each changed source file, find its corresponding test file(s)
+2. Analyze those test files for: missing edge cases, weak assertions (toBeTruthy instead of specific values), missing error path coverage, tests that test implementation rather than behavior
+3. Improve the test files with the most impactful changes
+4. Run the full test suite to verify all tests pass
+5. Commit changes with conventional commit messages
+6. Create a PR with `gh pr create` summarizing what was improved and why
+
+## General Mode
+
+1. Scan the test files to find weak, brittle, or poorly-written tests
+2. Look for: missing edge cases, weak assertions (toBeTruthy instead of specific values), missing error path coverage, tests that test implementation rather than behavior
+3. Improve 3-5 test files with the most impactful changes
+4. Run the full test suite to verify all tests pass
+5. Commit changes with conventional commit messages
+6. Create a PR with `gh pr create` summarizing what was improved and why

package/plugins/lisa/.codex-plugin/skills/lisa-nightly-improve-tests/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Nightly Improve Tests"
+short_description: "Nightly direct-execution skill…"
+default_prompt:
+  - "Use $lisa-nightly-improve-tests: Nightly direct-execution skill…."

package/plugins/lisa/.codex-plugin/skills/lisa-nightly-lower-code-complexity/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: lisa-nightly-lower-code-complexity
+description: "Nightly direct-execution skill…"
+allowed-tools: ["Edit", "MultiEdit", "Write", "Read", "Glob", "Grep", "Bash"]
+---
+
+# Nightly Code Complexity Reduction
+
+The caller provides pre-computed context:
+- **Package manager** (`npm`, `yarn`, or `bun`)
+- **Current thresholds** (cognitiveComplexity, maxLinesPerFunction from eslint.thresholds.json)
+- **Proposed thresholds** (each metric decreased toward target minimums)
+- **Metrics being reduced** (which metrics are above target)
+
+## Instructions
+
+1. Update eslint.thresholds.json with the proposed new threshold values (do NOT change the maxLines threshold)
+2. Run the project's lint script with the provided package manager (e.g., `npm run lint`, `yarn lint`, or `bun run lint`) to find functions that violate the new stricter thresholds
+3. **Before editing**, check each violating file's total line count (`wc -l`). If a file is within 20 lines of its `max-lines` ESLint limit (typically 300), extract helpers into a **separate companion file** (e.g., `fooHelpers.ts`) instead of adding them to the same file. Extracting functions into the same file adds net lines and can create new max-lines violations.
+4. Fix violations one file at a time. Read only the specific function that violates — do not pre-read all files upfront. Fix it, then move to the next.
+5. For cognitive complexity violations: use early returns, extract helper functions, replace conditionals with lookup tables
+6. For max-lines-per-function violations: split large functions, extract helper functions, separate concerns
+7. After each file edit, run the project's formatter (e.g., `bun run format` or `npx prettier --write <file>`) to ensure line counts reflect the final formatted state before moving on
+8. Re-run the lint script with the provided package manager to verify all violations are resolved (both the target metric AND max-lines)
+9. Run the TypeScript compiler to catch type errors early: `npx tsc --noEmit 2>&1 | head -30`. If there are type errors, fix them now — do NOT wait until the commit step. Pre-commit hooks run type checking, and discovering errors at commit time wastes turns.
+10. Run the project's test script with the provided package manager (e.g., `npm run test`, `yarn test`, or `bun run test`) to verify no tests are broken by the refactoring
+11. Commit all changes (refactored code + updated eslint.thresholds.json) with conventional commit messages
+12. Create a PR with `gh pr create` with a title like "refactor: reduce code complexity: [metrics being reduced]" summarizing the changes

package/plugins/lisa/.codex-plugin/skills/lisa-nightly-lower-code-complexity/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Nightly Lower Code Complexity"
+short_description: "Nightly direct-execution skill…"
+default_prompt:
+  - "Use $lisa-nightly-lower-code-complexity: Nightly direct-execution skill…."