@codyswann/lisa 2.11.0 → 2.12.0

package/README.md

@@ -12,9 +12,9 @@ A request to fix a bug routes to a different flow than a request to build a feat
 
 ### Flows and Agents
 
-A flow is a pipeline. Each step in the pipeline is an **agent** — a scoped AI with specific tools and skills. One agent investigates git history, another reproduces bugs, another writes code, another verifies the result.
+A flow is a pipeline. Each step in the pipeline is an **agent** — a scoped AI with specific tools and instructions. One agent investigates git history, another reproduces bugs, another writes code, another verifies the result.
 
-Agents delegate domain-specific work to **skills** — reusable instruction sets that can be invoked by agents, by slash commands, or by CI workflows. The same skill that triages a JIRA ticket interactively is the same skill invoked by the nightly triage workflow.
+Behind the scenes, agents delegate domain-specific work to reusable instruction sets that are loaded automatically when a command runs. The same logic that triages a JIRA ticket interactively is the same logic invoked by the nightly triage workflow — you don't need to know which one is running.
 
 Flows can nest. A build flow includes a verification sub-flow, which includes a ship sub-flow. This composition keeps each flow focused while enabling complex end-to-end workflows.
 
@@ -28,13 +28,13 @@ Lisa enforces quality through layered gates:
 
 ### Location Agnostic
 
-The same rules, skills, and quality gates apply everywhere:
+The same rules, workflows, and quality gates apply everywhere:
 
 - On a developer's workstation running Claude Code interactively
 - In a GitHub Action running a nightly improvement job
 - In a CI workflow responding to a PR review comment
 
-The analytical logic lives in skills. The enforcement lives in hooks and rules. The orchestration adapts to context — using MCP integrations locally and REST APIs in CI — but the standards don't change.
+The orchestration adapts to context — using MCP integrations locally and REST APIs in CI — but the standards don't change.
 
 ### Template Governance
 
@@ -44,7 +44,7 @@ Lisa distributes its standards to downstream projects as templates. When a proje
 - Test and coverage infrastructure
 - CI/CD workflows
 - Git hooks
-- AI agent definitions, skills, and rules
+- AI agent definitions and project rules
 
 Templates follow governance rules: some files are overwritten on every update (enforced standards), some are created once and left alone (project customization), and some are merged (shared defaults with project additions).
 
@@ -58,15 +58,66 @@ curl -fsSL https://claude.ai/install.sh | bash
 
 ## Working With Lisa
 
-> Ask Claude: "I have JIRA ticket [TICKET-ID]. Research, plan, and implement it."
+Lisa exposes a small set of top-level commands that map to the work lifecycle. Run them in Claude Code; everything underneath — agents, sub-flows, and the supporting libraries that power each step — happens automatically.
 
-Or use slash commands directly:
+### The Lifecycle
 
-- `/fix` — route through the bug fix flow
-- `/build` — route through the feature build flow
-- `/improve` — route through the improvement flow
-- `/investigate` — route through the investigation flow
-- `/jira:triage <TICKET-ID>` — analytical triage gate: detect ambiguities, edge cases, and verification methodology
-- `/plan:improve-tests <target>` — improve test quality by analyzing and strengthening weak or brittle tests
+A piece of work moves through five stages. Each stage has one command.
 
