@codyswann/lisa 1.0.0 → 1.0.2

package/README.md

@@ -2,6 +2,8 @@
 
 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](OVERVIEW.md)** 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:
@@ -60,7 +62,7 @@ Lisa is designed for a **two-tier organizational model** that separates AI exper
 │                   IMPLEMENTATION TEAMS                      │
 │                                                             │
 │  • Focus on building end-user software                      │
-│  • Run `lisa.sh` to bootstrap projects                      │
+│  • Run `npx @codyswann/lisa` to bootstrap projects          │
 │  • Use simple commands like `/project:implement`            │
 │  • Don't need deep AI expertise                             │
 │  • Automatically get guardrails & quality enforcement       │
@@ -122,7 +124,7 @@ That's it. Behind the scenes, Lisa ensures:
 - Knowledge gap detection (stops if questions need answering)
 - Task breakdown and TDD implementation
 - Verification that all tasks completed
-- New patterns captured in `PROJECT_RULES.md`
+- New patterns captured in `.claude/rules/PROJECT_RULES.md`
 
 ### Platform Team Iteration Example
 
@@ -130,9 +132,26 @@ That's it. Behind the scenes, Lisa ensures:
 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.sh` on their projects (or it happens via CI)
+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:
+
+```bash
+# 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
 
 ```bash
@@ -147,38 +166,68 @@ cd lisa
 git push origin main
 ```
 
-Implementation teams then clone from your organization's fork:
+Implementation teams then install from your organization's fork:
 
 ```bash
-git clone https://github.com/your-org/lisa ~/lisa
-~/lisa/lisa.sh /path/to/project
+# 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
 
-Clone the Lisa repository to your machine:
+Install Lisa globally via npm:
 
 ```bash
-git clone <lisa-repo-url> ~/lisa
-cd ~/lisa
-npm install
-npm run build
+npm install -g @codyswann/lisa
+```
+
+Or use npx to run without installing:
+
+```bash
+npx @codyswann/lisa /path/to/project
 ```
 
 ### Requirements
 
-- **Node.js 18+**
-- **npm** or **bun**
+- **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](https://coderabbit.ai/)** - AI-powered code review tool used by `/project:review`
+
+  **Installation (choose one):**
+  ```bash
+  # 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:
 
 ```bash
-~/lisa/lisa.sh /path/to/your-project
+lisa /path/to/your-project
 
 # Or from within your project
-~/lisa/lisa.sh .
+lisa .
+
+# Or with npx (no install required)
+npx @codyswann/lisa .
 ```
 
 ### Options
@@ -196,7 +245,7 @@ Run Lisa against any project directory:
 Preview changes before applying them:
 
 ```bash
-~/lisa/lisa.sh --dry-run /path/to/your-project
+lisa --dry-run /path/to/your-project
 ```
 
 ### CI/CD Usage
@@ -204,7 +253,10 @@ Preview changes before applying them:
 For automated pipelines, use non-interactive mode:
 
 ```bash
-~/lisa/lisa.sh --yes /path/to/project
+lisa --yes /path/to/project
+
+# Or with npx
+npx @codyswann/lisa --yes /path/to/project
 ```
 
 ### Validate Mode
@@ -212,7 +264,7 @@ For automated pipelines, use non-interactive mode:
 Check project compatibility without making changes:
 
 ```bash
-~/lisa/lisa.sh --validate /path/to/project
+lisa --validate /path/to/project
 ```
 
 ### Uninstall
@@ -220,10 +272,10 @@ Check project compatibility without making changes:
 Remove Lisa-managed files from a project:
 
 ```bash
-~/lisa/lisa.sh --uninstall /path/to/project
+lisa --uninstall /path/to/project
 
 # Preview what would be removed
-~/lisa/lisa.sh --dry-run --uninstall /path/to/project
+lisa --dry-run --uninstall /path/to/project
 ```
 
 Note: Files applied with `copy-contents` or `merge` strategies require manual cleanup as they modify existing content.
@@ -339,6 +391,7 @@ Pre-built workflows for common tasks:
 | `/project:verify` | Run all quality checks |
 | `/git:commit` | Create conventional commit |
 | `/git:submit-pr` | Create pull request |
