@codyswann/lisa 2.176.11 → 2.177.0

package/plugins/lisa-agy/skills/linear-access/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear-access
+description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Resolves Linear MCP first when authenticated, then falls back to LINEAR_API_KEY + Linear GraphQL in headless environments."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Linear Access: $ARGUMENTS
+
+Single chokepoint for Linear operations. Caller skills (`linear-*`) MUST go
+through this skill. They MUST NOT call `mcp__linear-server__*` tools directly or
+curl `https://api.linear.app/graphql` themselves.
+
+## Invocation Contract
+
+```text
+operation: list-teams [query:<KEY>]
+operation: get-team id:<ID>
+operation: list-projects [team:<KEY>] [label:<NAME>] [state:<arr>]
+operation: get-project id:<ID>
+operation: save-project payload:{...}
+operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state_type:<arr>]
+operation: get-issue id:<ID>
+operation: save-issue payload:{...}
+operation: list-comments issue_id:<ID>
+operation: save-comment issue_id:<ID> body:"..."
+operation: list-issue-labels [team:<ID>]
+operation: create-issue-label payload:{...}
+operation: list-project-labels
+operation: create-project-label payload:{...}
+operation: list-documents project_id:<ID>
+operation: get-document id:<ID>
+```
+
+Return parsed JSON in a `<result>` block. On failure, prefix the message with
+`Error:` and include the failing operation name.
+
+## Substrate Selection
+
+Read config:
+
+```bash
+WORKSPACE=$(jq -r '.linear.workspace // empty' .lisa.config.json 2>/dev/null)
+TEAM_KEY=$(jq -r '.linear.teamKey // empty' .lisa.config.json 2>/dev/null)
+```
+
+Probe in order:
+
+1. Linear MCP, if `mcp__linear-server__list_teams` is available and can list the
+   configured workspace/team.
+2. `LINEAR_API_KEY` with Linear GraphQL (`https://api.linear.app/graphql`).
+
+The Linear GraphQL docs support personal API keys for scripts and authenticate
+with an `Authorization: <API_KEY>` header. Treat `LINEAR_API_KEY` as the
+headless substrate. If neither tier works, fail with:
+
+```text
+Error: no Linear access substrate available. Authenticate the Linear MCP or set LINEAR_API_KEY.
+```
+
+## GraphQL Adapter
+
+All GraphQL calls use:
+
+```bash
+linear_graphql() {
+  local query="$1"
+  local variables="${2:-{}}"
+  [ -n "$LINEAR_API_KEY" ] || {
+    echo "Error: LINEAR_API_KEY is not set." >&2
+    return 1
+  }
+  jq -n --arg query "$query" --argjson variables "$variables" \
+    '{query:$query, variables:$variables}' |
+    curl -sS -X POST "https://api.linear.app/graphql" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: '"$LINEAR_API_KEY"'" \
+      --data-binary @-
+}
+```
+
+Map operation names to Linear GraphQL queries/mutations in this access skill.
+Consumers pass business-shaped arguments only; they do not embed GraphQL.
+
+## Invariants
+
+- MCP is preferred when it is present and already authenticated.
+- GraphQL fallback runs only when `LINEAR_API_KEY` is present.
+- Missing MCP plus missing token is a hard failure naming `LINEAR_API_KEY`.
+- Mutations send only the fields being changed, matching existing Linear skill
+  guidance that `save_*` style updates should not clobber unrelated fields.

package/plugins/lisa-agy/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.

