Lisa

Lisa is a Claude Code governance framework that ensures Claude produces high-quality, consistent code through multiple layers of guardrails, guidance, and automated enforcement.

New to Lisa? Start with the Architecture Overview for a visual guide to how Lisa works, including the developer workflow diagram and multi-layer governance architecture.

Why Lisa Exists

Claude Code is powerful, but without guardrails it can:

• Produce inconsistent code styles across sessions
• Skip tests or quality checks when not reminded
• Over-engineer solutions or create unnecessary abstractions
• Mutate data instead of using immutable patterns
• Leave deprecated code instead of cleanly deleting it

Lisa solves this by applying a comprehensive governance system that guides Claude's behavior at every step.

The key insight: Not every developer needs to be an AI expert. Platform teams with deep AI knowledge can encode best practices into Lisa, and implementation teams get the benefits automatically through simple commands.

How It Works

Lisa applies multiple layers of quality control to your project:

| Layer | Purpose | Examples | |-------|---------|----------| | CLAUDE.md | Direct behavioral rules | "Never skip tests", "Always use immutable patterns" | | Skills | Teach patterns & philosophy | Immutability, TDD, YAGNI/SOLID/DRY/KISS | | Hooks | Auto-enforcement on every edit | Format and lint after Write/Edit operations | | Slash Commands | Guided workflows | /project:implement, /project:review, /git:commit | | Custom ESLint Plugins | Enforce code structure | Statement ordering, component structure | | Thresholds | Configurable limits | Max complexity, max file length | | Git Hooks | Pre-commit quality gates | Husky + lint-staged + commitlint | | Agents | Specialized sub-agents | Codebase analysis, pattern finding |

These layers work together. When Claude writes code:

1. CLAUDE.md tells it what patterns to follow
2. Skills teach it the philosophy behind those patterns
3. Hooks automatically format and lint the code
4. ESLint plugins catch structural violations
5. Git hooks prevent commits that fail quality checks

Team & Organization Usage

Lisa is designed for a two-tier organizational model that separates AI expertise from day-to-day development:

┌─────────────────────────────────────────────────────────────┐
│                      PLATFORM TEAM                          │
│                                                             │
│  • Deep AI/LLM expertise (prompting, context engineering)  │
│  • Domain knowledge of coding standards & best practices    │
│  • Maintains and iterates on Lisa configurations           │
│  • Writes skills, hooks, ESLint rules, slash commands      │
│  • Tests guardrails against real-world edge cases          │
│                                                             │
│                         │                                   │
│                         ▼                                   │
│                   Lisa Repository                           │
│                         │                                   │
│                         ▼                                   │
├─────────────────────────────────────────────────────────────┤
│                   IMPLEMENTATION TEAMS                      │
│                                                             │
│  • Focus on building end-user software                      │
│  • Run `npx @codyswann/lisa` to bootstrap projects          │
│  • Use simple commands like `/project:implement`            │
│  • Don't need deep AI expertise                             │
│  • Automatically get guardrails & quality enforcement       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Why This Model Works

For Platform Teams:

• Centralize AI governance expertise in one place
• Iterate on prompts, skills, and guardrails based on real feedback
• A/B test different approaches across the organization
• Push improvements to all teams instantly via Lisa updates

For Implementation Teams:

• No need to learn prompt engineering or context engineering
• Simple commands produce high-quality, consistent code
• Guardrails prevent common mistakes automatically
• Focus on business logic, not AI wrangling

How Implementation Teams Work

Once Lisa is applied to a project, developers have two paths:

Path 1: Just Type a Prompt

Even if a developer just types a vague request, Lisa's built-in prompt-complexity-scorer skill automatically evaluates it:

Developer: "Make the app faster"

Claude: This request scores 8/10 on complexity. I suggest writing it
        as a spec to plan it out properly.

        Would you like me to create `specs/performance-optimization.md`?

Complex or vague prompts (score 5+) are automatically routed to the spec workflow. Simple, well-defined requests (score 1-4) proceed immediately. Developers don't need to know which path to take—Lisa routes them automatically.

Path 2: The Full Workflow

For planned work, the workflow is two commands:

# 1. Create a spec file describing what you want
#    (or let Claude create it from your prompt)
echo "Add user authentication with OAuth" > specs/add-auth.md

