@codyswann/lisa 2.119.1 → 2.121.0

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

@@ -0,0 +1,219 @@
+---
+name: 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

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

@@ -0,0 +1,293 @@
+---
+name: atlassian-access
+description: "Vendor-neutral access layer for Atlassian (JIRA + Confluence). Every jira-* and confluence-* skill MUST delegate through this skill rather than calling Atlassian directly. Resolves a substrate per operation in this order: (1) acli if installed and its active profile matches the configured site, (2) Atlassian MCP if authenticated and the configured cloudId is in its accessible resources, (3) curl + API-token Basic auth. Verifies the active connection matches `.lisa.config.json` before every operation — substrates authenticated as a different Atlassian account are skipped, not used."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Atlassian Access: $ARGUMENTS
+
+Single chokepoint for all Atlassian operations. Routes each op to a substrate, enforces connection match, returns structured result. Caller skills (`jira-*`, `confluence-*`) MUST go through this — they MUST NOT invoke `acli` directly, call Atlassian MCP tools directly, or curl the Atlassian REST API themselves.
+
+## Invocation contract
+
+The caller passes one operation plus its arguments. Operations are listed in the dispatch table below. The skill returns either the structured operation result (JSON when the substrate provides it) or a clear error.
+
+```text
+operation: read-ticket  key: PROJ-123
+operation: write-ticket payload: {...}
+operation: transition   key: PROJ-123  to: "In Review"
+operation: comment      key: PROJ-123  body: "..."
+operation: search-issues jql: "project = SE AND status = Open"
+operation: read-page    id: 12345
+operation: write-page   payload: {...}
+```
+
+## Workflow
+
+### Step 1 — Substrate selection (per operation)
+
+Read config:
+
+```bash
+SITE=$(jq -r '.atlassian.site // empty' .lisa.config.json)
+CLOUDID=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json)
+EMAIL=$(jq -r '.atlassian.email // empty' .lisa.config.local.json 2>/dev/null)
+[ -z "$CLOUDID" ] && { echo "Error: atlassian.cloudId not set. Run /lisa:setup:atlassian." >&2; exit 1; }
+```
+
+Probe each tier in order; the first that's ready AND identity-matches is the substrate for this operation. Identity-match is verified before any operation; substrates authenticated as a different Atlassian account are skipped, not used.
+
+```bash
+substrate=""
+
+# Tier 1: acli
+if command -v acli >/dev/null 2>&1 && acli auth status >/dev/null 2>&1; then
+  current_site=$(acli auth status 2>/dev/null | awk '/^  Site:/{print $2}')
+  if [ "$current_site" = "$SITE" ]; then
+    substrate="acli"
+  else
+    # acli installed but pointing at a different site. Try switching profiles.
+    if acli auth switch --site "$SITE" ${EMAIL:+--email "$EMAIL"} >/dev/null 2>&1; then
+      substrate="acli"
+    fi
+  fi
+fi
+
+# Tier 2: Atlassian MCP (if acli not ready OR the operation isn't acli-covered)
+# $OP_REQUIRES is a conceptual variable set by the dispatch table to "non-acli" for
+# operations that have no acli adapter (e.g. read-page-descendants). It is not a real
+# shell variable initialized here — the condition is illustrative pseudo-code.
+if [ -z "$substrate" ] || [ "$OP_REQUIRES" = "non-acli" ]; then
+  # Probe via mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources.
+  # (Pseudo-code; actual call is the MCP tool invocation, not a bash command.)
+  # If the MCP returns a list and $CLOUDID is in it, MCP is identity-matched.
+  # If the MCP is unauthenticated or $CLOUDID is NOT in the list, MCP is skipped.
+  if mcp_atlassian_authenticated_and_matches_cloudid "$CLOUDID"; then
+    : ${substrate:=mcp}
+    # Mark MCP as available even if acli already won tier 1 — used for ops acli can't do.
+    mcp_available=true
+  fi
+fi
+
+# Tier 3: curl + API token (headless / multi-account / scoped-token path)
+read_atlassian_token() {
+  local email="$1"
+  [ -n "$ATLASSIAN_API_TOKEN" ] && { echo "$ATLASSIAN_API_TOKEN"; return; }
+  local slug=$(echo "$email" | tr '[:upper:]@.' '[:lower:]__')
+  local varname="ATLASSIAN_API_TOKEN_${slug}"
+  [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  case "$(uname -s)" in
+    Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
+    Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;
+    MINGW*|MSYS*|CYGWIN*)
+      # `cmdkey /generic ... /pass:` stores the secret in Windows Credential Manager, but
+      # `cmdkey /list` never prints stored passwords (by design). Read the CredentialBlob
+      # back via the Win32 CredRead API through PowerShell; pass the target name via an env
+      # var to dodge nested quoting, and strip the CRLF powershell.exe appends.
+      LISA_CRED_TARGET="lisa-atlassian-${email}" powershell.exe -NoProfile -NonInteractive -Command '
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public static class LisaCred {
+  [StructLayout(LayoutKind.Sequential)]
+  private struct CREDENTIAL {
+    public int Flags; public int Type; public IntPtr TargetName; public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize; public IntPtr CredentialBlob; public int Persist;
+    public int AttributeCount; public IntPtr Attributes; public IntPtr TargetAlias; public IntPtr UserName;
+  }
+  [DllImport("advapi32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  private static extern bool CredRead(string target, int type, int flags, out IntPtr credential);
+  [DllImport("advapi32.dll")] private static extern void CredFree(IntPtr cred);
+  public static string Read(string target) {
+    IntPtr p;
+    if (!CredRead(target, 1, 0, out p)) { return null; }
+    try {
+      CREDENTIAL c = (CREDENTIAL)Marshal.PtrToStructure(p, typeof(CREDENTIAL));
+      if (c.CredentialBlobSize == 0) { return String.Empty; }
+      return Marshal.PtrToStringUni(c.CredentialBlob, c.CredentialBlobSize / 2);
+    } finally { CredFree(p); }
+  }
+}
+"@
+[LisaCred]::Read($env:LISA_CRED_TARGET)' 2>/dev/null | tr -d '\r' ;;
+  esac
+}
+TOKEN=$(read_atlassian_token "$EMAIL")
+[ -n "$TOKEN" ] && curl_available=true && : ${substrate:=curl}
+
+# Fail loudly with actionable remediation if nothing works.
+if [ -z "$substrate" ]; then
+  # Detect plugin enablement state for the suggestion.
+  plugin_enabled_global=$(jq -r '.enabledPlugins["atlassian@claude-plugins-official"] // false' ~/.claude/settings.json 2>/dev/null || echo "false")
+  plugin_enabled_project=$(jq -r '.enabledPlugins["atlassian@claude-plugins-official"] // false' .claude/settings.json 2>/dev/null || echo "false")
+  plugin_enabled_local=$(jq -r '.enabledPlugins["atlassian@claude-plugins-official"] // false' .claude/settings.local.json 2>/dev/null || echo "false")
+
+  cat >&2 <<EOF
+Error: no Atlassian access substrate available for site $SITE.
+
+Attempted:
+  acli   — $(command -v acli >/dev/null && echo "installed but identity mismatch or unauthenticated" || echo "not installed")
+  MCP    — $([ "$plugin_enabled_global" = "true" ] || [ "$plugin_enabled_project" = "true" ] || [ "$plugin_enabled_local" = "true" ] && echo "plugin enabled but not authenticated or cloudId $CLOUDID not in accessible resources" || echo "plugin not enabled in any settings.json scope")
+  curl   — no ATLASSIAN_API_TOKEN found for $EMAIL (env, slug-suffixed env, or keychain)
+
+Remediation paths (pick one):
+
+1. Install the Atlassian MCP plugin (local scope — per-developer, gitignored).
+   This is the simplest path for single-account developers.
+
+   Run in your terminal:
+
+     jq '.enabledPlugins["atlassian@claude-plugins-official"] = true' \\
+       .claude/settings.local.json 2>/dev/null > /tmp/s && \\
+       mv /tmp/s .claude/settings.local.json || \\
+       echo '{"enabledPlugins":{"atlassian@claude-plugins-official":true}}' > .claude/settings.local.json
+
+   Then restart Claude Code (or run /restart-mcp) to load the plugin, and
+   invoke 'mcp__plugin_atlassian_atlassian__authenticate' to complete OAuth.
+
+2. Install acli and authenticate (best for multi-account developers).
+
+     brew tap atlassian/homebrew-acli && brew install acli
+     acli auth login   # OAuth as the account matching $EMAIL
+
+3. Provision an API token (headless / CI / scoped-token environments).
+
+     Run /lisa:setup:atlassian — guided flow with clipboard-piped keychain store.
+
+EOF
+  exit 1
+fi
+```
+
+Operation dispatch then uses `$substrate` for the primary route. If the operation has no `acli` adapter and `$substrate=acli`, fall through to `$mcp_available` then `$curl_available` for the actual call. The fall-through stops at the first available tier that can perform the operation.
+
+### Step 2 — Connection-match check
+
+The active connection MUST point at the cloudId/site declared in `.lisa.config.json`. Step 1's substrate selection already verifies this implicitly (substrates that don't match are skipped). This step is the explicit assertion before any operation runs — defensive in case the substrate state changed since selection.
+
+Read configured site:
+
+```bash
+cloudid=$(jq -r '.atlassian.cloudId // empty' .lisa.config.json)
+site=$(jq -r '.atlassian.site // empty' .lisa.config.json)   # optional human-readable site URL
+email=$(jq -r '.atlassian.email // empty' .lisa.config.json) # optional, for multi-account disambiguation
+
+if [ -z "$cloudid" ]; then
+  echo "Error: atlassian.cloudId not set in .lisa.config.json. Run /lisa:setup:atlassian." >&2
+  exit 1
+fi
+```
+
+**CLI mode check**:
+
+```bash
+# Compare active acli profile against config.
+current=$(acli auth status --json 2>/dev/null)
+current_site=$(echo "$current" | jq -r '.site // empty')
+current_email=$(echo "$current" | jq -r '.email // empty')
+
+if [ -n "$site" ] && [ "$current_site" != "$site" ]; then
+  # Profile mismatch — switch.
+  acli auth switch --site "$site" ${email:+--email "$email"}
+fi
+```
+
+If `acli auth switch` fails because no matching profile exists, surface the error verbatim and instruct the caller to run `/lisa:setup:atlassian` to add the profile.
+
+**curl mode check** (when the chosen op routes to curl):
+
+```bash
+# Validate the active ATLASSIAN_API_TOKEN points at the configured account by
+# hitting /rest/api/3/myself and comparing emailAddress.
+AUTH=$(printf '%s:%s' "$email" "$ATLASSIAN_API_TOKEN" | base64)
+myself=$(curl -s -H "Authorization: Basic $AUTH" \
+  "https://${site}/rest/api/3/myself")
+me_email=$(echo "$myself" | jq -r '.emailAddress // empty')
+
+if [ -z "$me_email" ]; then
+  echo "Error: ATLASSIAN_API_TOKEN failed authentication against $site. Run /lisa:setup:atlassian to re-issue." >&2
+  exit 1
+fi
+if [ "$me_email" != "$email" ]; then
+  echo "Error: ATLASSIAN_API_TOKEN belongs to '$me_email', but .lisa.config.local.json declares '$email'. Multi-account misconfiguration." >&2
+  exit 1
+fi
+```
+
+If validation fails, never silently proceed — abort and instruct the user to fix env.
+
+### Step 3 — Operation dispatch
+
+Substrate column meanings:
+
+- **`acli`**: routes through `acli`. Preferred when available and identity-matched.
+- **`MCP`**: routes through the Atlassian MCP. Preferred when acli can't do the op and the MCP is identity-matched (cloudId in `getAccessibleAtlassianResources`).
+- **`curl`**: routes through curl + Basic auth + `ATLASSIAN_API_TOKEN`. Used when neither acli nor MCP is available.
+- Multiple cells filled means tier ordering applies — try acli, then MCP, then curl, taking the first that has an adapter for the op AND is identity-matched.
+- One cell means only that substrate can perform the op.
+
+`<SITE>` = `.atlassian.site` (e.g. `propswap.atlassian.net`). `<CLOUDID>` = `.atlassian.cloudId`. `<AUTH>` = `Basic $(printf '%s:%s' "$email" "$ATLASSIAN_API_TOKEN" | base64)`. JIRA paths use `/rest/api/3/...`; Confluence uses `/wiki/rest/api/...` (v1) or `/api/v2/...` (v2).
+
+| Operation | acli adapter | MCP adapter | curl adapter |
+|---|---|---|---|
+| **JIRA ops** | | | |
+| `read-ticket key:<K>` | `acli jira workitem view <K> --json` | `mcp__plugin_atlassian_atlassian__getJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>` |
+| `write-ticket payload:<P>` (create) | `acli jira workitem create --from-json <P>` | `mcp__plugin_atlassian_atlassian__createJiraIssue` | `POST https://<SITE>/rest/api/3/issue` body=`<P>` |
+| `write-ticket payload:<P>` (edit) | `acli jira workitem edit <K> --from-json <P>` | `mcp__plugin_atlassian_atlassian__editJiraIssue` | `PUT https://<SITE>/rest/api/3/issue/<K>` body=`<P>` |
+| `transition key:<K> to:<S>` | `acli jira workitem transition --key <K> --status "<S>" --yes` | `mcp__plugin_atlassian_atlassian__transitionJiraIssue` | resolve transition id then `POST .../issue/<K>/transitions` |
+| `transitions key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getTransitionsForJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>/transitions` |
+| `comment key:<K> body:<B>` | `acli jira workitem comment add --key <K> --body "<B>"` | `mcp__plugin_atlassian_atlassian__addCommentToJiraIssue` | `POST https://<SITE>/rest/api/3/issue/<K>/comment` |
+| `link from:<K> to:<K2> type:<T>` | `acli jira workitem link create --inward <K> --outward <K2> --type "<T>"` | `mcp__plugin_atlassian_atlassian__createJiraIssueLink` | `POST https://<SITE>/rest/api/3/issueLink` |
+| `remote-links key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getJiraIssueRemoteIssueLinks` | `GET https://<SITE>/rest/api/3/issue/<K>/remotelink` |
+| `search-issues jql:<J>` | `acli jira workitem search --jql "<J>" --json` | `mcp__plugin_atlassian_atlassian__searchJiraIssuesUsingJql` | `POST https://<SITE>/rest/api/3/search/jql` |
+| `list-projects` | `acli jira project list --paginate --json` | `mcp__plugin_atlassian_atlassian__getVisibleJiraProjects` | `GET https://<SITE>/rest/api/3/project/search` |
+| `issue-type-metadata project:<K>` | `acli jira project view --key <K> --include-all --json` | `mcp__plugin_atlassian_atlassian__getJiraProjectIssueTypesMetadata` | `GET https://<SITE>/rest/api/3/issuetype/project?projectId=<id>` |
+| **Confluence ops** | | | |
+| `read-page id:<I>` | `acli confluence page view --id <I> --json` | `mcp__plugin_atlassian_atlassian__getConfluencePage` | `GET https://api.atlassian.com/ex/confluence/<CLOUDID>/wiki/rest/api/content/<I>` |
+| `read-page-descendants id:<I>` | — | `mcp__plugin_atlassian_atlassian__getConfluencePageDescendants` | `GET .../content/<I>/descendant/page` |
+| `read-page-comments id:<I> kind:<footer\|inline>` | — | `mcp__plugin_atlassian_atlassian__getConfluencePageFooterComments` / `getConfluencePageInlineComments` | `GET .../content/<I>/child/comment?location=<kind>` |
+| `read-comment-children id:<C>` | — | `mcp__plugin_atlassian_atlassian__getConfluenceCommentChildren` | `GET .../content/<C>/child/comment` |
+| `write-page payload:<P>` (create) | — | `mcp__plugin_atlassian_atlassian__createConfluencePage` | `POST .../wiki/rest/api/content` body=`<P>` |
+| `write-page payload:<P>` (edit) | — | `mcp__plugin_atlassian_atlassian__updateConfluencePage` | `PUT .../content/<I>` body must include `version.number` bumped |
+| `label-page id:<I> add:<L1,L2> remove:<L3,L4>` | — | (no v2 label-write endpoint on MCP) | (Atlassian gap; not used by lisa — see "Confluence PRD lifecycle" rule) |
+| `comment-page id:<I> kind:<footer\|inline> body:<B>` | — | `mcp__plugin_atlassian_atlassian__createConfluenceFooterComment` / `createConfluenceInlineComment` | `POST .../content` body has `type=comment` |
+| `search-pages cql:<Q>` | — | `mcp__plugin_atlassian_atlassian__searchConfluenceUsingCql` | `GET .../content/search?cql=<Q>` |
+| `list-spaces` | `acli confluence space list --type global --json` | `mcp__plugin_atlassian_atlassian__getConfluenceSpaces` | `GET .../wiki/rest/api/space` |
+| **Common ops** | | | |
+| `list-sites` | `acli auth status --json` | `mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources` | `GET https://api.atlassian.com/oauth/token/accessible-resources` |
+
+**Confluence v1 vs v2:** every Confluence curl path above uses **v1** (`/wiki/rest/api/...`). v1 is deprecated by Atlassian but as of writing remains functional for API-token Basic auth. The v2 API (`/api/v2/...`) requires *granular* OAuth scopes that aren't issued to Basic-auth API tokens consistently — so v1 is the safer path for now. When Atlassian fully retires v1, this table must move to v2 (the dispatch is the only thing that changes; the substrate-selection logic is unaffected).
+
+**acli flag note:** acli's `--output` flag does not exist; the correct flag is `--json`. List commands require `--paginate` or `--limit` (no implicit fetch-all). Several documented adapters are nominal — verify against `acli <subcmd> --help` before relying on them. When acli's adapter is broken or missing for a specific op, fall through to MCP (if identity-matched) then curl per the tier ordering.
+
+**JIRA terminal-resolution note:** when a caller marks a transition as terminal per `leaf-only-lifecycle`, the substrate must not treat a Done-named status as sufficient by name alone. After `transition key:<K> to:<S>`, re-read the issue and verify `statusCategory = Done`; if the workflow requires a resolution, verify `resolution` is set. If the transition screen requires a resolution value, pass the configured default resolution when available; otherwise return a setup error so the build-intake skill can report the workflow gap instead of silently leaving an unresolved ticket in a Done-looking status.
+
+Operations not in this table are unsupported — add an adapter row before using them. Adapters MUST return a structured response (parse `acli`'s `--json`; jq-process curl's raw JSON).
+
+### Payload conventions
+
+- `write-ticket` payload: full JSON spec when creating; partial JSON (only changed fields, with `key` to identify) when editing. Adapters detect create vs edit by presence of `key`.
+- `write-page` payload: supports a label-only mutation form — `{ "id": "<I>", "labels": { "add": [...], "remove": [...] } }` — so callers transitioning PRD lifecycle labels do not need to resend the page body. Full create/update payloads also accepted.
+- `comment-page` `kind: inline` requires `anchor` (the highlighted text the comment attaches to). `kind: footer` ignores `anchor`.
+
+### Step 4 — Return result
+
+Emit either:
+
+- The structured operation result (JSON object), wrapped in a `<result>` block for caller parsing, OR
+- An error message prefixed with `Error:` and a remediation hint. Exit non-zero. Include the HTTP status code (curl) or acli exit code so callers can route on it.
+
+Do not paraphrase substrate output beyond JSON normalization.
+
+## Invariants
+
+- Caller skills never invoke `acli` or `curl` against Atlassian directly. They only invoke this skill.
+- Substrate is decided once per skill invocation and never switches mid-operation.
+- Connection match is mandatory. Operations that bypass it (because "the user obviously meant the configured site") are forbidden.
+- Profile mutations (`acli auth switch`) are allowed when acli is the active substrate. The curl substrate never mutates the token — if `ATLASSIAN_API_TOKEN` doesn't match the configured account, fail loud rather than silently substituting.
+- `.lisa.config.local.json` overrides `.lisa.config.json` per-key — the same precedence rule as every other consumer of project config.
+
+## Headless behavior
+
+In a headless / non-interactive context (no TTY, `CI=true`, or `-p` mode), the MCP tier is unavailable (its OAuth flow needs a browser). The substrate ladder collapses to: acli (if pre-authenticated, e.g., a CI image baked with a service-account token) → curl + `ATLASSIAN_API_TOKEN`. Never block on interactive prompts. If both fail readiness checks, exit non-zero with a deterministic error.