+| `/lisa:review-implementation` | Compare project files against Lisa templates, upstream changes |
 
 ### Custom ESLint Plugins
 
@@ -350,7 +403,6 @@ Lisa includes custom ESLint plugins that enforce code structure:
 **eslint-plugin-component-structure** (Expo)
 - `single-component-per-file` - One component per file
 - `require-memo-in-view` - Memoization in view components
-- `no-inline-styles` - Extract styles to StyleSheet
 
 ### Thresholds
 
@@ -360,10 +412,30 @@ Configurable limits in `eslint.thresholds.config.json`:
 {
   "cognitiveComplexity": 10,
   "maxLines": 300,
-  "maxLinesView": 300
+  "maxLinesPerFunction": 75
 }
 ```
 
+### File Backups
+
+When Lisa overwrites files that have local modifications (conflicts), it automatically creates timestamped backup copies in the `.lisabak/` directory. This allows you to review or recover your original files if needed.
+
+**Backup naming format:** `<YYYY-MM-DD>-<filename>.<extension>.lisa.bak`
+
+**Example:**
+```
+.lisabak/
+├── 2026-01-19-eslint.config.mjs.lisa.bak
+├── 2026-01-19-package.json.lisa.bak
+└── 2026-01-19-.prettierrc.json.lisa.bak
+```
+
+**Key behaviors:**
+- Backups are created only when files are overwritten (not on first creation or when identical)
+- Multiple backups of the same file on the same day are all preserved
+- The `.lisabak/` directory is automatically added to `.gitignore` (backups are local-only)
+- Backups are meant for manual review; the `.lisabak/` directory can be safely deleted after reviewing
+
 ## Project Type Detection
 
 Lisa auto-detects project types and applies appropriate configurations:
@@ -472,6 +544,28 @@ Once configured, all future releases are automatic:
 - npm CLI 11.5+ (workflow automatically installs latest)
 - Cannot use self-hosted GitHub runners (not yet supported by npm)
 
+**Workflow Configuration:**
+
+The `publish-to-npm.yml` workflow accepts configurable inputs:
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `node_version` | `20.x` | Node.js version to use |
+| `package_manager` | `npm` | Package manager (`npm`, `yarn`, or `bun`) |
+
+Example with custom configuration:
+
+```yaml
+publish:
+  uses: ./.github/workflows/publish-to-npm.yml
+  needs: [release]
+  with:
+    tag: ${{ needs.release.outputs.tag }}
+    version: ${{ needs.release.outputs.version }}
+    node_version: '22.x'
+    package_manager: 'bun'
+```
+
 ### Extending Lisa for Other Stacks
 
 Lisa currently supports TypeScript, npm-package, Expo, NestJS, and CDK—but the architecture is designed for extension. **We're calling on the community to contribute stack-specific configurations.**
@@ -581,7 +675,7 @@ Each type directory contains subdirectories that control how files are applied:
 
 **copy-contents**: For files like `.gitignore` where you want to ensure certain lines exist without removing custom entries.
 
-**create-only**: Template files that should only be created once (e.g., `PROJECT_RULES.md` for project-specific customization).
+**create-only**: Template files that should only be created once (e.g., `.claude/rules/PROJECT_RULES.md` for project-specific customization).
 
 **merge**: For `package.json` files. Performs a deep merge where:
 - Lisa provides default values
@@ -625,7 +719,6 @@ lisa/
 ├── nestjs/                         # NestJS projects
 ├── cdk/                            # CDK projects
 ├── tests/                          # Vitest test suite
-├── lisa.sh                         # Wrapper script
 ├── package.json
 ├── tsconfig.json
 └── vitest.config.ts
@@ -656,7 +749,7 @@ When principles conflict, **KISS wins**. The decision framework:
 
 ### Project-Specific Rules
 
-Edit `PROJECT_RULES.md` (created by Lisa) to add project-specific instructions:
+Edit `.claude/rules/PROJECT_RULES.md` (created by Lisa) to add project-specific instructions:
 
 ```markdown
 # Project Rules
@@ -708,14 +801,6 @@ nvm install 18
 nvm use 18
 ```
 
-#### "Permission denied" when running lisa.sh
-
-Make the script executable:
-
-```bash
-chmod +x ~/lisa/lisa.sh
-```
-
 #### JSON merge fails with "parse error"
 
 Your project's `package.json` may have syntax errors. Validate it:
@@ -736,10 +821,10 @@ chmod +x .claude/hooks/*.sh
 
 ```bash
 # See all operations without making changes
