@codyswann/lisa 1.67.3 → 1.69.0

package/README.md

@@ -1,77 +1,72 @@
-# NPM
+# Lisa
 
-Developers write specs and answer questions. Agents implement, test, verify, question, and document.
+Lisa is a governance layer for AI-assisted software development. It ensures that AI agents — whether running on a developer's machine or in CI/CD — follow the same standards, workflows, and quality gates.
 
-## About This Project
+## What Lisa Does
 
-> Ask Claude: "What is the purpose of this project and how does it work?"
+### Intent Routing
 
-## Step 1: Install Claude Code
+When a request comes in (from a human, a JIRA ticket, or a scheduled job), Lisa classifies it and routes it to the appropriate **flow**. Flows are ordered sequences of specialized agents, each with a defined role.
 
-```bash
-brew install claude-code
-# Or: npm install -g @anthropic-ai/claude-code
-```
-
-## Step 2: Set Up This Project
-
-> Ask Claude: "I just cloned this repo. Walk me through the full setup including installing dependencies, environment variables, and any other configuration."
-
-## Step 3: Build and Test
+A request to fix a bug routes to a different flow than a request to build a feature or reduce code complexity. The routing is automatic based on context, but can be overridden explicitly via slash commands.
 
-> Ask Claude: "How do I build this package and run the tests?"
+### Flows and Agents
 
-## Step 4: Work on a Feature
+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.
 
-> Ask Claude: "I have Jira ticket [TICKET-ID]. Research the codebase, create a plan, and implement it."
+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.
 
-Or with utility commands:
+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.
 
-- `/plan:add-test-coverage` - Increase test coverage to a threshold
-- `/plan:fix-linter-error` - Fix ESLint rule violations
-- `/plan:local-code-review` - Review local branch changes
-- `/plan:lower-code-complexity` - Reduce cognitive complexity
-- `/plan:reduce-max-lines` - Reduce max file lines threshold
-- `/plan:reduce-max-lines-per-function` - Reduce max function lines
+### Quality Gates
 
-## Lisa Commands
+Lisa enforces quality through layered gates:
 
-> Ask Claude: "What Lisa commands are available, and how do I use them? Read HUMAN.md and give me a summary."
+- **Rules** are loaded into every AI session automatically. They define coding standards, architectural patterns, and behavioral expectations. The AI follows them because they're part of its context.
+- **Git hooks** are hard stops. Pre-commit hooks run linting, formatting, and type checking. Pre-push hooks run tests, coverage checks, security audits, and dead code detection. Nothing ships without passing.
+- **Claude hooks** bridge AI actions to project tooling — ensuring that when the AI commits, pushes, or creates a PR, the project's quality infrastructure runs.
 
-## Common Tasks
+### Location Agnostic
 
-### Code Review
+The same rules, skills, and quality gates apply everywhere:
 
-> Ask Claude: "Review the changes on this branch and suggest improvements."
+- 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
 
-### Submit a PR
+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.
 
-> Ask Claude: "Commit my changes and open a pull request."
+### Template Governance
 
-### Fix Lint Errors
+Lisa distributes its standards to downstream projects as templates. When a project installs Lisa, it receives:
 
-> Ask Claude: "Run the linter and fix all errors."
+- Linting, formatting, and type checking configurations
+- Test and coverage infrastructure
+- CI/CD workflows
+- Git hooks
+- AI agent definitions, skills, and rules
 
-### Add Test Coverage
+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).
 
-> Ask Claude: "Increase test coverage for the files I changed."
+## Quick Start
 
-### Publish to npm
-
-> Ask Claude: "Walk me through publishing a new version of this package to npm."
-
-### Deploy
-
-> Ask Claude: "Walk me through deploying this project."
+```bash
+brew install claude-code
+```
 
-## Project Standards
+> Ask Claude: "I just cloned this repo. Walk me through setup."
 
-> Ask Claude: "What coding standards and conventions does this project follow?"
+## Working With Lisa
 
-## Architecture
+> Ask Claude: "I have JIRA ticket [TICKET-ID]. Research, plan, and implement it."
 
-> Ask Claude: "Explain the architecture of this project, including key components and how they interact."
+Or use slash commands directly:
 