package/plugins/lisa-agy/skills/automation-status/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: automation-status
+description: "Read-only operator surface for the current project's Lisa automation fleet. Resolves the expected recurring jobs from the same setup-automations contract Lisa uses to create them, inspects the active runtime scheduler (Codex automations or Claude /schedule), compares live command/cadence/queue arguments against the expected contract, and reports grouped fleet health such as healthy, missing, unsupported, drifted, stale, or failing with remediation guidance."
+allowed-tools: ["Skill", "Bash", "Read"]
+---
+
+# Automation Status: $ARGUMENTS
+
+`/lisa:automation-status` is the operator-facing inspection surface for Lisa's unattended job fleet. It answers, for the **current repo only**, whether the recurring Lisa automations that should exist actually exist, still match Lisa's setup contract, and appear healthy based on the runtime metadata available.
+
+This command is **read-only** in v1. It does not create, update, resume, rerun, pause, or delete automations. It complements `/lisa:setup-automations`, `/lisa:tear-down-automations`, `/lisa:intake`, `/lisa:repair-intake`, `doctor`, and `monitor`; it does not replace them.
+
+## Confirmation policy
+
+Do **not** ask for confirmation once invoked. This skill inspects scheduler state and reports what it finds. There are no write-side effects in the v1 surface.
+
+## Scope
+
+Inspect only the Lisa automation fleet for the current project:
+
+- `intake-repair`
+- `intake-prd`
+- `intake-tickets`
+- `exploratory-bugs` when the current stack supports `exploratory-qa`
+- `exploratory-prds`
+
+Resolve the expected project identifier, fleet naming prefix, queue arguments, cadence, and stack-support rules from the same contract used by `setup-automations` and `tear-down-automations`. Do **not** invent a second source of truth for fleet naming or queue resolution.
+
+## Runtime inspection
+
+Branch on the active runtime and prefer the runtime's native automation listing surface:
+
+- **Codex**: inspect Codex automations metadata first. Use backing-store files only as a fallback or to enrich timestamps when the runtime surface cannot provide enough status detail directly.
+- **Claude**: inspect the `/schedule` listing surface and any exposed recency or failure metadata available there.
+- **Other runtimes**: if no native recurring-task inspection exists, report that automation-status is unsupported in this runtime rather than guessing.
+
+The report must stay repo-scoped: inspect only automations whose names belong to the current repo's Lisa fleet prefix, and do not absorb unrelated automations into the result.
+
+## What to report
+
+For each expected automation, report:
+
+1. Whether it exists.
+2. Whether it is expected or intentionally unsupported.
+3. The configured command and cadence Lisa expects.
+4. Any detected drift in name, cadence, command shape, or queue arguments.
+5. Any available recent-run health signal such as stale last-run timing or repeated failure status.
+6. A concise remediation hint when attention is needed.
+
+Emit an overall grouped fleet verdict such as `HEALTHY`, `ATTENTION_NEEDED`, or `PARTIAL_SUPPORT`, plus the runtime surface inspected.
+
+## Operator usage
+
+Typical entrypoint:
+
+```text
+/lisa:automation-status
+```
+
+Use this command when an operator needs to answer one of these questions for the current repo:
+
+- "Did Lisa set up every automation this project expects?"
+- "Is the scheduler still pointing at the right cadence and queue arguments?"
+- "Is the queue idle because there is no work, or because the automation is stale or failing?"
+
+The report should be terminal-first and immediately actionable: observable scheduler facts first, then the smallest useful remediation step.
+
+## Runtime differences
+
+- **Codex**: prefer native automation metadata and use backing-store files only to fill gaps such as timestamps or failure recency. When Codex exposes health/memory signals, include them as observed facts rather than assumptions.
+- **Claude**: use the `/schedule` listing as the primary runtime surface. Compare the live schedule name, cadence, and command shape against the Lisa contract, but degrade gracefully when `/schedule` does not expose equivalent recency or failure fields.
+- **Other runtimes**: report automation-status as unsupported for that runtime instead of guessing from unrelated files or naming patterns.
+
+## Verdicts and remediation
+
+- `HEALTHY`: every expected automation exists and the inspected runtime metadata shows no actionable drift, staleness, or failure.
+- `PARTIAL_SUPPORT`: the fleet is otherwise healthy, but at least one exploratory job is intentionally unsupported for this stack or runtime.
+- `ATTENTION_NEEDED`: at least one automation is missing, drifted, stale, or failing.
+
+Status-specific remediation guidance:
+
+- `MISSING`: tell the operator which job is absent and recommend rerunning `/lisa:setup-automations` or recreating the missing job with the expected cadence and command.
+- `DRIFTED`: show the expected versus observed cadence/command mismatch and recommend aligning the scheduler entry with Lisa's current setup contract, usually by rerunning `/lisa:setup-automations`.
+- `STALE`: explain that the job exists but has not run recently enough for its cadence. Recommend inspecting the runtime's recent-run history or failure logs before changing queue state.
+- `FAILING`: surface the failure signal directly and recommend checking the latest runtime error plus the affected queue command (`/lisa:intake`, `/lisa:repair-intake`, or exploratory job) after the scheduler issue is resolved.
+- `UNSUPPORTED`: explain why the job is intentionally absent and say that no remediation is required unless the project stack or runtime support changed.
+
+Render the report in grouped sections using the shared `scripts/automation-status-report.mjs` contract:
+
+```text
+Overall verdict: <VERDICT>
+Counts: <n HEALTHY>, <n MISSING>, <n UNSUPPORTED>, <n DRIFTED>, <n STALE>, <n FAILING>
+Runtime inspected: <runtime surface>
+Generated at: <ISO timestamp>
+
+1. <group title>
+- <STATUS> <automation-id>: <summary>
+  Expected: <cadence> -> <command>
+  Observed: <what the runtime exposed>
+  Remediation: <next step when attention is needed>
+```
+
+Keep observable runtime facts separate from remediation guidance so operators can distinguish drift, unsupported jobs, and actual failures quickly.
+
+## Rules
+
+- Stay **read-only**. Never create, update, delete, enable, disable, or rerun automations from this skill.
+- Reuse `setup-automations` contract logic for expected fleet resolution, cadence, queue arguments, naming, and stack-specific support checks.
+- Distinguish **unsupported** from **missing**. An exploratory job omitted because the current stack lacks `exploratory-qa` is not a failure.
+- If the runtime cannot expose a field such as last-run timestamp or failure state, say that explicitly instead of implying health.
+- Keep the output operational and repo-scoped so operators can tell whether Lisa's unattended surfaces are present, current, and healthy right now.

