@codyswann/lisa 2.176.12 → 2.178.0

package/plugins/lisa-cursor/skills/linear-prd-intake/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: linear-prd-intake
 description: "Scans a Linear workspace (or a specific team) for projects carrying the configured `ready` PRD label and runs the first eligible one through the dry-run validation pipeline. A project that passes every gate gets tickets written and the label flipped to the configured `ticketed` label; a project that fails gets clarifying-question comments (on a sentinel feedback issue under the project) and the label flipped to the configured `blocked` label. Linear counterpart of `lisa:notion-prd-intake` and `lisa:confluence-prd-intake` — the workflow is identical; only the source-of-truth tools differ. Composes existing skills (linear-to-tracker, tracker-validate, tracker-source-artifacts, product-walkthrough)."
-allowed-tools: ["Skill", "Bash", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__save_project", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__save_issue", "mcp__linear-server__list_comments", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_teams"]
+allowed-tools: ["Skill", "Bash"]
 ---
 
 # Linear PRD Intake: $ARGUMENTS
@@ -96,13 +96,13 @@ If the project does not yet use these labels, this skill cannot run. Adopting th
    - Bare team key → use as-is; the scope is that team.
    - The literal `linear` → fall back to `linear.workspace` from `.lisa.config.json`; error if not set.
 2. Verify the scope is reachable:
-   - For a workspace: call `mcp__linear-server__list_teams` and confirm at least one team is returned (non-empty workspaces are readable; empty results indicate auth or workspace-mismatch).
-   - For a team: call `mcp__linear-server__list_teams({query: <KEY>})` and confirm the team resolves.
-3. Resolve the project-label IDs for `$READY`, `$IN_REVIEW`, `$BLOCKED`, `$TICKETED` via `mcp__linear-server__list_project_labels`. Cache them — every transition uses these IDs. If any of the four are missing, surface a label-convention error and exit (see "Adoption").
+   - For a workspace: call `lisa:linear-access operation: list-teams` and confirm at least one team is returned (non-empty workspaces are readable; empty results indicate auth or workspace-mismatch).
+   - For a team: call `lisa:linear-access operation: list-teams({query: <KEY>})` and confirm the team resolves.
+3. Resolve the project-label IDs for `$READY`, `$IN_REVIEW`, `$BLOCKED`, `$TICKETED` via `lisa:linear-access operation: list-project-labels`. Cache them — every transition uses these IDs. If any of the four are missing, surface a label-convention error and exit (see "Adoption").
 
 ### Phase 2 — Find ready PRDs
 
-Call `mcp__linear-server__list_projects({label: "$READY", ...scope-filter})`:
+Call `lisa:linear-access operation: list-projects({label: "$READY", ...scope-filter})`:
 
 - For a workspace scope: pass `label: "$READY"` only.
 - For a team scope: pass `label: "$READY"` AND `team: "<KEY>"`.
@@ -123,7 +123,7 @@ Select the first ready project returned by Phase 2 and process only that project
 
 #### 3a. Claim
 
-Transition labels via `mcp__linear-server__save_project({id, labels})`: pass the full new label set with `$READY` removed and `$IN_REVIEW` added. This is the idempotency lock — a re-entrant cycle running concurrently won't see this project because its query filters on `label: "$READY"`.
+Transition labels via `lisa:linear-access operation: save-project({id, labels})`: pass the full new label set with `$READY` removed and `$IN_REVIEW` added. This is the idempotency lock — a re-entrant cycle running concurrently won't see this project because its query filters on `label: "$READY"`.
 
 If the update fails (permission error, race condition), log it and skip this project. Do not proceed to validation on a project you didn't successfully claim.
 
@@ -145,7 +145,7 @@ This call also indirectly invokes `lisa:tracker-source-artifacts` (artifact extr
 
 1. Re-invoke `lisa:linear-to-tracker` with `dry_run: false` to actually write the tickets. This re-runs Phases 1-5 and runs the preservation gate (Phase 5.5).
 2. Capture the created ticket keys from the skill's output.
-3. Ensure the project has a sentinel feedback issue (see "Sentinel feedback issue" below for the helper). Post a comment on it via `mcp__linear-server__save_comment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the $SHIPPED label to the Linear project after the work is delivered."`
+3. Ensure the project has a sentinel feedback issue (see "Sentinel feedback issue" below for the helper). Post a comment on it via `lisa:linear-access operation: save-comment` listing the created tickets (epic, stories, sub-tasks) with their JIRA URLs. Lead with: `"Ticketed by Claude. Created N JIRA issues — see below. Add the $SHIPPED label to the Linear project after the work is delivered."`
 4. Transition labels: remove `$IN_REVIEW`, add `$TICKETED` via `save_project`.
 5. **Run Phase 3e (coverage audit)** before considering this PRD done.
 
@@ -160,7 +160,7 @@ The audience for these comments is the **product team**, not engineers. They are
 
 ##### 3c.2 Render each comment
 
-Ensure the project has a sentinel feedback issue (see helper below). For each anchored group (`prd_anchor` is a sub-issue identifier), post a comment on THAT sub-issue via `mcp__linear-server__save_comment({issueId: <prd_anchor>, body: <template>})`. For the unanchored group, post a single comment on the sentinel feedback issue using the same template, prefixed with `Issues without a specific sub-issue anchor:` and one block per failure.
+Ensure the project has a sentinel feedback issue (see helper below). For each anchored group (`prd_anchor` is a sub-issue identifier), post a comment on THAT sub-issue via `lisa:linear-access operation: save-comment({issueId: <prd_anchor>, body: <template>})`. For the unanchored group, post a single comment on the sentinel feedback issue using the same template, prefixed with `Issues without a specific sub-issue anchor:` and one block per failure.
 
 If `save_comment` fails for a specific anchored sub-issue (the issue was deleted between fetch and post, or the agent lacks comment permission), fall back to the sentinel feedback issue for that group. Do not silently drop the failure.
 
@@ -246,7 +246,7 @@ Rollup is keyed by the PRD's current state. If the PRD project already carries `
 
 Read the PRD's **generated top-level work** — its created Epics and any top-level Stories created directly under it, **excluding** leaf Sub-tasks and any Story nested under a generated Epic (`prd-lifecycle-rollup` rule, generated-top-level-work contract). Use two sources, native first:
 
-1. **Native parent / project relationships (primary).** Linear records the PRD→child relationship natively where the PRD also lives in Linear: a generated top-level Issue uses `parentId`, or a generated Project groups the generated Issues. Read the PRD project's generated top-level Issues via `mcp__linear-server__list_issues({project: <id>})` and take the **top-level** ones (no `parentId`, or whose parent is the PRD itself) — those are the PRD's direct children. Fetch each with `mcp__linear-server__get_issue` for its workflow state.
+1. **Native parent / project relationships (primary).** Linear records the PRD→child relationship natively where the PRD also lives in Linear: a generated top-level Issue uses `parentId`, or a generated Project groups the generated Issues. Read the PRD project's generated top-level Issues via `lisa:linear-access operation: list-issues({project: <id>})` and take the **top-level** ones (no `parentId`, or whose parent is the PRD itself) — those are the PRD's direct children. Fetch each with `lisa:linear-access operation: get-issue` for its workflow state.
 
 2. **Documented `## Tickets` section (fallback).** When the native relationship is unavailable (the destination tracker is a *different* system — e.g. Linear PRD → JIRA tracker — so the children were never linked as Linear issues), parse the machine-readable generated-work section `lisa:prd-backlink` writes to the PRD (`## Tickets`, alias `## Generated Work`; see #582). Top-level children are the `### <Epic key>: <title>` group headers' first line (`- [<ref>](<url>) — Epic`) plus any top-level Story listed directly under `### Unparented items`. Lines nested deeper (`  - ... — Story:` under an Epic, `    - ... — Sub-task:`) are descendants, NOT top-level children — skip them.
 
@@ -266,7 +266,7 @@ The set of **required** children for the all-terminal check is the top-level chi
 
 **All required children terminal** (every required top-level child is terminal; at least one required child exists):
 
-1. Transition labels: remove `$TICKETED`, add `$SHIPPED` via `mcp__linear-server__save_project({id, labels})`. Verify exactly one lifecycle label remains (the single-label invariant).
+1. Transition labels: remove `$TICKETED`, add `$SHIPPED` via `lisa:linear-access operation: save-project({id, labels})`. Verify exactly one lifecycle label remains (the single-label invariant).
 2. Leave the PRD active for `/lisa:verify-prd`; do not archive at the shipped hop.
 3. Post a short rollup comment on the sentinel feedback issue naming the terminal child set and (when dropped children exist) the dropped set, so the audit trail records *why* the PRD shipped. Lead with `"Shipped by Claude — all generated top-level work is complete."`
 
@@ -283,7 +283,7 @@ This phase implements exactly one PRD-lifecycle hop — `$TICKETED → $SHIPPED`
 
 `shipped` and `verified` are distinct facts about a PRD (see the `prd-lifecycle-rollup` rule's "PRD-level verification vs ticket verification" and "Closing the loop" sections). Rollup (3f) only reaches `$SHIPPED`; the `shipped → verified` (pass) / `shipped → ticketed` (fail) hops are owned by `/lisa:verify-prd`. This phase **closes that loop** by dispatching the initiative-level acceptance gate for shipped PRDs. It never performs the verification transition itself — the "never sets the verification outcome" invariant holds: `lisa:verify-prd`, not this skill, sets `verified` (or, on failure, re-opens the PRD to `ticketed`).
 
-Re-query the projects currently carrying the `$SHIPPED` label via `mcp__linear-server__list_projects` (filtered by the `$SHIPPED` project label, **including archived projects** — so shipped PRDs remain active for `lisa:verify-prd`). Pick the **first** one and invoke `lisa:verify-prd <project-url>`. Process **one shipped PRD per cycle** — `lisa:verify-prd` is a heavy full flow (spec-conformance + empirical verification + fix-issue creation), so it is bounded exactly like the single-ready-PRD claim in Phase 3; the scheduler drains the rest.
+Re-query the projects currently carrying the `$SHIPPED` label via `lisa:linear-access operation: list-projects` (filtered by the `$SHIPPED` project label, **including archived projects** — so shipped PRDs remain active for `lisa:verify-prd`). Pick the **first** one and invoke `lisa:verify-prd <project-url>`. Process **one shipped PRD per cycle** — `lisa:verify-prd` is a heavy full flow (spec-conformance + empirical verification + fix-issue creation), so it is bounded exactly like the single-ready-PRD claim in Phase 3; the scheduler drains the rest.
 
 **Per-cycle combined bound:** each scheduler cycle dispatches at most one ready PRD (the Phase 3 single-ready-PRD claim) **and** at most one shipped PRD for verification (this Phase 3g dispatch), for a maximum of two PRD operations per cycle. Ready intake runs first (Phase 3), then shipped verify (Phase 3g).
 

package/plugins/lisa-cursor/skills/linear-read-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: linear-read-issue
 description: "Fetches the full scope of a Linear work item — Issue or Project — including metadata, description, acceptance criteria, all comments, attachments, native relations (blocks/blocked_by/relates_to/duplicates), Project parent (if any) with siblings, and sub-Issues. Produces a consolidated context bundle that downstream agents consume so they never act on a single item in isolation."
-allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__get_project", "mcp__linear-server__list_issues", "mcp__linear-server__list_comments", "mcp__linear-server__list_documents", "mcp__linear-server__get_document"]
+allowed-tools: ["Bash", "Skill"]
 ---
 
 # Read Linear Work Item: $ARGUMENTS
@@ -21,13 +21,13 @@ Reads `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.loca
 1. If `$ARGUMENTS` matches `<TEAM>-<n>` → Issue mode.
 2. If `$ARGUMENTS` is a URL containing `/project/<slug>-<short-id>` → Project mode (extract `<short-id>`).
 3. Otherwise stop and report. Do NOT guess.
-4. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
+4. Resolve team ID via `lisa:linear-access operation: list-teams({query: <teamKey>})`.
 
 ## Phase 2 — Fetch Primary Item
 
 ### Issue mode
 
-Call `mcp__linear-server__get_issue`. Extract and preserve:
+Call `lisa:linear-access operation: get-issue`. Extract and preserve:
 
 **Metadata**
 - Identifier, title, issue type (typically a label or workflow state), state, priority (0–4)
@@ -43,13 +43,13 @@ Call `mcp__linear-server__get_issue`. Extract and preserve:
 - Attachment URLs (capture, do not download unless needed)
 
 **Comments**
-Fetch ALL comments via `mcp__linear-server__list_comments({issueId: <id>})` in chronological order. Walk thread parents/children — Linear comments are threaded via `parentId`. Do not truncate. For each comment:
+Fetch ALL comments via `lisa:linear-access operation: list-comments({issueId: <id>})` in chronological order. Walk thread parents/children — Linear comments are threaded via `parentId`. Do not truncate. For each comment:
 - Author, timestamp, body
 - Flag comments that contain: credentials, reproduction steps, status updates from stakeholders, decisions, or triage headers.
 
 ### Project mode
 
-Call `mcp__linear-server__get_project` with `includeMilestones: true`, `includeResources: true`. Extract:
+Call `lisa:linear-access operation: get-project` with `includeMilestones: true`, `includeResources: true`. Extract:
 
 **Metadata**
 - ID, slug, name, state, priority, lead, color
@@ -58,10 +58,10 @@ Call `mcp__linear-server__get_project` with `includeMilestones: true`, `includeR
 
 **Body**
 - Description (markdown)
-- Attached documents — call `mcp__linear-server__list_documents({projectId})` then `get_document` per result. Treat each as additional spec content.
+- Attached documents — call `lisa:linear-access operation: list-documents({projectId})` then `lisa:linear-access operation: get-document` per result. Treat each as additional spec content.
 
 **Member Issues**
-- Call `mcp__linear-server__list_issues({project: <id>})` to enumerate the Project's Issues. Capture identifier, title, state, parent Issue (for sub-Issue tree).
+- Call `lisa:linear-access operation: list-issues({project: <id>})` to enumerate the Project's Issues. Capture identifier, title, state, parent Issue (for sub-Issue tree).
 
 ## Phase 3 — Fetch Attachments / Remote Links
 
@@ -81,7 +81,7 @@ Linear native Issue relations are returned in the `get_issue` response under `re
 - `relates_to`
 - `duplicates` / `duplicated_by`
 
-For each related Issue, call `mcp__linear-server__get_issue` and capture:
+For each related Issue, call `lisa:linear-access operation: get-issue` and capture:
 - Identifier, title, state, priority, assignee
 - Description (full, unless cancelled — then summary only)
 - Acceptance Criteria section
@@ -96,9 +96,9 @@ For Project-level relationships (Project ↔ Project), Linear doesn't model nati
 
 If the primary Item is an Issue with a Project parent:
 
-1. Fetch the Project via `mcp__linear-server__get_project` — full description, milestones, labels, lead.
+1. Fetch the Project via `lisa:linear-access operation: get-project` — full description, milestones, labels, lead.
 2. Fetch Project documents (Phase 2 procedure).
-3. Find Project siblings via `mcp__linear-server__list_issues({project: <projectId>})` excluding the primary identifier.
+3. Find Project siblings via `lisa:linear-access operation: list-issues({project: <projectId>})` excluding the primary identifier.
 4. For each sibling, capture: identifier, title, state, priority, assignee, summary (first paragraph of description).
 5. If a sibling is `Started` or `In Review` with a different assignee, flag it prominently.
 
@@ -106,7 +106,7 @@ If the primary Item IS a Project, Phase 5 is the same as fetching all member Iss
 
 ## Phase 6 — Fetch Sub-Issues
 
-If the primary Issue has children (sub-Issues), fetch each via `mcp__linear-server__get_issue`: identifier, title, state, assignee, description (first paragraph), Acceptance Criteria.
+If the primary Issue has children (sub-Issues), fetch each via `lisa:linear-access operation: get-issue`: identifier, title, state, assignee, description (first paragraph), Acceptance Criteria.
 
 ## Phase 7 — Assemble Context Bundle
 

package/plugins/lisa-cursor/skills/linear-sync/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: linear-sync
 description: "Syncs plan progress to a linked Linear Issue. Posts plan contents, progress updates, branch links, and PR links at key milestones. Use this skill throughout the plan lifecycle to keep Linear Issues in sync. The Linear counterpart of lisa:jira-sync and lisa:github-sync."
-allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__list_issues", "mcp__linear-server__save_comment", "mcp__linear-server__list_issue_labels", "mcp__linear-server__create_issue_label", "mcp__linear-server__save_issue"]
+allowed-tools: ["Bash", "Skill"]
 ---
 
 # Sync Plan to Linear: $ARGUMENTS
@@ -37,7 +37,7 @@ This skill **suggests** transitions but does not auto-transition the native Line
 
 1. If `$ARGUMENTS` includes an identifier, parse it.
 2. Else search for the active plan file (most recent file under `plans/`) and extract the linked Linear Issue identifier from its frontmatter.
-3. Fetch the Issue via `mcp__linear-server__get_issue` to confirm it exists.
+3. Fetch the Issue via `lisa:linear-access operation: get-issue` to confirm it exists.
 
 ## Phase 2 — Compose Milestone Comment
 
@@ -65,7 +65,7 @@ Next: implementation begins. Suggested status: **Todo** (label: `status:ready`).
 
 ## Phase 3 — Post Comment
 
-Call `mcp__linear-server__save_comment({issueId: <id>, body: <comment>})`.
+Call `lisa:linear-access operation: save-comment({issueId: <id>, body: <comment>})`.
 
 ## Phase 3b — Ensure PR Backlink
 
@@ -79,14 +79,14 @@ The PR branch/title/body identifier is the PR -> Linear side. This phase is the
 
 ## Phase 4 — Update Status Label (when caller requests)
 
-If the caller passes `--update-label`, update the `status:*` label set via `mcp__linear-server__save_issue`:
+If the caller passes `--update-label`, update the `status:*` label set via `lisa:linear-access operation: save-issue`:
 
 - `plan-created` → add `status:ready`
 - `implementation-in-progress` → remove `status:ready`, add `status:in-progress`
 - `pr-ready` → remove `status:in-progress`, add `status:code-review`
 - `pr-merged` → remove `status:code-review`, add `status:done`
 
-If the requested label doesn't exist on the team, create it via `mcp__linear-server__create_issue_label`.
+If the requested label doesn't exist on the team, create it via `lisa:linear-access operation: create-issue-label`.
 
 Verify exactly one `status:*` label remains after the update — having two simultaneously breaks the build-queue invariant.
 
@@ -96,7 +96,7 @@ Without `--update-label`, this skill posts the comment only and does NOT touch l
 
 When the caller passes `--rollup`, this skill **derives a parent/container's `status:*` label from the roll-up of its children** instead of acting on a leaf. A **Project** (the Epic equivalent) rolls up from its Issues; an **Issue** rolls up from its sub-Issues. This implements the Linear child-issue-status arm of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy.
 
-**Resolve the child set the same way `lisa:linear-read-issue` does** — `mcp__linear-server__list_issues({project: <id>})` for a Project's Issues, or `mcp__linear-server__get_issue` per child for an Issue's sub-Issues (via `parentId`). Capture each child's `status:*` label. If the item has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
+**Resolve the child set the same way `lisa:linear-read-issue` does** — `lisa:linear-access operation: list-issues({project: <id>})` for a Project's Issues, or `lisa:linear-access operation: get-issue` per child for an Issue's sub-Issues (via `parentId`). Capture each child's `status:*` label. If the item has **no** children it is a leaf — rollup is N/A; behave as a normal milestone sync.
 
 **Evaluate the required children over the env ladder `in-progress < dev < staging < production` (the ordered keys of the Linear env-keyed `done` map, e.g. `status:on-dev < status:on-stg < status:done`) and take the first match** (canonical roles from `config-resolution`; Linear label map is `status:blocked`, `status:in-progress`, `status:code-review`, env-keyed `done`):
 
@@ -115,7 +115,7 @@ When the caller passes `--rollup`, this skill **derives a parent/container's `st
 
 **Single-environment collapse (this repo).** The env rungs resolve via the env-keyed `done` logic in `config-resolution`. In this repo `deploy.branches` declares only `production: main`, so `done` collapses to the single `status:done` label, the only env rung is production, and the lifecycle is `status:ready → status:in-progress → status:code-review → status:done` with **no** dev/staging promotion hops; the rollup never resolves a dev or staging `done`. Multi-environment projects keep the env-keyed map and roll a parent up to intermediate env labels (`status:on-dev`/`status:on-stg`).
 
-**Apply the derived label** via `mcp__linear-server__save_issue` (Project or Issue), removing the parent's existing `status:*` and adding the derived one so exactly one `status:*` label remains. Post an idempotent rollup comment naming the derived state and the child tally. The native Linear `state` is **not** auto-transitioned — only the `status:*` label, mirroring the `--update-label` rule. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's label untouched.
+**Apply the derived label** via `lisa:linear-access operation: save-issue` (Project or Issue), removing the parent's existing `status:*` and adding the derived one so exactly one `status:*` label remains. Post an idempotent rollup comment naming the derived state and the child tally. The native Linear `state` is **not** auto-transitioned — only the `status:*` label, mirroring the `--update-label` rule. **Safe default:** if the derived terminal cannot be resolved (ambiguous required-set or unresolvable env `done`), do not guess — post the derived suggestion as a comment and leave the parent's label untouched.
 
 ## Rules
 

package/plugins/lisa-cursor/skills/linear-to-tracker/SKILL.md

@@ -6,7 +6,7 @@ description: >
   "break down this Linear project", "create tickets from a Linear project", "turn this Linear PRD into tickets", or similar. This skill mirrors `lisa:notion-to-tracker` and `lisa:confluence-to-tracker` for projects
   whose PRDs live in Linear — the workflow, gates, dry-run mode, and validation rules are identical;
   only the source-of-truth tool surface differs (Linear MCP instead of Notion / Confluence MCP).
-allowed-tools: ["Skill", "Bash", "mcp__linear-server__get_project", "mcp__linear-server__list_projects", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_comments", "mcp__linear-server__list_documents", "mcp__linear-server__get_document", "mcp__linear-server__list_project_labels", "mcp__linear-server__list_teams"]
+allowed-tools: ["Skill", "Bash"]
 ---
 
 # Linear PRD to Tracker Breakdown
@@ -21,8 +21,8 @@ This skill is the Linear counterpart of `lisa:notion-to-tracker` and `lisa:confl
 Linear has no native "PRD" entity. This skill treats a **Linear Project** as the PRD container:
 
 - **Project description** (markdown) is the PRD body — equivalent to a Notion page body or a Confluence page body.
-- **Project documents** (Linear's long-form markdown docs attached to projects, fetched via `list_documents({projectId})` / `get_document`) are treated as additional spec content and merged into the analysis. A multi-document Linear PRD is the analog of a multi-page Confluence PRD.
-- **Project sub-issues** (`list_issues({project})`) act as the candidate set for epics and user stories — the same role child Epic pages play in a Notion/Confluence PRD.
+- **Project documents** (Linear's long-form markdown docs attached to projects, fetched via `list-documents({projectId})` / `get-document`) are treated as additional spec content and merged into the analysis. A multi-document Linear PRD is the analog of a multi-page Confluence PRD.
+- **Project sub-issues** (`list-issues({project})`) act as the candidate set for epics and user stories — the same role child Epic pages play in a Notion/Confluence PRD.
 - **Linear comments live on Issues, not on Projects.** This skill aggregates comments from every issue under the project to capture decisions and engineering notes. Project-level discussion that isn't reflected on an issue is invisible to this skill.
 
 ## Modes
@@ -127,10 +127,10 @@ If env vars are not available, ask the user to provide them explicitly before pr
 
 ### Phase 1: Fetch & Analyze the PRD
 
-1. **Resolve the project** via `mcp__linear-server__get_project` with the slug or ID, including milestones and resources (`includeMilestones: true`, `includeResources: true`). Capture the project title, description, state, labels, lead, dates, attached documents, attached links.
-2. **Fetch attached Linear documents** via `mcp__linear-server__list_documents({projectId})` then `get_document` per result. Treat each as additional PRD content. (A Linear PRD with a single rich project description and no attached documents is the common case; multi-document PRDs are valid too.)
-3. **Identify candidate epics and user stories** from project sub-issues via `mcp__linear-server__list_issues({project: <id>})`. Capture identifier, title, description, labels, state, parent issue, and `parentId` chain so the issue hierarchy is reproducible.
-4. **Fetch full comments per sub-issue** via `mcp__linear-server__list_comments({issueId})` for every issue surfaced in step 3. Walk thread parents/children — comments are threaded via `parentId` references on the comment object.
+1. **Resolve the project** via `lisa:linear-access operation: get-project` with the slug or ID, including milestones and resources (`includeMilestones: true`, `includeResources: true`). Capture the project title, description, state, labels, lead, dates, attached documents, attached links.
+2. **Fetch attached Linear documents** via `lisa:linear-access operation: list-documents({projectId})` then `lisa:linear-access operation: get-document` per result. Treat each as additional PRD content. (A Linear PRD with a single rich project description and no attached documents is the common case; multi-document PRDs are valid too.)
+3. **Identify candidate epics and user stories** from project sub-issues via `lisa:linear-access operation: list-issues({project: <id>})`. Capture identifier, title, description, labels, state, parent issue, and `parentId` chain so the issue hierarchy is reproducible.
+4. **Fetch full comments per sub-issue** via `lisa:linear-access operation: list-comments({issueId})` for every issue surfaced in step 3. Walk thread parents/children — comments are threaded via `parentId` references on the comment object.
 5. **Synthesize decisions and blockers** from the project description + every document + every issue comment:
    - Decisions already confirmed by the team (look for agreement in comment threads)
    - Open questions that need product/engineering input

package/plugins/lisa-cursor/skills/linear-validate-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: linear-validate-issue
 description: "Validates a proposed Linear work item spec (Project, Issue, or sub-Issue) — or an existing Linear item — against the organizational quality gates without writing anything. Returns a structured PASS/FAIL report per gate with concrete remediation. Single source of truth for what makes a valid Linear item — both the write path (linear-write-issue runs it pre-write) and the dry-run path (linear-to-tracker runs it during PRD intake) call this skill so the bar can never drift."
-allowed-tools: ["Bash", "mcp__linear-server__list_teams", "mcp__linear-server__get_team", "mcp__linear-server__list_projects", "mcp__linear-server__get_project", "mcp__linear-server__list_issues", "mcp__linear-server__get_issue", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+allowed-tools: ["Skill", "Bash"]
 ---
 
 # Validate Linear Work Item: $ARGUMENTS
@@ -65,7 +65,7 @@ build_ready: true                 # caller asserts the build-ready role (status:
 child_refs: ["ENG-601", "ENG-602"]   # known child work (sub-issues / project-member issues / blocked_by parentage) — see S15
 ```
 
-If the caller passes only an identifier, fetch the item via `mcp__linear-server__get_issue` (Issue) or `mcp__linear-server__get_project` (Project), derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa:linear-read-issue`) so S15 can classify the item — then run gates.
+If the caller passes only an identifier, fetch the item via `lisa:linear-access operation: get-issue` (Issue) or `lisa:linear-access operation: get-project` (Project), derive the same fields from the fetched data — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa:linear-read-issue`) so S15 can classify the item — then run gates.
 
 ## Gates
 
@@ -235,28 +235,28 @@ Remediation: `"Build-ready (status:ready) is leaf-only per leaf-only-lifecycle.
 
 #### F1 — Issue type valid in team
 
-For Issue types: confirm the team supports the issue type via `mcp__linear-server__get_team`. Linear issue types are typically per-team; check that the requested type exists.
+For Issue types: confirm the team supports the issue type via `lisa:linear-access operation: get-team`. Linear issue types are typically per-team; check that the requested type exists.
 
 For Epic (Project): confirm the team allows projects.
 
 #### F2 — Project parent exists and is in same team
 
-When `parent_project_id` is set: fetch via `mcp__linear-server__get_project`, confirm it exists and belongs to the configured team.
+When `parent_project_id` is set: fetch via `lisa:linear-access operation: get-project`, confirm it exists and belongs to the configured team.
 
-When `parent_issue_id` is set (Sub-task case): fetch via `mcp__linear-server__get_issue`, confirm the issue is non-Sub-task and in the same team / project.
+When `parent_issue_id` is set (Sub-task case): fetch via `lisa:linear-access operation: get-issue`, confirm the issue is non-Sub-task and in the same team / project.
 
 #### F3 — Linked items exist
 
-For each entry in `relations`, call `mcp__linear-server__get_issue` to confirm the identifier resolves. Flag broken identifiers.
+For each entry in `relations`, call `lisa:linear-access operation: get-issue` to confirm the identifier resolves. Flag broken identifiers.
 
 #### F4 — Required labels exist (or can be created)
 
-For each label referenced (`status:*`, `component:<name>`, `prd-*`), confirm via `mcp__linear-server__list_issue_labels` (or `list_project_labels` for Project labels) that it exists OR is creatable. Linear labels are team-scoped or workspace-scoped; flag if the requested scope is wrong.
+For each label referenced (`status:*`, `component:<name>`, `prd-*`), confirm via `lisa:linear-access operation: list-issue-labels` (or `lisa:linear-access operation: list-project-labels` for Project labels) that it exists OR is creatable. Linear labels are team-scoped or workspace-scoped; flag if the requested scope is wrong.
 
 ## Execution
 
 1. Parse `$ARGUMENTS`. If it's an identifier, fetch the item and derive the spec from the fetched fields — including `build_ready` (label set contains `status:ready`) and `child_refs` (sub-issues, project-member issues, plus `blocked_by` parentage, resolved as in `lisa:linear-read-issue`) so S15 can classify the item. Otherwise parse the YAML spec.
-2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})` if any feasibility gate will run.
+2. Resolve team ID via `lisa:linear-access operation: list-teams({query: <teamKey>})` if any feasibility gate will run.
 3. Run every Specification gate in order. Collect PASS / FAIL / N/A with a one-line reason.
 4. Unless the caller passed `--spec-only` (dry-run), run every Feasibility gate. Collect results.
 5. Emit the report below.

package/plugins/lisa-cursor/skills/linear-verify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: linear-verify
 description: "Verifies a Linear work item meets organizational standards by fetching the live item and running it through lisa:linear-validate-issue. Catches anything dropped or reformatted on write — same gates as the pre-write check, but applied to what Linear actually stored. Read-only."
-allowed-tools: ["Bash", "Skill", "mcp__linear-server__list_teams", "mcp__linear-server__get_issue", "mcp__linear-server__get_project", "mcp__linear-server__list_issue_labels", "mcp__linear-server__list_project_labels"]
+allowed-tools: ["Bash", "Skill"]
 ---
 
 # Verify Linear Work Item: $ARGUMENTS
@@ -25,14 +25,14 @@ If `$ARGUMENTS` is not parseable, stop and report.
 ## Phase 1 — Resolve Context
 
 1. Read `linear.workspace`, `linear.teamKey` from `.lisa.config.json` (with `.local` override).
-2. Resolve team ID via `mcp__linear-server__list_teams({query: <teamKey>})`.
+2. Resolve team ID via `lisa:linear-access operation: list-teams({query: <teamKey>})`.
 3. Determine entity type from the identifier shape:
    - `<TEAM>-<n>` → Issue
    - URL containing `/project/<slug>-<id>` → Project
 
 ## Phase 2 — Fetch Live State
 
-Call `mcp__linear-server__get_issue` (for Issues) or `mcp__linear-server__get_project` (for Projects). Capture every field, label, relation, comment, milestone, and project membership.
+Call `lisa:linear-access operation: get-issue` (for Issues) or `lisa:linear-access operation: get-project` (for Projects). Capture every field, label, relation, comment, milestone, and project membership.
 
 ## Phase 3 — Delegate to Validator
 

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

@@ -1,7 +1,7 @@
 ---
 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"]
+allowed-tools: ["Bash", "Skill"]
 ---
 
 # Write Linear Work Item: $ARGUMENTS
@@ -25,11 +25,11 @@ Linear's data model maps Epic / Story / Sub-task to **different entity types**.
 
 | `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 |
+| `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.
 
@@ -40,7 +40,7 @@ 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.
+Resolve the team ID for `linear.teamKey` via `lisa:linear-access operation: list-teams({query: <teamKey>})`. Cache it.
 
 ## Phase 2 — Gather Required Inputs
 
@@ -129,7 +129,7 @@ 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"]})
+   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.
@@ -152,16 +152,16 @@ If the git search surfaces a PR or commit that relates to this work, capture the
 
 ```text
 # Open items in the same Project
-mcp__linear-server__list_issues({project: <projectId>, state_type: ["unstarted", "started"]})
+lisa:linear-access operation: 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"]})
+lisa:linear-access operation: list-issues({query: "<keyword>", state_type: ["unstarted", "started"]})
 
 # Items with shared labels
-mcp__linear-server__list_issues({label: "<label>", updatedAt: ">-30d"})
+lisa:linear-access operation: 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"})
+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.
@@ -229,7 +229,7 @@ The validator is the **single source of truth** for what makes a valid Linear wo
 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.
+- 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.
 
@@ -237,15 +237,15 @@ If the validator reports `PASS`, continue to Phase 6.
 
 ### 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.
+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 `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.
+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.
@@ -253,13 +253,13 @@ If the validator reports `PASS`, continue to Phase 6.
 ### 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`.
+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 `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.
+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 `usage-accounting` serializer/merge path rather than freehand edits to ledger rows.
 
 ## Phase 7 — Verify
@@ -268,7 +268,7 @@ Call the `lisa:linear-verify` skill on the resulting item. `lisa:linear-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:
+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)

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

@@ -1,7 +1,7 @@
 ---
 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"]
+allowed-tools: ["Skill", "Bash"]
 ---
 
 # Write Linear PRD: $ARGUMENTS
@@ -37,17 +37,17 @@ PROGRESSED=("$PRD_IN_REVIEW" "$PRD_BLOCKED" "$PRD_TICKETED" "$PRD_SHIPPED" "$PRD
 ```
 
 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).
+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. `mcp__linear-server__list_projects` scoped to the team/workspace (filtered by the `prd-*` label
+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
-   `mcp__linear-server__get_project` for the marker. If `source_ref` was passed, target it directly.
+   `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
@@ -59,7 +59,7 @@ dedupe. If the live Project description already contains the canonical managed `
 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:
+**CREATE:** `lisa:linear-access operation: save-project` with:
 - `name`: `$TITLE`
 - `description`: the marker-normalized full PRD markdown
 - `teamIds`: `[<resolved team id>]`

package/plugins/lisa-cursor/skills/posthog-access/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: posthog-access
+description: "Vendor-neutral access layer for PostHog. PostHog skills and observability rules MUST delegate through this skill rather than calling PostHog MCP tools or REST directly. Resolves PostHog MCP first when available, then falls back to POSTHOG_PERSONAL_API_KEY bearer auth."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# PostHog Access: $ARGUMENTS
+
+Single chokepoint for PostHog operations. Caller skills and rules MUST NOT call
+`mcp__posthog__*` tools or PostHog REST directly.
+
+## Invocation Contract
+
+```text
+operation: query project_id:<ID> payload:{...}
+operation: insights project_id:<ID>
+operation: persons project_id:<ID> [query:<QUERY>]
+operation: events project_id:<ID> [after:<ISO>] [before:<ISO>]
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. PostHog MCP, if available and authenticated.
+2. `POSTHOG_PERSONAL_API_KEY` bearer token against the configured PostHog host.
+
+PostHog documents personal API keys and bearer authentication. The headless REST
+tier uses:
+
+```bash
+POSTHOG_HOST=${POSTHOG_HOST:-https://app.posthog.com}
+posthog_api() {
+  local path="$1"
+  local method="${2:-GET}"
+  local body="${3:-}"
+  [ -n "$POSTHOG_PERSONAL_API_KEY" ] || {
+    echo "Error: POSTHOG_PERSONAL_API_KEY is not set." >&2
+    return 1
+  }
+  local args=(-sS -X "$method" -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY")
+  [ -n "$body" ] && args+=(-H "Content-Type: application/json" --data-binary "$body")
+  curl "${args[@]}" "${POSTHOG_HOST%/}/api${path}"
+}
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no PostHog access substrate available. Authenticate the PostHog MCP or set POSTHOG_PERSONAL_API_KEY.
+```
+
+## Invariants
+
+- Fallback is gated on `POSTHOG_PERSONAL_API_KEY`.
+- `POSTHOG_HOST` defaults to PostHog Cloud but can point at a self-hosted
+  deployment.
+- Consumer skills do not embed PostHog REST paths.