@codyswann/lisa 2.189.7 → 2.189.9

package/plugins/src/base/rules/reference/observability-audit.md

@@ -1,6 +1,6 @@
 # Observability Audit (load-bearing)
 
-This rule is the single source of truth for the **audit + file** arm of the `lisa:monitor` skill. The `monitor` skill collects live signals (errors, logs, performance, health) via the stack `ops-specialist` exactly as before; this rule adds two things on top, both **repo-scoped**:
+This rule is the single source of truth for the **audit + file** arm of the `lisa-monitor` skill. The `monitor` skill collects live signals (errors, logs, performance, health) via the stack `ops-specialist` exactly as before; this rule adds two things on top, both **repo-scoped**:
 
 1. **Audit** — score the repo against an observability-completeness rubric for its detected type, so a frontend repo is never dinged for missing backend tracing.
 2. **File** — turn both *anomalies* (a real bad live signal) and *gaps* (an in-scope observability dimension that isn't wired) into **build-ready leaf tickets** so the existing `intake` / `tracker-build-intake` cron picks them up and fixes them. `monitor` files only; it never fixes.
@@ -66,7 +66,7 @@ Everything below the bar is reported (so the human sees it) but **not** ticketed
 
 ## Two finding types → build-ready leaf tickets
 
-Both finding types are filed through the vendor-neutral `lisa:tracker-write` shim with `build_ready: true` (never a vendor write skill directly — that is what keeps the destination switchable). Both are **leaf** work units (`Bug` for anomalies, `Task`/`Improvement` for gaps) — never an Epic or container (gate S15). Each must pass the `tracker-validate` gates S1–S15, so each ticket is a real authored artifact, not a template dump.
+Both finding types are filed through the vendor-neutral `lisa-tracker-write` shim with `build_ready: true` (never a vendor write skill directly — that is what keeps the destination switchable). Both are **leaf** work units (`Bug` for anomalies, `Task`/`Improvement` for gaps) — never an Epic or container (gate S15). Each must pass the `tracker-validate` gates S1–S15, so each ticket is a real authored artifact, not a template dump.
 
 ### Required fields (so the gates pass)
 
@@ -93,7 +93,7 @@ A manual re-run next week must not duplicate last week's tickets. Mirror the `re
 1. **Stable fingerprint per finding.**
    - Anomaly: `sha1("<source>:<stable-signature>:<CURRENT_REPO>")` (12 hex chars). `stable-signature` is the Sentry issue short-id (or culprit), the CloudWatch alarm name, or `errorType@location` — something that survives between runs, **never** the human title or occurrence count.
    - Gap: the literal `gap:<dimension>:<CURRENT_REPO>` (a dimension is missing-or-not; no hash needed).
-2. **Sentinel in the body.** Embed `<!-- lisa-monitor-finding: <fingerprint> -->` in every filed ticket.
+2. **Sentinel in the body.** Embed `<!-- lisa:monitor-finding: <fingerprint> -->` in every filed ticket.
 3. **Search before create** (this IS gate S13). Before filing, search the tracker for the fingerprint string. The search **MUST include closed/resolved tickets** (`gh issue list --search <fp> --state all` for GitHub; JQL with no status filter for JIRA; all states for Linear) — otherwise a just-closed match is invisible and the backoff below can't fire. If an **open** ticket carries the fingerprint → skip (optionally link). If a ticket carrying it was closed **within the recently-resolved backoff window** (`monitor.backoffHours`, default **24h** — matching the 24h Sentry event window; this is **not** the 2h `intake.repair.staleAfterHours`) → skip, to avoid re-filing a just-fixed regression before its signal has drained. Only file when no live or recently-resolved match exists.
 
 ## The cap
@@ -105,7 +105,7 @@ File **at most `max_candidates` tickets per run** (default **20**; config `monit
 - **Default (standalone `monitor <env>`): files.** A plain manual run audits, reports, dedupes, and files up to the cap.
 - **`--dry-run`:** does everything except call `tracker-write` — prints exactly which tickets *would* be filed (title, type, fingerprint, dedup verdict) so the human can preview.
 - **`--report-only`:** produces the health/audit summary only — no filing and no would-file analysis. This is the mode Verify uses (below).
-- **Invoked as `lisa:verify`'s post-deploy step: never files — enforced mechanically, not inferred.** `lisa:verify` step 6 invokes monitor as `lisa:monitor <env> --report-only`; monitor must never file when `--report-only` (or `--dry-run`) is set. This is load-bearing **today** — Verify already routes its remote verification through the `monitor` skill, so without the passed flag the new file-by-default behavior would create tickets during every verify run. As a belt-and-suspenders default, if monitor is invoked via the Skill tool from within a Verify flow and no filing flag was passed, treat it as `--report-only` rather than filing.
+- **Invoked as `lisa-verify`'s post-deploy step: never files — enforced mechanically, not inferred.** `lisa-verify` step 6 invokes monitor as `lisa-monitor <env> --report-only`; monitor must never file when `--report-only` (or `--dry-run`) is set. This is load-bearing **today** — Verify already routes its remote verification through the `monitor` skill, so without the passed flag the new file-by-default behavior would create tickets during every verify run. As a belt-and-suspenders default, if monitor is invoked via the Skill tool from within a Verify flow and no filing flag was passed, treat it as `--report-only` rather than filing.
 
 ## Output
 

package/plugins/src/base/rules/reference/prd-lifecycle-rollup.md

@@ -143,11 +143,11 @@ Apply it as follows:
 
 Skills that link generated work to a PRD or roll a PRD up cite this rule by slug (the `prd-lifecycle-rollup` rule) instead of restating it:
 
-- **PRD backlink / native linking** (`prd-backlink`) — record generated top-level work as native PRD children where supported; always write the documented generated-work fallback; dedupe by child-ref. *(LPC-1.1 #580, LPC-1.2 #582)*
-- **PRD coverage** (`prd-ticket-coverage`) — read the generated top-level child set deterministically from the recorded relationship, not from free-form comments.
-- **GitHub PRD shipped rollup** (`github-prd-intake`) — detect terminal/incomplete/blocked child sets, transition to `prd-shipped`, and leave the PRD open for `/lisa:verify-prd`. *(LPC-1.3 #583)*
-- **Linear / Confluence / Notion PRD shipped rollup** (`linear-prd-intake`, `confluence-prd-intake`, `notion-prd-intake`) — mirror the GitHub shipped rollup with each vendor's terminal predicate and keep the PRD active for verification. *(LPC-1.3 #584)*
-- **Repair close-out** (`repair-intake`) — re-run the same generated-top-level-work terminal
+- **PRD backlink / native linking** (`lisa-prd-backlink`) — record generated top-level work as native PRD children where supported; always write the documented generated-work fallback; dedupe by child-ref. *(LPC-1.1 #580, LPC-1.2 #582)*
+- **PRD coverage** (`lisa-prd-ticket-coverage`) — read the generated top-level child set deterministically from the recorded relationship, not from free-form comments.
+- **GitHub PRD shipped rollup** (`lisa-github-prd-intake`) — detect terminal/incomplete/blocked child sets, transition to `prd-shipped`, and leave the PRD open for `/lisa:verify-prd`. *(LPC-1.3 #583)*
+- **Linear / Confluence / Notion PRD shipped rollup** (`lisa-linear-prd-intake`, `lisa-confluence-prd-intake`, `lisa-notion-prd-intake`) — mirror the GitHub shipped rollup with each vendor's terminal predicate and keep the PRD active for verification. *(LPC-1.3 #584)*
+- **Repair close-out** (`lisa-repair-intake`) — re-run the same generated-top-level-work terminal
   predicate to close out PRDs that were left open after all associated child work became terminal,
   without setting the product-owned `verified` role.
 - **Idempotency** (all of the above) — dedupe-by-ref linking and no-op already-shipped rollup. *(LPC-1.4 #585)*

package/plugins/src/base/rules/reference/repo-scope-split.md

@@ -55,9 +55,9 @@ This pre-applies **only** the unambiguous *"labeled for another repo → skip"*
 
 Apply it **only where the query layer can express `OR labels IS EMPTY` without dropping unlabeled candidates** — otherwise the pre-filter would hide the very tickets the determine + stamp arm exists to handle:
 
-- **JIRA (multi-repo project):** JQL expresses it directly — `lisa:jira-build-intake` applies it in Phase 1. This is the case the optimization is for.
+- **JIRA (multi-repo project):** JQL expresses it directly — `lisa-jira-build-intake` applies it in Phase 1. This is the case the optimization is for.
 - **GitHub:** issues are inherently single-repo, so the scanner is already repo-scoped — no pre-filter needed.
-- **Linear (multi-repo team):** the `list_issues` label filter is an AND-of-labels and cannot express "current-repo **or** unlabeled" in one query, so `lisa:linear-build-intake` keeps the broad `$READY` query and relies on the per-candidate 3a.0 gate — a narrowing label filter there would strand unlabeled Issues.
+- **Linear (multi-repo team):** the `list_issues` label filter is an AND-of-labels and cannot express "current-repo **or** unlabeled" in one query, so `lisa-linear-build-intake` keeps the broad `$READY` query and relies on the per-candidate 3a.0 gate — a narrowing label filter there would strand unlabeled Issues.
 
 **Cost.** Only **unlabeled** candidates need content determination; once stamped, wrong-repo candidates are skipped by label alone — and with the query-time pre-filter, sibling-repo tickets are not even fetched. Prefer candidates already labeled `repo:<current>` first (cheap claim), falling through to unlabeled candidates (determine + stamp) only when no pre-labeled current-repo leaf is ready.
 
@@ -69,4 +69,4 @@ The procedure is vendor-neutral; the create + link + edit mechanics differ:
 
 - **JIRA** — create via `mcp__atlassian__createJiraIssue` (clone fields, set the same epic parent); link via `mcp__atlassian__createIssueLink` with `Blocks` / `is blocked by` (resolve names via `mcp__atlassian__getIssueLinkTypes`); narrow the original via `mcp__atlassian__editJiraIssue`; comment via `mcp__atlassian__addCommentToJiraIssue`. See `jira-write-ticket` Phase 6.
 - **GitHub** — create the sibling issue with the same labels and parent sub-issue; encode the dependency in the body (`Blocked by #<n>` / `Blocks #<n>`) and via the sub-issue/parent graph where used; edit the original's body to narrow scope. See `github-write-issue` Phase 6.
-- **Linear** — create via `lisa:linear-access operation: save-issue` (clone fields, set the same `projectId`); add a blocking relation via the `relations` field or a paired relation call; edit the original to narrow scope. See `linear-write-issue` Phase 6.
+- **Linear** — create via `lisa-linear-access operation: save-issue` (clone fields, set the same `projectId`); add a blocking relation via the `relations` field or a paired relation call; edit the original to narrow scope. See `linear-write-issue` Phase 6.

package/plugins/src/base/rules/reference/upstream-to-lisa.md

@@ -20,7 +20,7 @@ Apply the stopgap in this project so you can keep working. Do **not** stall wait
 
 ### 2. File an upstream issue in the Lisa repository
 
-Use the `github-write-issue` skill (`lisa:github-write-issue`) to create a GitHub Issue **in Lisa's source repository `CodySwannGT/lisa`** — not in this project's own repo. The skill uses the `gh` CLI; the target repo must be `CodySwannGT/lisa` (e.g. `gh issue create --repo CodySwannGT/lisa ...`), because the agent's default repo is this host project.
+Use the `github-write-issue` skill (`lisa-github-write-issue`) to create a GitHub Issue **in Lisa's source repository `CodySwannGT/lisa`** — not in this project's own repo. The skill uses the `gh` CLI; the target repo must be `CodySwannGT/lisa` (e.g. `gh issue create --repo CodySwannGT/lisa ...`), because the agent's default repo is this host project.
 
 The issue should capture, following the skill's three-audience / acceptance-criteria conventions:
 

package/plugins/src/base/rules/reference/usage-accounting.md

@@ -101,7 +101,7 @@ _Managed by Lisa. Regenerated on each usage update; do not edit by hand._
 
 | Flow | Model | Source | Tokens | Cost |
 |---|---|---|---:|---:|
-| ...human-readable rows ending with `lisa:usage-entry` tokens... |
+| ...human-readable rows ending with `lisa-usage-entry` tokens... |
 
 ### Rollup
 

package/plugins/src/base/skills/lisa-acceptance-criteria/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: lisa-acceptance-criteria
+description: "Acceptance criteria definition. Gherkin user flows (Given/When/Then), error states, UX concerns, and empirical verification from the user perspective."
+---
+
+# Acceptance Criteria
+
+Evaluate changes from a non-technical user's perspective. Define acceptance criteria and verify behavior matches requirements.
+
+## Analysis Process
+
+1. **Understand the user goal** -- what problem does this solve for the end user?
+2. **Define user flows** -- step-by-step paths through the feature, including happy path and error paths
+3. **Write acceptance criteria** -- testable conditions from the user's perspective
+4. **Identify UX concerns** -- confusing interactions, missing feedback, accessibility issues
+5. **Map error states** -- what happens when things go wrong, and what the user sees
+6. **Run the feature** -- execute scripts, call APIs, or trigger the described behavior to verify empirically
+7. **Compare output to requirements** -- does actual behavior match expectations?
+
+## Output Format
+
+Structure findings as:
+
+```
+## Product Analysis
+
+### User Goal
+[1-2 sentence summary of what the user wants to accomplish]
+
+### User Flows (Gherkin)
+
+#### Happy Path
+Given [precondition]
+When [action]
+Then [expected outcome]
+
+#### Error Path: [description]
+Given [precondition]
+When [action that fails]
+Then [error handling behavior]
+
+### Acceptance Criteria
+- [ ] [criterion from user perspective]
+
+### UX Concerns
+- [concern] -- impact on user experience
+
+### Error Handling Requirements
+| Error Condition | User Sees | User Can Do |
+|----------------|-----------|-------------|
+
+### Verification Results
+For each acceptance criterion:
+- **Criterion:** [what was expected]
+- **Result:** Pass / Fail / Not Yet Testable
+- **Evidence:** [what was observed]
+
+### Out of Scope
+- [thing that might be expected but is not part of this work]
+```
+
+## Rules
+
+- Write acceptance criteria from the user's perspective, not the developer's
+- Every user flow must include at least one error path
+- Use Gherkin format (Given/When/Then) for user flows to enable direct translation into test cases
+- When verifying, always run the feature -- never review by only reading code
+- If you cannot run the feature (missing dependencies, services unavailable), report as a blocker -- do not guess
+- If the changes are purely internal (refactoring, config, tooling), report "No user-facing impact" and explain why
+- Do not propose UX changes beyond what was described -- flag scope concerns instead
+- Assume the reviewer has no technical background

package/plugins/src/base/skills/lisa-agent-design-best-practices/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: lisa-agent-design-best-practices
+description: Best practices for designing Claude Code agent files (.claude/agents/*.md). This skill should be used when writing or reviewing agent markdown files to ensure proper design with focused domains, correct tool access, reusable definitions, and separation of capabilities from lifecycle. Combines Anthropic's official guidance with battle-tested patterns from agent team usage.
+---
+
+# Agent Design Best Practices
+
+## Overview
+
+This skill defines best practices for designing Claude Code agent files (`.claude/agents/*.md`). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that **agent files define capabilities, not lifecycle** -- the team lead's spawn prompt controls when and how the agent runs.
+
+## Principles
+
+### 1. Define Capabilities, Not Lifecycle
+
+Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*.
+
+```markdown
+<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
+# Security Planner Agent
+
+You are a security specialist in a plan-create Agent Team.
+Given a Research Brief from the team lead, identify security
+considerations for the planned changes.
+
+## Output Format
+
+Send your sub-plan to the team lead via `SendMessage` with this structure:
+...
+```
+
+```markdown
+<!-- Correct: Defines domain expertise, team lead controls usage -->
+# Security Specialist Agent
+
+You are a security specialist who identifies vulnerabilities,
+evaluates threats, and recommends mitigations for code changes.
+
+## Analysis Process
+1. Read affected files
+2. STRIDE analysis
+3. Check input validation
+...
+```
+
+The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.
+
+### 2. One Agent Per Domain, Not Per Phase
+
+Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.
+
+| Wrong | Right |
+|-------|-------|
+| `security-planner` + `security-reviewer` | `security-specialist` |
+| `test-strategist` + `test-coverage-agent` | `test-specialist` |
+| `architecture-planner` + `architecture-reviewer` | `architecture-specialist` |
+
+The same agent type can be spawned multiple times with different prompts for different phases. A `security-specialist` spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."
+
+### 3. Design Focused Domains
+
+Each agent should excel at one specific domain. The domain should be broad enough to avoid workflow coupling but narrow enough to provide real expertise.
+
+```yaml
+# Too narrow (coupled to one workflow step)
+description: Performs STRIDE analysis on Research Briefs during plan-create Phase 2
+
+# Too broad (no clear expertise)
+description: General-purpose agent that can do anything
+
+# Just right (focused domain, reusable across workflows)
+description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling.
+```
+
+### 4. Write Detailed Descriptions
+
+Claude uses the `description` field in YAML frontmatter to decide when to delegate tasks. Be specific about what the agent does and when it adds value.
+
+```yaml
+# Bad: Vague, Claude can't decide when to use it
+description: Reviews code
+
+# Good: Specific domain, clear trigger conditions
+description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
+```
+
+### 5. Limit Tool Access
+
+Grant only the tools necessary for the agent's domain. This enforces focus and prevents agents from exceeding their intended scope.
+
+| Agent Type | Appropriate Tools | Rationale |
+|-----------|-------------------|-----------|
+| Researcher / Reviewer | `Read, Grep, Glob, Bash` | Read-only analysis, no file modifications |
+| Implementer | `Read, Write, Edit, Bash, Grep, Glob` | Needs to modify code |
+| Planner | `Read, Grep, Glob` | Research only, no execution |
+
+Read-only agents cannot implement code. Do not assign implementation tasks to agents without `Write` and `Edit` tools.
+
+### 6. No Hardcoded Interaction Patterns
+
+Do not prescribe how the agent communicates or what input format it expects. The team lead's spawn prompt handles interaction patterns.
+
+```markdown
+<!-- Wrong: Hardcodes communication protocol -->
+## Input
+You receive a **Research Brief** from the team lead containing...
+
+## Output Format
+Send your sub-plan to the team lead via `SendMessage` with this structure:
+```
+
+```markdown
+<!-- Correct: Defines output structure without prescribing delivery mechanism -->
+## Output Format
+Structure your findings as:
+
+### Threat Model (STRIDE)
+| Threat | Applies? | Description | Mitigation |
+...
+```
+
+The output format itself is fine to define -- it provides structure. But how the agent receives input and delivers output should be left to the team lead.
+
+### 7. Context Window Isolation
+
+Each teammate has its own context window. Teammates do not share context and cannot see what other teammates have done. Account for this in agent design:
+
+- Do not assume the agent has seen previous analysis from other agents
+- Include enough domain knowledge in the agent file for independent operation
+- The team lead bridges context between agents via spawn prompts and messages
+
+### 8. File Ownership in Teams
+
+When agents work in teams, each teammate should own distinct files or directories. Two teammates editing the same file leads to conflicts and lost work.
+
+Design agent domains so their file ownership naturally separates:
+
+| Agent | Owns |
+|-------|------|
+| `implementer` | Source files (`src/`) |
+| `test-specialist` | Test files (`tests/`) |
+| `quality-specialist` | No files (read-only) |
+
+## Agent File Structure
+
+### Required Frontmatter
+
+```yaml
+---
+name: agent-name           # lowercase with hyphens
+description: When and why to use this agent. Be specific.
+tools: Read, Grep, Glob     # comma-separated, minimal set
+---
+```
+
+### Optional Frontmatter
+
+```yaml
+model: sonnet              # sonnet, opus, haiku, or inherit (default)
+permissionMode: default     # default, acceptEdits, plan, bypassPermissions, etc.
+maxTurns: 50               # limit agentic turns
+skills:                     # skills to preload
+  - skill-name
+memory: user                # persistent memory: user, project, or local
+```
+
+### Body Structure
+
+The markdown body becomes the agent's system prompt. Structure it as:
+
+1. **Role statement** -- one sentence describing what the agent is
+2. **Analysis/workflow process** -- numbered steps for the agent's approach
+3. **Output format** -- structure for findings (without prescribing delivery mechanism)
+4. **Rules/constraints** -- guardrails for the agent's behavior
+
+## Anti-Patterns
+
+### Don't Create Phase-Specific Agents
+
+```markdown
+<!-- Wrong: Two agents for the same domain, split by phase -->
+# Pre-Implementation Security Planner
+...
+# Post-Implementation Security Reviewer
+...
+
+<!-- Correct: One agent, team lead controls timing -->
+# Security Specialist
+...
+```
+
+### Don't Hardcode Workflow Dependencies
+
+```markdown
+<!-- Wrong: Agent assumes specific workflow context -->
+You are part of the plan-create Phase 2 team.
+Wait for the Research Brief from Phase 1.
+After your analysis, the Consistency Checker will validate your output.
+
+<!-- Correct: Agent is self-contained -->
+You are a security specialist who identifies vulnerabilities
+and recommends mitigations for code changes.
+```
+
+### Don't Over-Specify the Model
+
+Only set `model` when there's a clear reason. Most agents work well with `inherit` (the default), which uses the same model as the parent session. Use `haiku` for fast, simple tasks (exploration, search). Use `sonnet` or `opus` only when the domain requires stronger reasoning.
+
+## Verification Checklist
+
+Before committing an agent file, verify:
+
+1. **Description is specific** -- Claude can determine when to delegate from the description alone
+2. **Tools are minimal** -- only the tools the agent actually needs
+3. **No workflow coupling** -- no references to specific team structures, phases, or input formats
+4. **No hardcoded communication** -- no "send via SendMessage" or "given a Research Brief"
+5. **Domain is reusable** -- the agent works in planning, review, and ad-hoc contexts
+6. **Role statement is clear** -- first line of body explains what the agent is
+7. **Output format is defined** -- structured output without prescribing delivery