package/plugins/lisa-agy/skills/bug-triage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: bug-triage
+description: "8-step bug triage and implementation workflow. Ensures bugs are reproducible, root-caused, and fixable before implementation begins."
+---
+
+# Bug Triage
+
+Follow this 8-step triage process before implementing any bug fix. Do not skip triage.
+
+## Triage Steps
+
+1. Verify you have all information needed to reproduce the bug (authentication requirements, environment information, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
+2. Reproduce the bug. If you cannot reproduce it, stop and report what you tried and what you observed.
+3. Once reproduced, verify you are 100% positive on how to fix it. If not, determine what you need to do to be 100% positive (e.g. add logging, trace the code path, inspect state) and do that first.
+4. Verify you have access to the tools, environments, and permissions needed to deploy and verify this fix (e.g. CI/CD pipelines, deployment targets, logging/monitoring systems, API access, database access). If any are missing or inaccessible, stop and raise them before starting implementation.
+5. Define the tests you will write to confirm the fix and prevent a regression.
+6. Define the documentation you will create or update to explain this bug so another developer understands the "how" and "what" behind it.
+7. If you can verify your fix before deploying to the target environment (e.g. start the app, invoke the API, open a browser, run the process, check logs), do so before deploying.
+8. Define how you will verify the fix beyond a shadow of a doubt (e.g. deploy to the target environment, invoke the API, open a browser, run the process, check logs).
+
+## Implementation
+
+Use the output of the triage steps above as your guide. Do not skip triage.