@codyswann/lisa 2.189.7 → 2.189.8

package/plugins/lisa/skills/lisa-tracker-sync/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: lisa-tracker-sync
+description: "Vendor-neutral wrapper for posting milestone updates to the linked ticket/issue. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa-jira-sync, lisa-github-sync, or lisa-linear-sync. Posts at: plan created, implementation in progress, PR ready, PR merged. Suggests (never auto-transitions) the next status."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Sync: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor sync skill.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Dispatch:
+   - `jira` → invoke `lisa-jira-sync` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa-github-sync` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa-linear-sync` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the output.
+
+`$ARGUMENTS` is forwarded verbatim, including the optional `--rollup` flag (see "Parent status rollup" below), `--update-label`, `pr_url=<url>`, and `merge_sha=<sha>`. The shim never interprets these — the vendor skill does.
+
+If `$ARGUMENTS` is empty, all vendor skills auto-detect a ticket reference from the active plan file (most recently modified `.md` in `plans/`).
+
+## Parent status rollup (`--rollup`)
+
+When the caller passes `--rollup` after the milestone, the dispatch target additionally **derives the parent/container's lifecycle state from its children** instead of acting on the work item directly. This is the vendor-neutral implementation of the **Parent status rollup (the state machine)** section of the `leaf-only-lifecycle` rule — cite that rule, do not restate the policy here. The shim is dispatch only; the rollup mechanics live in the vendor sync skill (`lisa-github-sync`, `lisa-jira-sync`, `lisa-linear-sync`), which resolves child membership via its `*-read-*` skill and evaluates the state machine below.
+
+The state machine (first match wins, evaluated over the **required** leaves only, on the env ladder `in-progress < dev < staging < production` — the ordered keys of the project's env-keyed `done` map):
+
+| If among the required leaves… | …the parent rolls up to | Role |
+|---|---|---|
+| any leaf is **blocked** | blocked / attention-needed | `blocked` |
+| else **every** required leaf has shipped to some env (each at a `done`-map value) | the **least-advanced** env among them | `done[min-env]` (terminal `done` at production) |
+| else any leaf has **started** (claimed or in review, or shipped while a sibling has not) | active / in-progress | `claimed` (or `review` where supported) |
+| else (leaves exist, none started) | unchanged | — |
+
+- **Blocked dominates** — one blocked leaf surfaces blocked on the parent even while others progress.
+- **Least-advanced env wins** — a parent reaches an env only once all required leaves have reached at least that env (all `On Stg` → `On Stg`; mixed dev/staging → the dev value). Native terminal closure fires only at the production `done`, never at an intermediate env.
+- **The parent never carries `ready`** — `ready` is a human "claim this leaf" signal; rollup only moves a parent between non-ready container states.
+- **Rollup is recursive** — an Epic rolls up from its Stories, each of which rolls up from its own leaves. Evaluate bottom-up.
+- **The env rungs are the configured env-keyed `done`** — multi-env projects roll up to whichever `done` value (including intermediate `On Dev`/`On Stg`) their leaves have collectively reached (see `config-resolution` "Env-keyed `done`"). **Single-environment collapse (this repo):** `deploy.branches` declares only `production: main`, so `done` is a single value, the only env rung is production, and the GitHub build lifecycle collapses to `ready → claimed (in-progress) → done`; the rollup terminal is simply `done` (or the PRD-side `ticketed` for PRD containers), with **no** dev/staging promotion hops and **no** env-keyed multi-entry chain to resolve.
+
+**Safe-by-default when not yet supported.** A vendor sync path that has not implemented native rollup MUST be a documented no-op that surfaces the derived state as a suggestion/comment rather than guessing a transition — never an unsafe default. Without `--rollup`, the sync skills behave exactly as before (milestone comment on the work item; no parent derivation).
+
+## Pull request backlinking
+
+When `$ARGUMENTS` includes `pr_url=<url>` with milestone `pr-ready` or `pr-merged`, the dispatch target must ensure ticket -> PR linkage, not just post a generic progress note:
+
+1. Prefer the provider's native development-link primitive when Lisa can write and verify it for that provider.
+2. Verify the native link using the provider read surface when available.
+3. If the native link is unavailable, unconfigured, cross-system, or cannot be verified, create or update one managed backlink comment on the work item containing the PR URL and current milestone.
+4. Keep the comment idempotent by using a stable marker such as `[lisa-pr-link]`; reruns update or skip the existing managed comment rather than appending duplicates.
+
+This is the reverse half of `lisa-git-submit-pr`'s PR body linkage. A PR that mentions a ticket is not considered fully synced until the ticket also has either a verified native PR link or the managed fallback comment.
+
+## Rules
+
+- Idempotent updates — running sync at the same milestone twice should not produce duplicate comments. Vendor skills enforce this.
+- Never auto-transition the underlying state. Linear's label-based transition (`status:*`) is the canonical signal and is updated only when the caller passes `--update-label`. Native states stay as suggestions.
+- Parent rollup derives state from children per the `leaf-only-lifecycle` rule; it never sets a parent to `ready` and never resolves a dev/staging `done` in this single-environment repo.
+- Pull request backlinks are mandatory when `pr_url=<url>` is present: native first, managed-comment fallback, never silently dropped.

package/plugins/lisa/skills/lisa-tracker-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Tracker Sync"
+short_description: "Vendor-neutral wrapper for posting milestone updates to the linked ticket/issue"
+default_prompt:
+  - "Use $lisa-tracker-sync: Vendor-neutral wrapper for posting milestone updates to the linked ticket/issue."

package/plugins/lisa/skills/lisa-tracker-validate/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: lisa-tracker-validate
+description: "Vendor-neutral wrapper for the pre-write quality gate. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa-jira-validate-ticket, lisa-github-validate-issue, or lisa-linear-validate-issue. Read-only — never writes to any tracker. Used by tracker-write Phase 5.5 (pre-write gate), tracker-verify (post-write checks), and the *-to-tracker dry-run paths. Output is structured PASS/FAIL per gate so callers can parse it."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Validate: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor validator.
+
+See the `config-resolution` rule for the full configuration schema and skill-mapping table.
+
+## Workflow
+
+1. **Resolve tracker config** (same logic as `lisa-tracker-write` Step 1):
+
+   ```bash
+   local_tracker=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+   global_tracker=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+   tracker="${local_tracker:-${global_tracker:-jira}}"
+   ```
+
+2. **Dispatch**
+
+   - `jira` → invoke `lisa-jira-validate-ticket` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa-github-validate-issue` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa-linear-validate-issue` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+3. **Pass through the validator's structured report unchanged.** Callers (e.g. `lisa-jira-write-ticket` Phase 5.5) parse the gate lines; do not paraphrase.
+
+## Rules
+
+- Read-only — never write to any tracker.
+- Never re-implement gate logic here. The gate definitions are the vendor validator's responsibility.
+- Never silently transform the input — pass `$ARGUMENTS` through verbatim.

package/plugins/lisa/skills/lisa-tracker-validate/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Tracker Validate"
+short_description: "Vendor-neutral wrapper for the pre-write quality gate"
+default_prompt:
+  - "Use $lisa-tracker-validate: Vendor-neutral wrapper for the pre-write quality gate."

package/plugins/lisa/skills/lisa-tracker-verify/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: lisa-tracker-verify
+description: "Vendor-neutral wrapper for the post-write verification gate. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa-jira-verify, lisa-github-verify, or lisa-linear-verify. Fetches the live ticket/issue and runs the validator gates against the stored state — catches anything dropped or reformatted on write. Read-only."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Verify: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor post-write verifier.
+
+See the `config-resolution` rule for configuration and dispatch table.
+
+## Workflow
+
+1. Resolve tracker config (same logic as `lisa-tracker-write`).
+2. Dispatch:
+   - `jira` → invoke `lisa-jira-verify` with `$ARGUMENTS` verbatim.
+   - `github` → invoke `lisa-github-verify` with `$ARGUMENTS` verbatim.
+   - `linear` → invoke `lisa-linear-verify` with `$ARGUMENTS` verbatim.
+   - Anything else → stop and report `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+3. Pass through the verifier's structured report unchanged.
+
+## Rules
+
+- Read-only.
+- The same gates run pre-write and post-write — this shim simply chooses the vendor implementation.
+- If the vendor verify reports `FAIL`, callers must NOT auto-fix from this layer. Surface the failures to the caller and let the higher-level skill decide.
+- Duplicate closeout is not a verifier shortcut. A build-intake ticket may be auto-closed as duplicate only when downstream triage returns `DUPLICATE_ALREADY_FIXED` with a canonical ticket reference and empirical evidence that the canonical fix is present on the relevant base branch; ordinary verifier `FAIL`/`PASS` output never implies duplicate resolution.

package/plugins/lisa/skills/lisa-tracker-verify/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Tracker Verify"
+short_description: "Vendor-neutral wrapper for the post-write verification gate"
+default_prompt:
+  - "Use $lisa-tracker-verify: Vendor-neutral wrapper for the post-write verification gate."

package/plugins/lisa/skills/lisa-tracker-write/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: lisa-tracker-write
+description: "Vendor-neutral wrapper for ticket creation and updates. Reads `tracker` from .lisa.config.json (default: jira) and dispatches to lisa-jira-write-ticket, lisa-github-write-issue, or lisa-linear-write-issue. Callers in vendor-neutral skills (notion-to-tracker, linear-to-tracker, confluence-to-tracker, github-to-tracker, implement, verify) MUST invoke this skill instead of the vendor-specific ones — that is what makes the tracker switchable per project. The Phase-5.5 validate-pre-write gate, post-write verify, and Phase-8 announce-comment behavior live in the vendor skills; this shim is dispatch only."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Tracker Write: $ARGUMENTS
+
+Thin dispatcher. Resolves the configured destination tracker and delegates to the matching vendor
+write skill.
+
+When the incoming description/body already contains the canonical `## Lisa Usage` ledger, the vendor
+writer must preserve that managed section on update and use the `lisa-lisa-usage-accounting` contract for any
+body-vs-comment fallback. This shim only routes — it never edits tracker artifacts itself.
+
+See the `config-resolution` rule for the full configuration schema and skill-mapping table.
+
+## Workflow
+
+1. **Resolve tracker config**
+
+   Read `.lisa.config.local.json` first (if present), then `.lisa.config.json`. Local overrides global on a per-key basis. Use `jq` — never hand-parse JSON.
+
+   ```bash
+   local_tracker=$(jq -r '.tracker // empty' .lisa.config.local.json 2>/dev/null)
+   global_tracker=$(jq -r '.tracker // empty' .lisa.config.json 2>/dev/null)
+   tracker="${local_tracker:-${global_tracker:-jira}}"
+   ```
+
+2. **Validate the value**
+
+   - `jira` → confirm `atlassian.cloudId` and `jira.project` are present. If either is missing, stop and report: `"tracker=jira but atlassian.cloudId and jira.project are not set in .lisa.config.json."` Continue to Step 3a.
+   - `github` → confirm `github.org` and `github.repo` are present. If either is missing, stop and report: `"tracker=github but github.org and github.repo are not set in .lisa.config.json."` Continue to Step 3b.
+   - `linear` → confirm `linear.workspace` and `linear.teamKey` are present. If either is missing, stop and report: `"tracker=linear but linear.workspace and linear.teamKey are not set in .lisa.config.json."` Continue to Step 3c.
+   - Any other value → stop and report: `"Unknown tracker '<value>' in .lisa.config.json. Expected 'jira', 'github', or 'linear'."`
+
+3. **Dispatch**
+
+   - **3a (jira):** Invoke `lisa-jira-write-ticket` via the Skill tool, passing `$ARGUMENTS` verbatim.
+   - **3b (github):** Invoke `lisa-github-write-issue` via the Skill tool, passing `$ARGUMENTS` verbatim.
+   - **3c (linear):** Invoke `lisa-linear-write-issue` via the Skill tool, passing `$ARGUMENTS` verbatim.
+
+4. **Surface the vendor skill's output unchanged.** Do not paraphrase; downstream callers parse the structured response.
+
+## Rules
+
+- Never bypass dispatch — calling the vendor skill directly from a vendor-neutral caller defeats the per-project switch.
+- Never drop, duplicate, or hand-rewrite an existing managed `## Lisa Usage` section in this shim.
+  Writer-specific preservation logic belongs in the vendor writers and follows the
+  `lisa-lisa-usage-accounting` contract.
+- Never accept a tracker value outside `{jira, github, linear}`.
+- Never mutate `$ARGUMENTS` between layers. The vendor skills define their own input contract.
+- Never inline gate logic here. All validation rules live in the vendor skills (`lisa-jira-validate-ticket` / `lisa-github-validate-issue` / `lisa-linear-validate-issue`); this skill only routes.

package/plugins/lisa/skills/lisa-tracker-write/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Tracker Write"
+short_description: "Vendor-neutral wrapper for ticket creation and updates"
+default_prompt:
+  - "Use $lisa-tracker-write: Vendor-neutral wrapper for ticket creation and updates."

package/plugins/lisa/skills/lisa-usage-accounting/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: lisa-usage-accounting
+description: "Shared usage-ledger utility for Lisa lifecycle flows and artifact writers. Delegates all direct-entry recording and rollup refreshes through one vendor-neutral contract so PRDs, tickets, evidence comments, PRs, and markdown artifacts preserve the canonical `## Lisa Usage` section instead of inventing per-flow formats."
+allowed-tools: ["Skill", "Read", "Bash"]
+---
+
+# Usage Accounting: $ARGUMENTS
+
+Single chokepoint for Lisa usage-ledger writes. Caller skills (`research`, `plan`,
+`implement`, `verify`, `debrief`, `intake`, `prd-source-write`, `tracker-write`,
+`tracker-evidence`, later rollup/monitor flows) MUST delegate usage-entry writes and
+rollup refreshes through this skill rather than hand-editing artifact bodies or comments.
+
+This skill does not define the ledger format itself. The durable schema, token order,
+rewrite invariants, and rollup semantics live in the `usage-accounting` rule. This skill
+applies that contract to real artifacts and chooses the safest writable surface.
+
+## Invocation contract
+
+The caller passes exactly one operation plus its arguments:
+
+```text
+operation: record
+artifact_ref: github:CodySwannGT/lisa#729
+artifact_kind: github-issue
+entry: { ...LisaUsageEntry fields... }
+
+operation: rollup
+artifact_ref: github:CodySwannGT/lisa#724
+artifact_kind: github-issue
+child_refs:
+  - github:CodySwannGT/lisa#729
+  - github:CodySwannGT/lisa#730
+
+operation: record_and_rollup
+artifact_ref: github:CodySwannGT/lisa#724
+artifact_kind: github-issue
+entry: { ...LisaUsageEntry fields... }
+child_refs:
+  - github:CodySwannGT/lisa#729
+```
+
+Required arguments:
+
+- `operation`: one of `record`, `rollup`, or `record_and_rollup`.
+- `artifact_ref`: canonical artifact identifier for the target being updated.
+- `artifact_kind`: the writable host surface (`github-issue`, `github-pr-comment`, `jira-ticket`,
+  `linear-issue`, `notion-page`, `confluence-page`, `markdown-file`, or another caller-defined
+  host string with a matching read/write adapter).
+
+Operation-specific arguments:
+
+- `record` requires `entry`.
+- `rollup` requires `child_refs` (empty is allowed when the caller wants a direct-only refresh).
+- `record_and_rollup` requires `entry` and may also pass `child_refs`.
+
+Optional arguments:
+
+- `attachment_preference`: `body-first` (default) or `comment-only`.
+- `comment_ref`: existing managed comment identifier when the ledger already lives in a comment.
+- `parent_artifact_ref`: explicit parent for callers that need to anchor descendant rollups.
+- `existing_body`: caller-supplied body snapshot when it already owns a fresh read.
+
+The `entry` payload MUST satisfy the canonical usage-entry contract from the rule: stable
+`entry_id`, `flow`, `run_id`, provider/model, source semantics, token fields, pricing fields,
+and artifact refs. Callers do not get to omit the "unavailable" case; when trustworthy usage is
+missing they still pass an explicit entry with `source: unavailable` and nullable token/cost
+fields.
+
+## Return shape
+
+Return structured output so callers can persist or log what happened without reparsing prose:
+
+```yaml
+outcome: updated | comment-fallback | no-op | blocked
+artifact_ref: "github:CodySwannGT/lisa#729"
+surface:
+  kind: body | comment
+  ref: "<artifact or comment identifier>"
+entry_ids:
+  direct:
+    - "<entry-id>"
+  child:
+    - "<rolled-up-child-entry-id>"
+rollup:
+  direct_tokens: 1200
+  child_tokens: 450
+  total_tokens: 1650
+  direct_cost: 0.42
+  child_cost: 0.17
+  total_cost: 0.59
+warnings:
+  - "<warning text>"
+error:
+  code: "<stable-code>"
+  message: "<exact failure text>"
+  remediation: "<next step>"
+```
+
+- `updated` means the preferred writable surface was updated successfully.
+- `comment-fallback` means body/description edits were unsafe, so the canonical ledger landed in a
+  managed comment instead.
+- `no-op` means the requested operation produced byte-identical ledger output.
+- `blocked` means the caller asked for a write that could not be completed; preserve the exact host
+  failure text.
+
+## Workflow
+
+### Step 1 — Read the current managed surface
+
+1. Resolve the target artifact from `artifact_ref` / `artifact_kind`.
+2. Prefer a caller-supplied `existing_body` when present and trustworthy for this write.
+3. Otherwise read the current body/description from the host's native adapter.
+4. If the caller passed `comment_ref`, read that managed comment body too.
+
+Never guess the prior ledger state. Always start from the current managed body/comment so rewrite
+idempotency is preserved.
+
+### Step 2 — Choose the writable surface
+
+Default policy is **body first**:
+
+- If the host body/description is writable by the caller's normal writer path, update the body in
+  place and keep the canonical `## Lisa Usage` section there.
+- If direct body edits are unsafe, unavailable, or likely to clobber other writer-owned content,
+  fall back to a **single managed comment** containing the same canonical section.
+- If the caller explicitly passes `attachment_preference: comment-only`, skip the body attempt and
+  write the managed comment directly.
+
+The fallback is part of the contract, not an error. Writers should prefer the artifact body they
+already own, but evidence comments, immutable PR descriptions, or size-limited hosts may require
+the managed comment path.
+
+### Step 3 — Apply the requested operation
+
+All three operations use the shared utilities and rule contract; they differ only in which inputs
+they require and whether they recompute child totals:
+
+- `record`: upsert exactly one direct usage entry on the target artifact. Rewrite the entire
+  `## Lisa Usage` section in place using the canonical serializer; never append ad hoc rows.
+- `rollup`: recompute the rollup token and visible totals from the target's current direct entries
+  plus usage discovered from `child_refs`. Dedupe strictly by stable `entry_id`.
+- `record_and_rollup`: first upsert the direct entry, then refresh totals against `child_refs` in
+  the same managed write so callers do not produce split-brain ledger states.
+
+The implementation path should use the shared utility layer (`parseLisaUsageSection`,
+`mergeLisaUsageEntries`, `createLisaUsageRollup`, `upsertLisaUsageSection`) rather than duplicating
+token parsing or markdown rendering in each caller.
+
+### Step 4 — Persist and report
+
+1. If the rendered ledger body is byte-identical to the current managed surface, return `outcome:
+   no-op`.
+2. Otherwise write the body or managed comment through the host adapter.
+3. Return the exact writable surface used, direct entry ids, rolled-up child entry ids, totals, and
+   any fallback warning.
+
+If the host write fails, preserve the exact error text in `error.message`. Do not collapse write
+failures into a generic "usage update failed."
+
+## Rules
+
+- Never invent a per-flow usage format. All usage-ledger writes go through this skill and the
+  canonical `usage-accounting` rule.
+- Never append a second `## Lisa Usage` section or a second managed usage comment.
+- Never treat missing usage as zero. Callers must record explicit `source: unavailable` entries.
+- Never skip rollup dedupe. Child totals are keyed by stable `entry_id`, not by child ref count.
+- Never silently drop to comments. Return `outcome: comment-fallback` so the caller can surface the
+  writable surface that actually holds the ledger.
+- Never overwrite unrelated artifact body content. Rewrite only the managed usage section/comment.

package/plugins/lisa/skills/lisa-usage-accounting/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Usage Accounting"
+short_description: "Shared usage-ledger utility for Lisa lifecycle flows and artifact writers"
+default_prompt:
+  - "Use $lisa-usage-accounting: Shared usage-ledger utility for Lisa lifecycle flows and artifact writers."

package/plugins/lisa/skills/lisa-use-the-product/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: lisa-use-the-product
+description: Shared methodology for actually USING a project's product the way its real end user would — across product types (DOM web app, HTTP/API backend, canvas game, CLI/library, IaC/CDK). Detects the product's consumer-facing interface, drives it as that consumer, gated by a per-environment mutation policy read from .lisa.config.json (so the agent never mutates production data by accident), and lensed through the project's personas/subagents when it defines them. Invoked by exploratory-qa (files defect/UX tickets) and product-walkthrough (grounds planning in the live product); rarely run standalone.
+---
+
+# Use the Product
+
+## The one idea
+
+Every product has a **consumer-facing interface**. To evaluate a product you (1) **detect** that interface, (2) **resolve where you're allowed to drive it and how much you may change**, and (3) **drive it as the real consumer would** — through the project's personas when it has them. This skill owns steps 1–4 below; the **caller** decides what to *do* with what you find (`exploratory-qa` files tickets, `product-walkthrough` grounds planning).
+
+Driving the product means **interacting** with it. Static route scans, HTTP fetches, screenshots-alone, and reading the code are *supporting evidence only* — never a substitute for actually using it.
+
+## 1. Detect the product type & interface
+
+Infer from the repo; if genuinely ambiguous, ask one concise question.
+
+| Signals | Type | Consumer-facing interface |
+|---|---|---|
+| `vite`/`next`/`angular`/`svelte` + `index.html`, DOM UI | **DOM web app** | the rendered UI in a real browser |
+| API server (`nest`/`express`/`fastify`/serverless handlers), OpenAPI, no frontend | **HTTP / API backend** | the API endpoints |
+| `phaser`/`pixi`/canvas game | **Canvas game** | the canvas + input (keyboard/pointer), read visually |
+| `cdk.json` / Terraform / IaC | **IaC / CDK** | the resources it provisions (+ synth output) |
+| `bin/` CLI or published library, no server | **CLI / library** | the commands / public API |
+
+## 2. Resolve the environment & mutation policy — the gate
+
+Read the `exploration` block from `.lisa.config.json` (a repo-local config overrides a global one):
+
+```jsonc
+"exploration": {
+  "default": "<env-name>",              // which env to use when none is passed
+  "environments": {
+    "<name>": {
+      "url": "https://dev.example.io",  // web/API target (omit for local CLI/game)
+      "provision": true,                // IaC/ephemeral: stand up, then tear down
+      "mutation": "forbidden | read-only | full",
+      "identity": "<test-account ref>", // which login to use (env var / 1Password ref)
+      "prodMutationAck": "<one sentence>" // REQUIRED to allow `full` on a production-named env
+    }
+  }
+}
+```
+
+Resolve the target env: explicit argument → `default` → infer. Then the **mutation level governs everything**:
+
+- **`read-only`** — only non-mutating interactions: read endpoints (`GET`), view UI without submitting, `cdk synth`/`diff`, `--help`/dry-run. Never create / edit / delete.
+- **`full`** — create / edit / delete allowed, but **only as the `identity` test account** and under Mutation Discipline (§5).
+- **`forbidden`** — do not exercise this environment at all.
+
+**Safety rules — enforced regardless of config:**
+
+- **No `exploration` block, or an unconfigured env → treat as `read-only`.** Never mutate without an explicit policy.
+- **A production-named env (`prod` / `production`) defaults to `forbidden`.** It may be raised to `full` **only** when a written `prodMutationAck` justification is present (this is how a single-environment app — e.g. a local-only game whose only "env" is production and whose mutations are the user's own local save — deliberately opts in). A bare `production: { "mutation": "full" }` with **no** `prodMutationAck` is downgraded to `forbidden`, and you warn.
+- **Never sign in as a real user or an admin** — only the `identity` test account.
+- If evaluating something *requires* a mutation the policy forbids, stop at that boundary and report it — never escalate your own permissions.
+
+## 3. Discover personas & subagents — soft-detect
+
+Look for the project's personas: `wiki/personas/**` (target-player archetypes, stakeholders) and persona subagents (e.g. the `lisa-phaser` `target-player` / `player-advocate` agents).
+
+- **Present** → drive the product **through each relevant persona**: adopt the archetype's constraints (device, session length, goals, patience, genre-literacy) and evaluate as them; run each archetype for breadth.
+- **Absent** → drive as a single **generic representative end user** of the app's stated audience, and say so.
+
+## 4. Drive the product — per type
+
+Apply the interface's *read-only* actions always; the *mutate* actions only when the policy is `full`.
+
+- **DOM web app** — a real browser (Playwright MCP). Land cold on the entry page, then click / type / select / submit visible controls and attempt real tasks; sweep viewport widths. *(The caller's lens supplies the specific things to look for.)*
+- **HTTP / API backend** — the consumer is a client, not a browser. Read-only: read the OpenAPI/routes and call safe `GET`s (`curl`/`httpie`). Mutate: exercise representative `POST`/`PUT`/`DELETE` flows with test data as the `identity`; check status codes, payload shapes, and error responses.
+- **Canvas game** — a real browser, but the UI is **drawn to a canvas, not the DOM**. Boot it (e.g. `bun run dev` + Playwright), drive via **keyboard/pointer into the canvas**, and read state **visually via screenshots** (not the accessibility tree). Mutation is usually local save state. Judge readability, game-feel, and input responsiveness — not DOM breakpoints.
+- **CLI / library** — the interface is the command / public API. Read-only: `--help`, read-only commands, dry-runs. Mutate: run state-changing commands with disposable inputs.
+- **IaC / CDK** — the "user" is whoever **consumes the resources the stack provisions** (plus the operator). **Read-only (default):** `cdk synth` → read the generated template; `cdk diff` vs. the deployed env; verify the resources, IAM, and outputs express what a consumer would expect. Flag over-broad IAM, missing/opaque outputs, resources that don't serve their stated purpose, and drift. **Mutate (only when `mutation: "full"` *and* `provision: true` on an ephemeral/sandbox env):** `cdk deploy` to the sandbox → recurse into the API/web playbook against the provisioned resources → `cdk destroy`. Never deploy to a real account without explicit sandbox-provisioning config.
+
+## 5. Mutation Discipline — only when the policy is `full`
+
+A real user creates, edits, and deletes things — exercise those flows when, and only when, the policy allows and always as the `identity` account.
+
+- Use unique names with a clear prefix such as `qa-` or `codex-`.
+- Before mutating, identify the cleanup path. After mutating, make a best effort to clean up, then verify it. If cleanup is unavailable, that itself is a finding.
+- Avoid destructive bulk actions unless the account/data is clearly disposable.
+- Record every mutation performed, cleanup attempts, and any residue left behind.
+
+## What you return
+
+Structured, raw observations for the caller — **what** you did, **as whom** (which persona / generic user), **where** (env + mutation level), **what you saw**, and **what you could not reach and why** (especially policy boundaries you stopped at). You do **not** file tickets or write plans; the caller does.

package/plugins/lisa/skills/lisa-use-the-product/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Use The Product"
+short_description: "Shared methodology for actually USING a project's product the way its real end user would — across product types (DOM web app, HTTP/API…"
+default_prompt:
+  - "Use $lisa-use-the-product: Shared methodology for actually USING a project's product the way its real end user would — across product types (DOM web app, HTTP/API…."