# 2. Bootstrap: research, analyze, identify gaps
/project:bootstrap @specs/add-auth.md

# 3. Execute: plan tasks, implement with TDD, verify completion
/project:execute @projects/add-auth

That's it. Behind the scenes, Lisa ensures:

• Comprehensive codebase and web research
• Knowledge gap detection (stops if questions need answering)
• Task breakdown and TDD implementation
• Verification that all tasks completed
• New patterns captured in .claude/rules/PROJECT_RULES.md

Platform Team Iteration Example

1. Platform Team discovers Claude sometimes creates overly complex functions
2. Platform Team adds a cognitiveComplexity: 10 threshold to ESLint config
3. Platform Team writes a skill teaching Claude to decompose complex logic
4. Platform Team pushes update to Lisa repository
5. Implementation Teams run lisa on their projects (or it happens via CI)
6. Implementation Teams now automatically get simpler, more maintainable code

Upstreaming Improvements

When implementation teams make improvements to Lisa-managed files (better CI configs, new hooks, etc.), the /lisa:review-implementation command helps upstream those changes back to Lisa:

# Start Claude Code with access to both your project and Lisa
claude --add-dir ~/lisa

# Run the review command
/lisa:review-implementation

This command:

1. Compares your project's Lisa-managed files against Lisa's source templates
2. Generates a diff report showing what has changed
3. Offers to copy improvements back to Lisa for all teams to benefit

Forking for Your Organization

# Fork Lisa for your organization
gh repo fork CodySwannGT/lisa --org your-org --clone

# Customize configurations
cd lisa
# Edit skills, hooks, CLAUDE.md, ESLint rules, etc.

# Push to your org's fork
git push origin main

Implementation teams then install from your organization's fork:

# Install globally from your fork
npm install -g github:your-org/lisa

# Or use npx with your fork
npx github:your-org/lisa /path/to/project

Installation

Install Lisa globally via npm:

npm install -g @codyswann/lisa

Or use npx to run without installing:

npx @codyswann/lisa /path/to/project

Requirements

• Node.js 18+ (workflows default to 22.x)
• npm, bun, or pnpm

Optional Tools

These tools enhance Lisa's capabilities but are not required:

• CodeRabbit CLI - AI-powered code review tool used by /project:review

  Installation (choose one):

  # Recommended
  curl -fsSL https://cli.coderabbit.ai/install.sh | sh
  coderabbit --version  # Verify installation
  
  # Homebrew (macOS/Linux)
  brew install coderabbit
  
  # NPX (no install needed)
  npx coderabbitai-mcp@latest

  If not installed, the CodeRabbit review step in /project:review will be skipped silently.

Usage

Run Lisa against any project directory:

lisa /path/to/your-project

# Or from within your project
lisa .

# Or with npx (no install required)
npx @codyswann/lisa .

Options

| Option | Description | |--------|-------------| | -n, --dry-run | Show what would be done without making changes | | -y, --yes | Non-interactive mode (auto-accept defaults, overwrite on conflict) | | -v, --validate | Validate project compatibility without applying changes | | -u, --uninstall | Remove Lisa-managed files from the project | | -h, --help | Show help message |

Dry Run

Preview changes before applying them:

lisa --dry-run /path/to/your-project

CI/CD Usage

For automated pipelines, use non-interactive mode:

lisa --yes /path/to/project

# Or with npx
npx @codyswann/lisa --yes /path/to/project

Validate Mode

Check project compatibility without making changes:

lisa --validate /path/to/project

Uninstall

Remove Lisa-managed files from a project:

lisa --uninstall /path/to/project

# Preview what would be removed
lisa --dry-run --uninstall /path/to/project

Note: Files applied with copy-contents or merge strategies require manual cleanup as they modify existing content.

GitHub Rulesets

Lisa can also apply GitHub repository rulesets via a separate script. This enforces branch protection rules like requiring PRs, status checks, and preventing force pushes.

# Apply rulesets to a project's GitHub repo
~/lisa/lisa-github-rulesets.sh /path/to/project

# Preview what would be applied
~/lisa/lisa-github-rulesets.sh --dry-run /path/to/project

# Non-interactive mode
~/