-~/lisa/lisa.sh --dry-run /path/to/project
+lisa --dry-run /path/to/project
 
 # Check compatibility issues
-~/lisa/lisa.sh --validate /path/to/project
+lisa --validate /path/to/project
 ```
 
 ## Development
@@ -763,7 +848,7 @@ npm test
 npm run test:watch
 
 # Run with coverage
-npm run test:coverage
+npm run test:cov
 ```
 
 ### Type Checking
@@ -862,6 +947,127 @@ EOF
 - Threshold-based complexity limits
 - Git hooks via Husky for pre-commit gates
 
+## Future Enhancements
+
+Planned improvements for future versions of Lisa:
+
+### Beads / Task Management Integration
+
+Integrate with [Beads](https://github.com/steveyegge/beads), a git-backed issue tracker engineered for AI-supervised coding workflows, and Claude Code's task management system (v2.1.16+).
+
+**Value:**
+- **Persistent Memory**: Beads stores tasks as JSONL in `.beads/`, version-controlled with code—agents maintain context across sessions
+- **Dependency-Aware Execution**: `bd ready` shows only unblocked work, enabling true parallel multi-agent execution
+- **Async Workflows**: Combine Claude Code Web + ntfy notifications + Beads status updates for fire-and-forget task execution
+- **Audit Trail**: Git-tracked task history provides immutable record of work decomposition and completion
+
+**Integration Points:**
+- Update `/project:plan` to create Beads issues with dependencies
+- Update `/project:execute` to claim and resolve tasks automatically
+- Enable multi-agent orchestration querying `bd ready` for unblocked work
+
+### Biome Migration
+
+Migrate formatting from Prettier to [Biome](https://biomejs.dev/) for 40x faster formatting, while keeping ESLint for governance-critical rules.
+
+**Value:**
+- **Performance**: Biome formats 10,000 files in 0.3s vs Prettier's 12.1s
+- **Unified Tooling**: Single binary replaces Prettier, reducing dependencies
+- **97% Prettier-Compatible**: Nearly identical output with minimal configuration changes
+
+**Approach:**
+- Replace Prettier with Biome formatter (low-risk, high-reward)
+- Keep ESLint for custom rules (enforce-statement-order, functional/immutable-data)
+- Monitor Biome's GritQL plugin system for future full migration when it matures
+
+**Note:** Full ESLint replacement is not recommended yet—Lisa's custom plugins and eslint-plugin-functional have no Biome equivalents.
+
+### ESLint Plugin Extraction
+
+Extract custom ESLint plugins to separate npm packages for independent versioning and broader adoption.
+
+**Current Plugins:**
+- `eslint-plugin-code-organization` (1 rule: enforce-statement-order)
+- `eslint-plugin-component-structure` (4 rules: container/view pattern enforcement)
+- `eslint-plugin-ui-standards` (3 rules: NativeWind/styling standards)
+
+**Value:**
+- **Independent Versioning**: Bug fixes ship without waiting for Lisa releases
+- **Reusability**: Any ESLint project can adopt these rules, not just Lisa users
+- **Easier Contribution**: Focused repos with clearer scope for community PRs
+- **Smaller Bundle**: Lisa package size reduced; users install only needed plugins
+- **Clear Ownership**: Each plugin has its own documentation and maintenance cycle
+
+**Extraction Order:**
+1. `eslint-plugin-code-organization` (generic, cleanest extraction)
+2. `eslint-plugin-ui-standards` (Expo-specific, smaller)
+3. `eslint-plugin-component-structure` (largest, most complex)
+
+### Test Library Standardization
+
+Standardize on Vitest across all Lisa-managed projects for consistent, fast testing.
+
+**Current State:** Lisa uses Vitest 3.0 with 97 tests, 90% coverage thresholds, and v8 provider.
+
+**Value:**
+- **Consistency**: All projects use same test APIs and patterns
+- **Performance**: Vitest is 10-20x faster than Jest in watch mode
+- **TypeScript-Native**: No ts-jest configuration needed
+- **Modern Ecosystem**: Growing adoption (20M+ weekly downloads), active maintenance
+
+**Trade-offs Considered:**
+- Jest: Industry standard but slower, requires ts-jest for TypeScript
+- Bun Test: Fastest but smallest ecosystem, 34% compatibility issues reported
+- Vitest: Best balance of speed, TypeScript support, and ecosystem maturity
+
+### Ruby on Rails Support
+
+Add Ruby on Rails as a project type with RuboCop integration and Rails-specific skills.
+
+**Detection:** Check for `Gemfile` + `Gemfile.lock` + `config/application.rb` + `app/` directory
+
+**What Lisa Would Provide:**
+- **RuboCop Configuration**: `.rubocop.yml` with rubocop-rails, rubocop-performance, rubocop-rspec
+- **Skills**: Rails conventions (MVC, service objects, concerns), RSpec testing, database/migrations
+- **Gemfile Merge**: Add development gems (rspec-rails, factory_bot_rails, faker) via merge strategy
+- **CI/CD**: GitHub workflows for RuboCop + RSpec
+
+**Skills to Create:**
+1. `rails-conventions` - MVC patterns, service objects, concerns, ActiveRecord
+2. `rspec-testing` - Test structure, shared examples, factories, isolation
+3. `rubocop-patterns` - Linting rules, Rails-specific cops
+4. `rails-database` - Migrations, models, scopes, associations
+
+**Note:** Rails would be a standalone type (not inheriting from TypeScript) since Ruby uses different tooling.
+
+### Plugin Publishing
+
+Publish Claude Code skills, commands, and agents as installable plugins via the Claude Code marketplace system.
+
+**Current Plugin Ecosystem:**
+- Official plugins: `claude-plugins-official` (typescript-lsp, code-review, playwright)
+- Community registry: [claude-plugins.dev](https://claude-plugins.dev/)
+
+**Lisa Components That Could Become Plugins:**
+- `coding-philosophy` skill - Teachable immutability and function structure patterns
+- `prompt-complexity-scorer` skill - Request complexity evaluation
+- `jsdoc-best-practices` skill - Documentation standards
+- `project:*` commands - Implementation workflows
+- Custom agents (skill-evaluator, codebase-analyzer)
+
+**Value:**
+- **À La Carte Adoption**: Teams install only relevant governance patterns
+- **Automatic Updates**: Plugin updates flow without re-running Lisa CLI
+- **Community Contributions**: Accept PRs for stack-specific patterns (Django, FastAPI, etc.)
+- **Ecosystem Discovery**: Listed on claude-plugins.dev for broader reach
+- **Mix-and-Match**: Combine Lisa's `coding-philosophy` with other teams' specialized plugins
+
+**Implementation Path:**
+1. Extract skills as standalone plugins with `.claude-plugin/plugin.json` manifests
+2. Create `lisa-governance-plugins` marketplace repository
+3. List on claude-plugins.dev community registry
+4. Provide marketplace.json for organizations to self-host
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details

package/all/copy-overwrite/.claude/README.md

@@ -43,7 +43,6 @@ The `enabledPlugins` section in `settings.json` references Claude Code plugins.
 |--------|-------------|--------------|
 | `claude-plugins-official` | Official Anthropic plugins | Built-in, no registration needed |
 | `cc-marketplace` | Community marketplace | Available at [Claude Code Marketplace](https://marketplace.claude.ai) |
-| `beads-marketplace` | Beads project plugins | See [Beads Documentation](https://beads.dev) |
 
 ### Enabled Plugins
 
@@ -53,7 +52,6 @@ The `enabledPlugins` section in `settings.json` references Claude Code plugins.
 | `safety-net` | `cc-marketplace` | Backup and safety features |
 | `code-simplifier` | `claude-plugins-official` | Code complexity reduction suggestions |
 | `code-review` | `claude-plugins-official` | Automated code review capabilities |
-| `beads` | `beads-marketplace` | Beads project integration |
 | `playwright` | `claude-plugins-official` | Playwright test integration |
 
 ### Installing Plugins
@@ -85,7 +83,7 @@ Create `settings.local.json` to override settings for your local environment:
     "PostToolUse": []
   },
   "enabledPlugins": {
-    "beads@beads-marketplace": false
+    "playwright": false
   }
 }
 ```