-> Ask Claude: "What commands are available?"
+| Stage | Command | What it does |
+| --- | --- | --- |
+| Research | `/lisa:research <problem>` | Investigates the codebase and problem space, then produces a PRD ready for planning. |
+| Plan | `/lisa:plan <PRD>` | Decomposes a PRD into ordered work items in your tracker (JIRA, GitHub Issues, or Linear). |
+| Implement | `/lisa:implement <ticket>` | Takes one work item from spec to shipped: assembles an agent team, runs the build, opens a PR, handles review, merges. |
+| Verify | `/lisa:verify` | Commits, pushes, opens a PR, monitors deploy, and verifies behavior in the target environment. Folded into `/lisa:implement` but available standalone. |
+| Debrief | `/lisa:debrief <epic>` | After shipping, mines tickets and PRs to surface edge cases, gotchas, and friction. Produces a triage doc; `/lisa:debrief:apply` persists accepted learnings. |
+
+Most users only ever call `/lisa:research`, `/lisa:plan`, and `/lisa:implement`. The rest run automatically as sub-flows.
+
+### Batch and Scheduled Work
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:intake <queue-url>` | Scans a Ready queue (Notion PRD database, JIRA project, GitHub repo, Linear team, Confluence space) and dispatches each item through the right lifecycle command. Designed as the cron target for unattended runs. |
+
+### Maintenance and Operations
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:monitor [environment]` | Checks application health, logs, error rates, and performance for the named environment. |
+| `/lisa:product-walkthrough <route>` | Walks the live product through a real browser to ground PRD or ticket reasoning in current behavior. |
+| `/lisa:codify-verification <type> <what>` | Converts a passing manual verification into a regression test in the appropriate framework (Playwright, integration test, benchmark). Runs automatically after `/lisa:verify`. |
+| `/lisa:review:local` | Reviews local branch changes against `main`. |
+| `/lisa:pull-request:review <pr-url>` | Pulls down review comments on a PR and implements the valid ones. |
+| `/lisa:security:zap-scan` | Runs an OWASP ZAP baseline scan against the local app. |
+
+### Targeted Improvements
+
+These commands tighten a specific quality threshold and fix every violation in one pass — useful for incremental hardening or nightly jobs.
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:improve:test-coverage <pct>` | Raises coverage to the target percentage by adding tests for uncovered code. |
+| `/lisa:improve:tests <target>` | Strengthens weak, brittle, or poorly-written tests. |
+| `/lisa:improve:code-complexity` | Lowers the cognitive-complexity threshold by 2 and fixes resulting violations. |
+| `/lisa:improve:max-lines <n>` | Reduces the max-file-lines threshold and fixes violations. |
+| `/lisa:improve:max-lines-per-function <n>` | Reduces the max-lines-per-function threshold and fixes violations. |
+| `/lisa:fix:linter-error <rule> [...]` | Fixes every violation of one or more ESLint rules across the codebase. |
+
+### Git Helpers
+
+| Command | What it does |
+| --- | --- |
+| `/lisa:git:commit [hint]` | Creates conventional commits from the current changes. |
+| `/lisa:git:submit-pr [hint]` | Pushes and opens or updates a PR. |
+| `/lisa:git:prune` | Prunes local branches whose remotes have been deleted. |
+
+### Talking to Lisa in Plain English
+
+You don't have to remember any of this. Tell Claude what you want and the right command will run:
+
+> "I have JIRA ticket PROJ-1234. Research, plan, and implement it."
+> "Walk through the checkout flow and tell me what's broken."
+> "Get test coverage to 90%."
+
+> Ask Claude: "What commands are available?" for the full list at any time.

package/package.json

@@ -79,7 +79,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

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

package/plugins/lisa/skills/jira-read-ticket/SKILL.md

@@ -34,7 +34,23 @@ Call `mcp__atlassian__getJiraIssue` for the target ticket. Extract and preserve:
 - Full description (preserve formatting)
 - Acceptance criteria section if separately structured
 - **Validation Journey** section if present (pass verbatim to downstream)
-- Attachments list (names + URLs, do not download unless needed)
+- Attachments list — capture `id`, `filename`, `mimeType`, `size`, and `content` URL for each. Do not download unless a downstream task needs the bytes (see "Downloading attachments" below).
+
+#### Downloading attachments (opt-in)
+
+The Atlassian MCP exposes attachment metadata but no binary-fetch tool ([JRACLOUD-97830](https://jira.atlassian.com/browse/JRACLOUD-97830), [ECO-1265](https://jira.atlassian.com/browse/ECO-1265)). Fetch attachment bytes only when a downstream task explicitly needs them — e.g., a design-fidelity check on an image, log-file analysis, PDF text extraction. For everything else, keep the URL reference and move on.
+
+```bash
+bash .claude/skills/jira-read-ticket/scripts/download-attachment.sh <id-or-content-url> <output-path>
+```
+
+Requires `JIRA_SERVER`, `JIRA_LOGIN`, and `JIRA_API_TOKEN` in the environment (same contract as `jira-evidence`). If those are not set the helper exits with code 2 and a clear remediation message — record the URL only and continue.
+
+After download, branch on `mimeType`:
+- `image/*` — pass the local path to image-aware downstream tools
+- `text/*`, `application/json`, `application/xml`, `application/x-yaml` — read inline as text
+- `application/pdf` — extract text via downstream tooling if needed
+- everything else — record path only; do not attempt to inline binary content
 
 ### Comments
 
@@ -121,7 +137,7 @@ Produce a single structured output that the caller can pass verbatim to downstre
 <chronological comments, flagged items called out>
 
 ### Attachments
-<list>
+<list with id, filename, mimeType, size, content URL — note any that were downloaded and their local paths>
 
 ## Remote Links
 ### Pull Requests (<count>)

package/plugins/lisa/skills/jira-read-ticket/scripts/download-attachment.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# download-attachment.sh — Download a JIRA attachment to a local file.
+#
+# Usage:
+#   bash download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>
+#
+# Why this helper exists:
+#   The Atlassian MCP server (mcp__atlassian__*) returns attachment metadata
+#   (id, filename, mimeType, size, content URL) on getJiraIssue but provides
+#   no tool to fetch the binary content. This script closes the gap by
+#   hitting the Jira REST API directly with Basic auth, mirroring the
+#   env-var contract already used by jira-evidence/scripts/post-evidence.sh.
+#
+#   See https://jira.atlassian.com/browse/JRACLOUD-97830 for the upstream
+#   gap; remove this helper once Atlassian ships a download tool in the MCP.
+#
+# Required env vars:
+#   JIRA_SERVER     - https://<your-tenant>.atlassian.net
+#   JIRA_LOGIN      - login email
+#   JIRA_API_TOKEN  - API token (https://id.atlassian.com/manage-profile/security/api-tokens)
+#
+# Exit codes:
+#   0  success
+#   1  download failed (HTTP error)
+#   2  missing required env var
+#   3  invalid arguments
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>" >&2
+  exit 3
+fi
+ID_OR_URL="$1"
+OUTPUT_PATH="$2"
+
+# Resolve credentials: prefer env, fall back to jira-cli config for server/login.
+JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+if [[ -z "${JIRA_SERVER:-}" && -f "$JIRA_CONFIG" ]]; then
+  JIRA_SERVER=$(grep '^server:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+if [[ -z "${JIRA_LOGIN:-}" && -f "$JIRA_CONFIG" ]]; then
+  JIRA_LOGIN=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+
+for VAR in JIRA_SERVER JIRA_LOGIN JIRA_API_TOKEN; do
+  if [[ -z "${!VAR:-}" ]]; then
+    echo "ERROR: $VAR is not set." >&2
+    echo "Required env vars: JIRA_SERVER, JIRA_LOGIN, JIRA_API_TOKEN." >&2
+    echo "Generate an API token: https://id.atlassian.com/manage-profile/security/api-tokens" >&2
+    exit 2
+  fi
+done
+
+OUTPUT_DIR=$(dirname "$OUTPUT_PATH")
+if [[ ! -d "$OUTPUT_DIR" ]]; then
+  echo "ERROR: Output directory does not exist: $OUTPUT_DIR" >&2
+  exit 3
+fi
+
+if [[ "$ID_OR_URL" == http*://* ]]; then
+  ATTACHMENT_URL="$ID_OR_URL"
+else
+  ATTACHMENT_URL="${JIRA_SERVER%/}/rest/api/3/attachment/content/$ID_OR_URL"
+fi
+
+JIRA_AUTH=$(printf '%s' "$JIRA_LOGIN:$JIRA_API_TOKEN" | base64 | tr -d '\n')
+
+# Atlassian responds 302 to a signed URL on media.atlassian.com that has its
+# own auth and rejects Basic. Two-step: capture Location, then GET unauthed.
+HEADERS_FILE=$(mktemp)
+trap 'rm -f "$HEADERS_FILE"' EXIT
+
+HTTP_CODE=$(curl -sS -o /dev/null -w '%{http_code}' \
+  --max-redirs 0 \
+  -D "$HEADERS_FILE" \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Accept: */*" \
+  "$ATTACHMENT_URL" || true)
+
+case "$HTTP_CODE" in
+  302|303|307)
+    SIGNED_URL=$(awk '/^[Ll]ocation:/{sub(/^[Ll]ocation:[ \t]*/,""); sub(/\r$/,""); print; exit}' "$HEADERS_FILE")
+    if [[ -z "$SIGNED_URL" ]]; then
+      echo "ERROR: Got HTTP $HTTP_CODE but no Location header in response." >&2
+      exit 1
+    fi
+    curl -sSf -o "$OUTPUT_PATH" "$SIGNED_URL" || { echo "ERROR: Download from signed URL failed." >&2; exit 1; }
+    ;;
+  200)
+    curl -sSf -o "$OUTPUT_PATH" \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "Accept: */*" \
+      "$ATTACHMENT_URL" || { echo "ERROR: Direct download from $ATTACHMENT_URL failed." >&2; exit 1; }
+    ;;
+  401|403)
+    echo "ERROR: Authentication failed (HTTP $HTTP_CODE). Verify JIRA_LOGIN and JIRA_API_TOKEN." >&2
+    exit 1
+    ;;
+  404)
+    echo "ERROR: Attachment not found at $ATTACHMENT_URL (HTTP 404). Verify the ID and your access." >&2
+    exit 1
+    ;;
+  *)
+    echo "ERROR: Unexpected HTTP $HTTP_CODE from $ATTACHMENT_URL" >&2
+    exit 1
+    ;;
+esac
+
+echo "  ✓ Downloaded -> $OUTPUT_PATH"

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/skills/jira-read-ticket/SKILL.md