-## Troubleshooting
+- `/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
 
-> Ask Claude: "I'm having an issue with [describe problem]. Help me debug it."
+> Ask Claude: "What commands are available?"

package/all/copy-overwrite/.claude/rules/base-rules.md

@@ -69,56 +69,6 @@ ASK FIRST:
 - Before adding a type-checking suppression comment (e.g. ts-ignore, ts-expect-error, ts-nocheck, type: ignore).
 - Lint suppression in test files is acceptable without asking only when comprehensive test coverage requires it (e.g. file length limits) or when intentional duplication improves test isolation. Include matching re-enable comments where applicable.
 
-Bug Triage:
-
-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).
-
-Bug Implementation:
-
-1. Use the output of Bug Triage as your guide. Do not skip triage.
-
-Task Triage:
-
-1. Verify you have all information needed to implement this task (acceptance criteria, design specs, environment information, dependencies, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
-2. Verify you have a clear understanding of the expected behavior or outcome when the task is complete. If not, stop and clarify before starting.
-3. Identify all dependencies (other tasks, services, APIs, data) that must be in place before you can complete this task. If any are unresolved, stop and raise them before starting implementation.
-4. Verify you have access to the tools, environments, and permissions needed to deploy and verify this task (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 task is implemented correctly and prevent regressions.
-6. Define the documentation you will create or update to explain the "how" and "what" behind this task so another developer understands it.
-7. If you can verify your implementation 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 task is complete beyond a shadow of a doubt (e.g. deploy to the target environment, invoke the API, open a browser, run the process, check logs).
-
-Task Implementation:
-
-1. Use the output of Task Triage as your guide. Do not skip triage.
-
-Epic Triage:
-
-1. Verify you have all information needed to understand the full scope of this epic (goals, acceptance criteria, impacted systems, design specs, dependencies, etc.). Do not make assumptions. If anything is missing, stop and ask before proceeding.
-2. Verify the epic is broken down into concrete, well-scoped bugs, tasks, and/or stories that are each fully triaged. If ambiguities exist, stop and resolve them before breaking it down.
-3. Identify all cross-cutting concerns (auth, performance, security, data migrations, third-party integrations) that need to be addressed across the epic.
-4. Identify all dependencies between tasks within the epic, or on external epics, teams, or services. Determine the correct order of execution.
-5. Verify you have access to the tools, environments, and permissions needed to deploy and verify all tasks within this epic (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 proceeding.
-6. Define the overall test strategy for the epic (unit, integration, end-to-end, load testing).
-7. Define the documentation that will need to be created or updated to cover the full scope of the epic so another developer understands the architecture, design decisions, and implementation.
-8. Define measurable acceptance criteria that confirm the epic is fully complete.
-9. Define how you will verify the epic is fully delivered beyond a shadow of a doubt (e.g. deploy to the target environment, walk through all acceptance criteria end-to-end, confirm all child tasks/stories are closed, confirm no regressions).
-
-Epic Implementation:
-
-1. Use the output of Epic Triage as your guide. Do not skip triage.
-2. Work through each task and/or story in the order defined during triage, respecting dependencies.
-3. Apply the Bug Implementation and Task Implementation processes to each child bug or task, respectively, as you work through them.
-4. Continuously update the epic and its child issues in JIRA as progress is made.
-5. Do not consider the epic complete until all acceptance criteria are verified in the target environment and all child issues are resolved.
-
 Multi-Repository Awareness:
 
 When working in a microservices architecture, the code you need may span multiple repositories. Watch for these signals that you're missing context:

package/all/copy-overwrite/.claude/rules/intent-routing.md

@@ -0,0 +1,126 @@
+# Intent Routing
+
+Classify the user's request and execute the matching flow. Each flow is a sequence of agents. Sub-flows can be invoked by any flow.
+
+## Flows
+
+### Fix
+When: Bug reports, broken behavior, error messages, JIRA bug tickets.
+
+Sequence:
+1. `git-history-analyzer` — understand why affected code exists, find related past fixes/reverts
+2. `debug-specialist` — reproduce the bug, prove root cause with evidence
+3. `architecture-specialist` — assess fix risk, identify files to change, check for ripple effects
+4. `test-specialist` — design regression test strategy
+5. `bug-fixer` — implement fix via TDD (reproduction becomes failing test)
+6. **Verify sub-flow**
+7. **Ship sub-flow**
+8. `learner` — capture discoveries for future sessions
+
+### Build
+When: New features, stories, tasks, JIRA story/task tickets.
+
+Sequence:
+1. `product-specialist` — define acceptance criteria, user flows, error states
+2. `architecture-specialist` — research codebase, design approach, map dependencies
+3. `test-specialist` — design test strategy (coverage, edge cases, TDD sequence)
+4. `builder` — implement via TDD (acceptance criteria become tests)
+5. **Verify sub-flow**
+6. **Review sub-flow**
+7. **Ship sub-flow**
+8. `learner` — capture discoveries
+
+### Investigate
+When: "Why is this happening?", triage requests, JIRA spike tickets.
+
+Sequence:
+1. `git-history-analyzer` — understand code evolution, find related changes
+2. `debug-specialist` — reproduce, trace execution, prove root cause
+3. `ops-specialist` — check logs, errors, health (if runtime issue)
+4. Report findings with evidence, recommend next action (Fix, Build, or escalate)
+
+### Plan
+When: "Break this down", epic planning, large scope work, JIRA epic tickets.
+
+Sequence:
+1. `product-specialist` — define acceptance criteria for the whole scope
+2. `architecture-specialist` — understand scope, map dependencies, identify cross-cutting concerns
+3. Break down into ordered tasks, each with: acceptance criteria, verification type, dependencies
+
+### Verify
+When: Pre-ship quality gate. Used as a sub-flow by Fix and Build.
+
+Sequence:
+1. Run full test suite — all tests must pass before proceeding
+2. Run quality checks — lint, typecheck, and format
+3. `verification-specialist` — verify acceptance criteria are met empirically
+
+### Ship
+When: Code is ready to deploy. Used as a sub-flow by Fix, Build, and Improve.
+
+Sequence:
+1. Commit — atomic conventional commits via `git-commit` skill
+2. PR — create/update pull request via `git-submit-pr` skill
+3. **Review sub-flow** (if not already done)
+4. PR Watch Loop (repeat until mergeable):
+   - If status checks fail → fix and push
+   - If merge conflicts → resolve and push
+   - If bot review feedback (CodeRabbit, etc.):
+     - Valid feedback → implement fix, push, resolve comment
+     - Invalid feedback → reply explaining why, resolve comment
+   - Repeat until all checks pass and all comments are resolved
+5. Merge the PR
+6. `ops-specialist` — deploy to target environment
+7. `verification-specialist` — post-deploy health check and smoke test
+8. `ops-specialist` — monitor for errors in first minutes
+
+### Review
+When: Code review requests, PR review, quality assessment. Used as a sub-flow by Build.
+
+Sequence:
+1. Run in parallel: `quality-specialist`, `security-specialist`, `performance-specialist`
+2. `product-specialist` — verify acceptance criteria are met empirically
+3. `test-specialist` — verify test coverage and quality
+4. Consolidate findings, ranked by severity
+
+### Improve
+When: Refactoring, optimization, coverage improvement, complexity reduction.
+
+Sequence:
+1. `architecture-specialist` — identify target, measure baseline, plan approach
+2. `test-specialist` — ensure existing test coverage before refactoring (safety net)
+3. `builder` — implement improvements via TDD
+4. `verification-specialist` — measure again, prove improvement
+5. **Ship sub-flow**
+6. `learner` — capture discoveries
+
+#### Improve: Test Quality
+When: "Improve tests", "strengthen test suite", "fix weak tests", test quality improvement.
+
+Sequence:
+1. `test-specialist` — scan tests, identify weak/brittle tests, rank by improvement impact
+2. `builder` — implement test improvements
+3. **Verify sub-flow**
+4. **Ship sub-flow**
+5. `learner` — capture discoveries
+
+### Monitor
+When: "Check the logs", "Any errors?", health checks, production monitoring.
+
+Sequence:
+1. `ops-specialist` — health checks, log inspection, error monitoring, performance analysis
+2. Report findings, escalate if action needed
+
+## JIRA Entry Point
+
+When the request references a JIRA ticket (ticket ID like PROJ-123 or a JIRA URL):
+
+1. Hand off to `jira-agent`
+2. `jira-agent` reads the ticket, validates structural quality, and runs analytical triage
+3. If triage finds unresolved ambiguities, `jira-agent` posts findings and STOPS — no work begins
+4. `jira-agent` determines intent and delegates to the appropriate flow above
+5. `jira-agent` syncs progress at milestones and posts evidence at completion
+
+## Sub-flow Usage
+
+Flows reference sub-flows by name. When a flow says "Ship sub-flow", execute the full Ship sequence. When it says "Review sub-flow", execute the full Review sequence. Sub-flows can be nested (e.g., Ship includes Review).

package/all/copy-overwrite/.claude/rules/security-audit-handling.md

@@ -0,0 +1,17 @@
+# Security Audit Handling
+
+If `git push` fails because the pre-push hook reports security vulnerabilities, follow these steps. Never use `--no-verify` to bypass the security audit.
+
+## Node.js Projects (GHSA advisories)
+
+1. Note the GHSA ID(s), affected package(s), and advisory URL from the error output
+2. Check the advisory URL to determine if a patched version of the vulnerable package exists
+3. If a patched version exists: add a resolution/override in package.json to force the patched version (add to both `resolutions` and `overrides` sections), then run the package manager install command to regenerate the lockfile, commit the changes, and retry the push
+4. If no patched version exists and the vulnerability is safe for this project (e.g., transitive dependency with no untrusted input, devDeps only, or build tool only): add an exclusion entry to `audit.ignore.local.json` with the format `{"id": "GHSA-xxx", "package": "pkg-name", "reason": "why this is safe for this project"}`, then commit and retry the push
+
+## Rails Projects (bundler-audit)
+
+1. Note the advisory ID, affected gem, and advisory URL from the error output
+2. Check if a patched version of the gem exists
+3. If a patched version exists: update the gem in Gemfile, run `bundle update <gem>`, commit the changes, and retry the push
+4. If no patched version exists and the vulnerability is safe for this project: document the exception and retry the push