package/plugins/lisa-agy/skills/sentry-access/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: sentry-access
+description: "Vendor-neutral access layer for Sentry. Sentry-oriented skills MUST delegate through this skill rather than calling Sentry MCP tools, sentry-cli, or REST directly. Resolves Sentry MCP/CLI first when available, then falls back to SENTRY_AUTH_TOKEN + Sentry REST API."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Sentry Access: $ARGUMENTS
+
+Single chokepoint for Sentry operations. Caller skills MUST NOT call
+`mcp__sentry__*`, `sentry-cli`, or `https://sentry.io/api/` directly.
+
+## Invocation Contract
+
+```text
+operation: list-issues org:<ORG> project:<PROJECT> query:<QUERY> [environment:<ENV>]
+operation: get-issue issue_id:<ID>
+operation: events org:<ORG> project:<PROJECT> query:<QUERY>
+operation: releases org:<ORG> project:<PROJECT>
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Sentry MCP, if available and authenticated.
+2. `sentry-cli`, if installed and authenticated to the requested org/project.
+3. `SENTRY_AUTH_TOKEN` bearer token against Sentry REST.
+
+Sentry documents API auth tokens for REST API calls. The headless REST tier uses:
+
+```bash
+sentry_api() {
+  local path="$1"
+  [ -n "$SENTRY_AUTH_TOKEN" ] || {
+    echo "Error: SENTRY_AUTH_TOKEN is not set." >&2
+    return 1
+  }
+  curl -sS "https://sentry.io/api/0${path}" \
+    -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
+}
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no Sentry access substrate available. Authenticate Sentry MCP/CLI or set SENTRY_AUTH_TOKEN.
+```
+
+## Invariants
+
+- Fallback is gated on `SENTRY_AUTH_TOKEN`.
+- Org/project come from `.sentryclirc`, `.lisa.config.json`, or explicit
+  operation args; never infer by searching all accessible orgs.
+- Consumer skills do not embed Sentry REST paths.

package/plugins/lisa-agy/skills/sonarcloud-access/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: sonarcloud-access
+description: "Vendor-neutral access layer for SonarCloud/SonarQube Cloud. Sonar triage skills MUST delegate through this skill rather than calling Sonar MCP tools or REST directly. Resolves Sonar MCP first when available, then falls back to SONAR_TOKEN + SonarCloud Web API."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# SonarCloud Access: $ARGUMENTS
+
+Single chokepoint for SonarCloud operations. Caller skills MUST NOT call
+`mcp__sonarqube__*` tools directly or curl `https://sonarcloud.io/api/`
+themselves.
+
+## Invocation Contract
+
+```text
+operation: gate-status project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
+operation: issues project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>] [types:<csv>] [severities:<csv>]
+operation: hotspots project_key:<KEY> [branch:<BRANCH>] [pull_request:<N>]
+operation: rule-detail key:<RULE_KEY>
+operation: source-snippet component:<COMPONENT_KEY> from:<N> to:<N>
+```
+
+Return parsed JSON in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Sonar MCP, if available and authenticated.
+2. `SONAR_TOKEN` against the SonarCloud Web API.
+
+SonarCloud documents bearer-token authentication for the Web API. Use:
+
+```bash
+sonar_api() {
+  local path="$1"
+  [ -n "$SONAR_TOKEN" ] || {
+    echo "Error: SONAR_TOKEN is not set." >&2
+    return 1
+  }
+  curl -sS "https://sonarcloud.io/api${path}" \
+    -H "Authorization: Bearer $SONAR_TOKEN"
+}
+```
+
+If a host still requires the legacy token-as-basic-auth form, make that an
+explicit adapter branch in this skill; consumers do not choose auth style.
+
+If neither tier works, fail with:
+
+```text
+Error: no SonarCloud access substrate available. Authenticate the Sonar MCP or set SONAR_TOKEN.
+```
+
+## REST Dispatch
+
+| Operation | REST path |
+|---|---|
+| `gate-status` | `/qualitygates/project_status?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
+| `issues` | `/issues/search?componentKeys=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]...` |
+| `hotspots` | `/hotspots/search?projectKey=<KEY>[&branch=<BRANCH>][&pullRequest=<N>]` |
+| `rule-detail` | `/rules/show?key=<RULE_KEY>` |
+| `source-snippet` | `/sources/lines?key=<COMPONENT_KEY>&from=<N>&to=<N>` |
+
+## Invariants
+
+- Fallback is gated on `SONAR_TOKEN`.
+- SonarCloud host access requires `sonarcloud.io` in any custom remote network
+  allowlist.
+- Consumers ask for analysis data by operation name; this skill owns the Web API
+  path shape.

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.176.11",
+  "version": "2.177.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/hooks/setup-jira-cli.sh

@@ -5,9 +5,9 @@
 #
 # Required env vars (must be created in your Claude Code Web environment):
 #   JIRA_INSTALLATION - cloud or local
-#   JIRA_SERVER       - Atlassian instance URL
+#   JIRA_SERVER       - Atlassian instance URL (falls back to .lisa.config*.json atlassian.site)
 #   JIRA_LOGIN        - login email
-#   JIRA_PROJECT      - default project key
+#   JIRA_PROJECT      - default project key (falls back to .lisa.config*.json jira.project)
 #   JIRA_API_TOKEN    - already expected by jira-cli natively
 #
 # Optional env vars:
@@ -31,6 +31,40 @@ fi
 CONFIG_DIR="${HOME}/.config/.jira"
 CONFIG_FILE="${CONFIG_DIR}/.config.yml"
 
+read_lisa_config() {
+  local query="$1"
+  local value=""
+
+  if ! command -v jq &>/dev/null; then
+    return 0
+  fi
+
+  if [[ -f ".lisa.config.local.json" ]]; then
+    value=$(jq -r "${query} // empty" .lisa.config.local.json 2>/dev/null || true)
+  fi
+
+  if [[ -z "${value}" && -f ".lisa.config.json" ]]; then
+    value=$(jq -r "${query} // empty" .lisa.config.json 2>/dev/null || true)
+  fi
+
+  printf '%s' "${value}"
+}
+
+if [[ -z "${JIRA_SERVER:-}" ]]; then
+  ATLASSIAN_SITE="$(read_lisa_config '.atlassian.site')"
+  if [[ -n "${ATLASSIAN_SITE}" ]]; then
+    if [[ "${ATLASSIAN_SITE}" == http://* || "${ATLASSIAN_SITE}" == https://* ]]; then
+      JIRA_SERVER="${ATLASSIAN_SITE}"
+    else
+      JIRA_SERVER="https://${ATLASSIAN_SITE}"
+    fi
+  fi
+fi
+
+if [[ -z "${JIRA_PROJECT:-}" ]]; then
+  JIRA_PROJECT="$(read_lisa_config '.jira.project')"
+fi
+
 # Skip config write if required vars are missing
 if [[ -z "${JIRA_SERVER:-}" || -z "${JIRA_LOGIN:-}" ]]; then
   exit 0

package/plugins/lisa-copilot/rules/eager/integration-access-layer.md

@@ -0,0 +1,10 @@
+# Integration Access Layer
+
+Skills and rules that use external integrations route through the matching
+`*-access` skill. Do not call vendor MCP tools or REST APIs directly from a
+consumer skill.
+
+Resolution order is MCP when available and authenticated, then documented
+token/REST substrate when the env var is set, then a loud error naming the env
+var. Full matrix and migration rules:
+[reference/integration-access-layer.md](../reference/integration-access-layer.md).

package/plugins/lisa-copilot/rules/reference/integration-access-layer.md

@@ -0,0 +1,56 @@
+# Integration Access Layer
+
+Every Lisa skill or rule that consumes an external integration MUST route through
+the integration's `*-access` skill instead of calling that vendor's MCP tools or
+REST API directly.
+
+The access skill owns substrate resolution:
+
+1. MCP, when the tool is available and already authenticated to the configured
+   workspace/account.
+2. Token/REST substrate, only when the documented env var is present.
+3. Loud failure naming the exact env var to set.
+
+Do not blind-retry a failed or absent MCP. Fall back only after checking the
+documented env var for that vendor, and never silently no-op when neither tier is
+available.
+
+## Access Skills
+
+| Vendor | Access skill | Headless env var | REST/token substrate |
+|---|---|---|---|
+| Atlassian | `lisa:atlassian-access` | `ATLASSIAN_API_TOKEN` | Atlassian Cloud REST |
+| Notion | `lisa:notion-access` | `NOTION_API_TOKEN` | Notion REST |
+| Linear | `lisa:linear-access` | `LINEAR_API_KEY` | Linear GraphQL |
+| Jam | `lisa:jam-access` | `JAM_PAT` | Jam MCP HTTP endpoint with bearer PAT |
+| SonarCloud | `lisa:sonarcloud-access` | `SONAR_TOKEN` | SonarCloud Web API |
+| Sentry | `lisa:sentry-access` | `SENTRY_AUTH_TOKEN` | Sentry REST API |
+| PostHog | `lisa:posthog-access` | `POSTHOG_PERSONAL_API_KEY` | PostHog REST API |
+
+## Current Coupling Matrix
+
+Source audit date: 2026-06-23. Scope: `plugins/src/**/skills/**` and
+`plugins/src/**/rules/**`.
+
+| Vendor | Direct source MCP references | Current route | Retrofit status |
+|---|---:|---|---|
+| Atlassian | setup-only references plus legacy stack-generated sources | `atlassian-access` for base runtime paths | Done for base hot paths; stack overlays still need sync from base patterns when touched. |
+| Notion | setup-only references | `notion-access` | Done. |
+| Linear | Multiple base queue/read/write/verify skills | Raw Linear MCP | Access layer added; consumers still need migration to `linear-access`. |
+| Jam | None in `plugins/src` at audit time | No access layer | Access layer added for host rules that include Jam triage. |
+| SonarCloud | None in `plugins/src` at audit time | No access layer | Access layer added for host rules that include SonarCloud gate triage. |
+| Sentry | No Sentry MCP references in `plugins/src`; CLI/REST mentions only | CLI/REST scattered in observability docs | Access layer added for future MCP-backed consumers. |
+| PostHog | No PostHog MCP references in `plugins/src`; observability docs mention PostHog detection | No access layer | Access layer added for future MCP-backed consumers. |
+
+## Migration Rule For Consumers
+
+When editing any skill listed in the matrix:
+
+- Replace direct `mcp__<vendor>__*` calls in `allowed-tools` with `Skill` and
+  delegate to the matching access skill.
+- Keep operation names coarse and vendor-native. Add new operation rows to the
+  access skill instead of embedding REST details in the consumer.
+- Preserve existing MCP behavior as the first tier where Claude/Codex can expose
+  the MCP, but make headless token fallback explicit and gated by the env var.
+- If a vendor has no documented token substrate, keep the MCP-only behavior and
+  fail with a clear "no documented headless substrate" message.

package/plugins/lisa-copilot/skills/jam-access/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jam-access
+description: "Vendor-neutral access layer for Jam. Jam triage rules and skills MUST delegate through this skill rather than calling Jam MCP tools directly. Resolves Jam MCP first when available, then falls back to JAM_PAT bearer auth for headless routines."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Jam Access: $ARGUMENTS
+
+Single chokepoint for Jam operations. Caller skills and rules MUST NOT call
+`mcp__Jam__*` tools directly.
+
+## Invocation Contract
+
+```text
+operation: get-trace url:<jam-url-or-id>
+operation: get-recording url:<jam-url-or-id>
+operation: get-bug-report url:<jam-url-or-id>
+```
+
+Return parsed JSON or a concise structured summary in a `<result>` block.
+
+## Substrate Selection
+
+Probe in order:
+
+1. Jam MCP, if the tool is available and authenticated.
+2. `JAM_PAT` bearer token against Jam's MCP/trace HTTP substrate.
+
+Jam documents personal access tokens for MCP clients so a browser OAuth flow is
+not required. The headless tier uses:
+
+```bash
+curl -sS "https://mcp.jam.dev/mcp" \
+  -H "Authorization: Bearer $JAM_PAT" \
+  -H "Content-Type: application/json" \
+  --data-binary "$PAYLOAD"
+```
+
+If neither tier works, fail with:
+
+```text
+Error: no Jam access substrate available. Authenticate the Jam MCP or set JAM_PAT.
+```
+
+## Invariants
+
+- Fallback is gated on `JAM_PAT`; do not retry Jam MCP failures blindly.
+- Never commit a Jam PAT into `.mcp.json`. Use env interpolation in host MCP
+  config, for example `Authorization: Bearer ${JAM_PAT}`.
+- If a requested operation is not yet mapped to the Jam HTTP substrate, surface
+  that exact missing adapter instead of pretending the trace is unavailable.

package/plugins/lisa-copilot/skills/linear-access/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear-access
+description: "Vendor-neutral access layer for Linear. Linear skills MUST delegate through this skill rather than calling Linear MCP tools or Linear GraphQL directly. Resolves Linear MCP first when authenticated, then falls back to LINEAR_API_KEY + Linear GraphQL in headless environments."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Linear Access: $ARGUMENTS
+
+Single chokepoint for Linear operations. Caller skills (`linear-*`) MUST go
+through this skill. They MUST NOT call `mcp__linear-server__*` tools directly or
+curl `https://api.linear.app/graphql` themselves.
+
+## Invocation Contract
+
+```text
+operation: list-teams [query:<KEY>]
+operation: get-team id:<ID>
+operation: list-projects [team:<KEY>] [label:<NAME>] [state:<arr>]
+operation: get-project id:<ID>
+operation: save-project payload:{...}
+operation: list-issues [team:<ID>] [project:<ID>] [label:<NAME>] [state_type:<arr>]
+operation: get-issue id:<ID>
+operation: save-issue payload:{...}
+operation: list-comments issue_id:<ID>
+operation: save-comment issue_id:<ID> body:"..."
+operation: list-issue-labels [team:<ID>]
+operation: create-issue-label payload:{...}
+operation: list-project-labels
+operation: create-project-label payload:{...}
+operation: list-documents project_id:<ID>
+operation: get-document id:<ID>
+```
+
+Return parsed JSON in a `<result>` block. On failure, prefix the message with
+`Error:` and include the failing operation name.
+
+## Substrate Selection
+
+Read config:
+
+```bash
+WORKSPACE=$(jq -r '.linear.workspace // empty' .lisa.config.json 2>/dev/null)
+TEAM_KEY=$(jq -r '.linear.teamKey // empty' .lisa.config.json 2>/dev/null)
+```
+
+Probe in order:
+
+1. Linear MCP, if `mcp__linear-server__list_teams` is available and can list the
+   configured workspace/team.
+2. `LINEAR_API_KEY` with Linear GraphQL (`https://api.linear.app/graphql`).
+
+The Linear GraphQL docs support personal API keys for scripts and authenticate
+with an `Authorization: <API_KEY>` header. Treat `LINEAR_API_KEY` as the
+headless substrate. If neither tier works, fail with:
+
+```text
+Error: no Linear access substrate available. Authenticate the Linear MCP or set LINEAR_API_KEY.
+```
+
+## GraphQL Adapter
+
+All GraphQL calls use:
+
+```bash
+linear_graphql() {
+  local query="$1"
+  local variables="${2:-{}}"
+  [ -n "$LINEAR_API_KEY" ] || {
+    echo "Error: LINEAR_API_KEY is not set." >&2
+    return 1
+  }
+  jq -n --arg query "$query" --argjson variables "$variables" \
+    '{query:$query, variables:$variables}' |
+    curl -sS -X POST "https://api.linear.app/graphql" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: '"$LINEAR_API_KEY"'" \
+      --data-binary @-
+}
+```
+
+Map operation names to Linear GraphQL queries/mutations in this access skill.
+Consumers pass business-shaped arguments only; they do not embed GraphQL.
+
+## Invariants
+
+- MCP is preferred when it is present and already authenticated.
+- GraphQL fallback runs only when `LINEAR_API_KEY` is present.
+- Missing MCP plus missing token is a hard failure naming `LINEAR_API_KEY`.
+- Mutations send only the fields being changed, matching existing Linear skill
+  guidance that `save_*` style updates should not clobber unrelated fields.

package/plugins/lisa-copilot/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.