@@ -34,7 +34,23 @@ Call `mcp__atlassian__getJiraIssue` for the target ticket. Extract and preserve:
 - Full description (preserve formatting)
 - Acceptance criteria section if separately structured
 - **Validation Journey** section if present (pass verbatim to downstream)
-- Attachments list (names + URLs, do not download unless needed)
+- Attachments list — capture `id`, `filename`, `mimeType`, `size`, and `content` URL for each. Do not download unless a downstream task needs the bytes (see "Downloading attachments" below).
+
+#### Downloading attachments (opt-in)
+
+The Atlassian MCP exposes attachment metadata but no binary-fetch tool ([JRACLOUD-97830](https://jira.atlassian.com/browse/JRACLOUD-97830), [ECO-1265](https://jira.atlassian.com/browse/ECO-1265)). Fetch attachment bytes only when a downstream task explicitly needs them — e.g., a design-fidelity check on an image, log-file analysis, PDF text extraction. For everything else, keep the URL reference and move on.
+
+```bash
+bash .claude/skills/jira-read-ticket/scripts/download-attachment.sh <id-or-content-url> <output-path>
+```
+
+Requires `JIRA_SERVER`, `JIRA_LOGIN`, and `JIRA_API_TOKEN` in the environment (same contract as `jira-evidence`). If those are not set the helper exits with code 2 and a clear remediation message — record the URL only and continue.
+
+After download, branch on `mimeType`:
+- `image/*` — pass the local path to image-aware downstream tools
+- `text/*`, `application/json`, `application/xml`, `application/x-yaml` — read inline as text
+- `application/pdf` — extract text via downstream tooling if needed
+- everything else — record path only; do not attempt to inline binary content
 
 ### Comments
 
@@ -121,7 +137,7 @@ Produce a single structured output that the caller can pass verbatim to downstre
 <chronological comments, flagged items called out>
 
 ### Attachments
-<list>
+<list with id, filename, mimeType, size, content URL — note any that were downloaded and their local paths>
 
 ## Remote Links
 ### Pull Requests (<count>)

package/plugins/src/base/skills/jira-read-ticket/scripts/download-attachment.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# download-attachment.sh — Download a JIRA attachment to a local file.
+#
+# Usage:
+#   bash download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>
+#
+# Why this helper exists:
+#   The Atlassian MCP server (mcp__atlassian__*) returns attachment metadata
+#   (id, filename, mimeType, size, content URL) on getJiraIssue but provides
+#   no tool to fetch the binary content. This script closes the gap by
+#   hitting the Jira REST API directly with Basic auth, mirroring the
+#   env-var contract already used by jira-evidence/scripts/post-evidence.sh.
+#
+#   See https://jira.atlassian.com/browse/JRACLOUD-97830 for the upstream
+#   gap; remove this helper once Atlassian ships a download tool in the MCP.
+#
+# Required env vars:
+#   JIRA_SERVER     - https://<your-tenant>.atlassian.net
+#   JIRA_LOGIN      - login email
+#   JIRA_API_TOKEN  - API token (https://id.atlassian.com/manage-profile/security/api-tokens)
+#
+# Exit codes:
+#   0  success
+#   1  download failed (HTTP error)
+#   2  missing required env var
+#   3  invalid arguments
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: download-attachment.sh <ATTACHMENT_ID_OR_URL> <OUTPUT_PATH>" >&2
+  exit 3
+fi
+ID_OR_URL="$1"
+OUTPUT_PATH="$2"
+
+# Resolve credentials: prefer env, fall back to jira-cli config for server/login.
+JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+if [[ -z "${JIRA_SERVER:-}" && -f "$JIRA_CONFIG" ]]; then
+  JIRA_SERVER=$(grep '^server:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+if [[ -z "${JIRA_LOGIN:-}" && -f "$JIRA_CONFIG" ]]; then
+  JIRA_LOGIN=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+fi
+
+for VAR in JIRA_SERVER JIRA_LOGIN JIRA_API_TOKEN; do
+  if [[ -z "${!VAR:-}" ]]; then
+    echo "ERROR: $VAR is not set." >&2
+    echo "Required env vars: JIRA_SERVER, JIRA_LOGIN, JIRA_API_TOKEN." >&2
+    echo "Generate an API token: https://id.atlassian.com/manage-profile/security/api-tokens" >&2
+    exit 2
+  fi
+done
+
+OUTPUT_DIR=$(dirname "$OUTPUT_PATH")
+if [[ ! -d "$OUTPUT_DIR" ]]; then
+  echo "ERROR: Output directory does not exist: $OUTPUT_DIR" >&2
+  exit 3
+fi
+
+if [[ "$ID_OR_URL" == http*://* ]]; then
+  ATTACHMENT_URL="$ID_OR_URL"
+else
+  ATTACHMENT_URL="${JIRA_SERVER%/}/rest/api/3/attachment/content/$ID_OR_URL"
+fi
+
+JIRA_AUTH=$(printf '%s' "$JIRA_LOGIN:$JIRA_API_TOKEN" | base64 | tr -d '\n')
+
+# Atlassian responds 302 to a signed URL on media.atlassian.com that has its
+# own auth and rejects Basic. Two-step: capture Location, then GET unauthed.
+HEADERS_FILE=$(mktemp)
+trap 'rm -f "$HEADERS_FILE"' EXIT
+
+HTTP_CODE=$(curl -sS -o /dev/null -w '%{http_code}' \
+  --max-redirs 0 \
+  -D "$HEADERS_FILE" \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Accept: */*" \
+  "$ATTACHMENT_URL" || true)
+
+case "$HTTP_CODE" in
+  302|303|307)
+    SIGNED_URL=$(awk '/^[Ll]ocation:/{sub(/^[Ll]ocation:[ \t]*/,""); sub(/\r$/,""); print; exit}' "$HEADERS_FILE")
+    if [[ -z "$SIGNED_URL" ]]; then
+      echo "ERROR: Got HTTP $HTTP_CODE but no Location header in response." >&2
+      exit 1
+    fi
+    curl -sSf -o "$OUTPUT_PATH" "$SIGNED_URL" || { echo "ERROR: Download from signed URL failed." >&2; exit 1; }
+    ;;
+  200)
+    curl -sSf -o "$OUTPUT_PATH" \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "Accept: */*" \
+      "$ATTACHMENT_URL" || { echo "ERROR: Direct download from $ATTACHMENT_URL failed." >&2; exit 1; }
+    ;;
+  401|403)
+    echo "ERROR: Authentication failed (HTTP $HTTP_CODE). Verify JIRA_LOGIN and JIRA_API_TOKEN." >&2
+    exit 1
+    ;;
+  404)
+    echo "ERROR: Attachment not found at $ATTACHMENT_URL (HTTP 404). Verify the ID and your access." >&2
+    exit 1
+    ;;
+  *)
+    echo "ERROR: Unexpected HTTP $HTTP_CODE from $ATTACHMENT_URL" >&2
+    exit 1
+    ;;
+esac
+
+echo "  ✓ Downloaded -> $OUTPUT_PATH"