{
  "markdown": "<img src=\"lisa-banner.png\" alt=\"Lisa Logo\" width=\"1000\" />\n\n# Lisa\n\n**Lisa plans. Ralph does.**\n\nInteractive specification interview workflow that conducts in-depth feature interviews and generates comprehensive specs. Available as both a Claude Code plugin and a standalone CLI that works with multiple AI providers.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n  - [Claude Code Plugin](#claude-code-plugin)\n  - [Standalone CLI](#standalone-cli)\n- [Quick Start](#quick-start)\n- [Plugin Commands](#plugin-commands)\n- [CLI Usage](#cli-usage)\n- [Output Files](#output-files)\n- [Interview Process](#interview-process)\n- [First Principles Mode](#first-principles-mode)\n- [Configuration](#configuration)\n- [Programmatic Usage](#programmatic-usage)\n- [Complete Workflow: Lisa + Ralph](#complete-workflow-lisa--ralph)\n- [Development](#development)\n- [License](#license)\n\n## Overview\n\nBased on the technique described by [@trq212](https://twitter.com/trq212):\n\n> My favorite way to use Claude Code to build large features is spec based. Start with a minimal spec or prompt and ask Claude to interview you using the AskUserQuestion tool about literally anything: technical implementation, UI & UX, concerns, tradeoffs, etc. Then make a new session to execute the spec.\n\nLisa automates this workflow by:\n- Conducting structured interviews about your feature\n- Generating comprehensive PRDs in Markdown and JSON formats\n- Supporting resume of interrupted sessions\n- Optionally challenging assumptions with first-principles questioning\n\n## Installation\n\n### Claude Code Plugin\n\n```bash\n# Add the marketplace\n/plugin marketplace add blencorp/lisa\n\n# Install the plugin\n/plugin install lisa\n```\n\n### Standalone CLI\n\nThe CLI works with multiple AI providers. Run it directly with npx:\n\n```bash\nnpx @blen/lisa \"user authentication\"\n```\n\n**Prerequisites:** At least one AI CLI tool must be installed:\n\n| Provider | CLI Command | Installation |\n|----------|-------------|--------------|\n| Claude Code | `claude` | [anthropic.com](https://anthropic.com) |\n| OpenCode | `opencode` | [opencode.dev](https://opencode.dev) |\n| Cursor | `cursor` or `agent` | [cursor.sh](https://cursor.sh) |\n| Codex | `codex` | [codex.dev](https://codex.dev) |\n| GitHub Copilot | `gh` with Copilot extension | [github.com/copilot](https://github.com/copilot) |\n\n## Quick Start\n\n**Plugin (Claude Code):**\n```bash\n/lisa:plan \"user authentication\"\n```\n\n**CLI:**\n```bash\nnpx @blen/lisa \"user authentication\"\n```\n\n## Plugin Commands\n\n### `/lisa:plan <FEATURE_NAME> [OPTIONS]`\n\nStart a specification interview for a feature.\n\n**Arguments:**\n- `FEATURE_NAME` (required) - Name of the feature to spec out\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--context <file>` | Initial context file (PRD, requirements, etc.) | none |\n| `--output-dir <dir>` | Output directory for generated specs | `docs/specs` |\n| `--max-questions <n>` | Maximum question rounds (0 = unlimited) | `0` |\n| `--first-principles` | Challenge assumptions before detailed spec gathering | `false` |\n| `-h, --help` | Show help | - |\n\n**Examples:**\n\n```bash\n# Basic interview\n/lisa:plan \"user authentication\"\n\n# With existing context\n/lisa:plan \"payment processing\" --context docs/PRD.md\n\n# Custom output location\n/lisa:plan \"search feature\" --output-dir specs/features\n\n# Limit to 15 questions\n/lisa:plan \"caching layer\" --max-questions 15\n\n# Challenge assumptions first\n/lisa:plan \"new dashboard\" --first-principles\n\n# Combined options\n/lisa:plan \"api gateway\" --context docs/arch.md --first-principles --max-questions 20\n```\n\n### `/lisa:resume`\n\nResume an interrupted specification interview.\n\n```bash\n/lisa:resume\n```\n\nIf you have interviews that were interrupted (session ended mid-interview), this command will:\n1. List all in-progress interviews with feature names and timestamps\n2. Let you select which interview to resume\n3. Continue the interview from where you left off\n\n### `/lisa:cleanup`\n\nClean up all Lisa interview state files.\n\n```bash\n/lisa:cleanup\n```\n\nRemoves all interview state files from `.claude/lisa-*.md`. Use this to:\n- Abandon all in-progress interviews\n- Reset Lisa to a clean state\n\nNote: This does NOT delete completed specs in `docs/specs/`.\n\n### `/lisa:help`\n\nDisplay help documentation about the Lisa workflow.\n\n## CLI Usage\n\n### Basic Usage\n\n```bash\nnpx @blen/lisa \"user authentication system\"\n```\n\n### Command Reference\n\n```\nUsage: npx @blen/lisa [options] [feature]\n\nArguments:\n  feature                          Feature description to plan\n\nOptions:\n  -v, --version                    Display the current version\n  -r, --resume                     Resume a previously interrupted interview\n  -f, --first-principles           Begin with foundational questions\n  -c, --context <files...>         Reference documents to include\n  -p, --provider <name>            AI provider: claude, opencode, cursor, codex, copilot\n  -h, --help                       Display help\n```\n\n### Examples\n\n```bash\n# With AI provider selection\nnpx @blen/lisa \"feature description\" --provider claude\nnpx @blen/lisa \"feature description\" --provider opencode\nnpx @blen/lisa \"feature description\" --provider cursor\n\n# With context files\nnpx @blen/lisa \"feature description\" --context docs/spec.md\nnpx @blen/lisa \"feature description\" --context docs/spec.md docs/api.md\n\n# First principles mode\nnpx @blen/lisa \"feature description\" --first-principles\n\n# Resume an interrupted interview\nnpx @blen/lisa --resume\n```\n\n## Output Files\n\n### Plugin Output\n\nThe plugin generates three files when the interview is finalized:\n\n| File | Location | Description |\n|------|----------|-------------|\n| Markdown PRD | `{output-dir}/{feature-slug}.md` | Human-readable specification |\n| Structured JSON | `{output-dir}/{feature-slug}.json` | Machine-readable spec for tooling |\n| Progress File | `{output-dir}/{feature-slug}-progress.txt` | Empty file for Ralph to track learnings |\n\n**Example:** For `/lisa:plan \"user authentication\"`:\n- `docs/specs/user-authentication.md`\n- `docs/specs/user-authentication.json`\n- `docs/specs/user-authentication-progress.txt`\n\n### CLI Output\n\nThe CLI generates PRD files in the `./lisa/` directory:\n\n| File | Description |\n|------|-------------|\n| `./lisa/{feature-slug}.md` | Markdown PRD with overview, user stories, and technical notes |\n| `./lisa/{feature-slug}.json` | JSON PRD for programmatic use |\n\n### JSON Structure\n\nThe JSON output follows the [snarktank/ralph](https://github.com/snarktank/ralph) format:\n\n```json\n{\n  \"project\": \"user-authentication\",\n  \"branchName\": \"ralph/user-authentication\",\n  \"description\": \"User authentication with email/password and OAuth\",\n  \"userStories\": [\n    {\n      \"id\": \"US-001\",\n      \"category\": \"setup\",\n      \"title\": \"Database schema for users\",\n      \"description\": \"As a developer, I want user tables created so that I can store credentials\",\n      \"acceptanceCriteria\": [\n        \"Migration creates users table with id, email, password_hash columns\",\n        \"Unique constraint on email column\",\n        \"npm run migrate completes without errors\"\n      ],\n      \"passes\": false,\n      \"notes\": \"\"\n    }\n  ]\n}\n```\n\n**Category values:**\n- `setup` - Initial setup, configuration, scaffolding\n- `core` - Core feature functionality\n- `integration` - Connecting with other systems\n- `polish` - UI refinements, error handling, edge cases\n\n## Interview Process\n\n### How It Works\n\n1. **Initialization**: Creates state files to track interview progress\n\n2. **Interview Loop**:\n   - AI asks probing questions using interactive prompts\n   - Interview continues until you say \"done\" or \"finalize\"\n   - Draft spec updated every 2-3 questions\n   - Questions adapt based on your answers\n   - If interrupted, use resume to continue\n\n3. **Completion Detection**: When you say \"done\", \"finalize\", \"finished\", \"that's all\", \"complete\", or \"wrap up\"\n\n4. **Finalization**: Generates all output files\n\n### Interview Coverage\n\nThe interview systematically covers:\n\n**Scope Definition**\n- What is explicitly OUT of scope?\n- MVP vs full vision boundaries\n- Related features to avoid touching\n\n**User Stories**\n- Discrete stories completable in one coding session\n- Verifiable acceptance criteria (not vague)\n  - Good: \"API returns 200 for valid input\", \"Response < 200ms\"\n  - Bad: \"Works correctly\", \"Is fast\", \"Handles errors\"\n\n**Technical Implementation**\n- Data models and storage\n- API design (endpoints, methods, auth)\n- Integration with existing systems\n- Error handling and edge cases\n\n**User Experience**\n- User flows and journeys\n- Edge cases and error states\n- Accessibility considerations\n\n**Trade-offs**\n- Performance requirements\n- Security considerations\n- Scalability expectations\n\n**Implementation Phases**\n- 2-4 incremental phases\n- Verification command for each phase\n- Minimum viable first phase\n\n## First Principles Mode\n\nUse `--first-principles` to challenge assumptions before diving into details:\n\n**Plugin:**\n```bash\n/lisa:plan \"new feature\" --first-principles\n```\n\n**CLI:**\n```bash\nnpx @blen/lisa \"new feature\" --first-principles\n```\n\n**Phase 1 - Challenge the Approach (3-5 questions):**\n- \"What specific problem have you observed that led to this idea?\"\n- \"What happens if we don't build this at all?\"\n- \"What's the absolute simplest thing that might solve this?\"\n- \"What would have to be true for this to be the wrong approach?\"\n- \"Is there an existing solution we could use instead?\"\n\n**Phase 2 - Detailed Spec:** Only proceeds after validating the approach is sound.\n\n## Configuration\n\n### CLI Configuration\n\nThe CLI stores configuration in `./lisa/config.yaml`:\n\n```yaml\n# Lisa CLI Configuration\n# Default AI provider (claude, opencode, cursor, codex, copilot)\ndefaultProvider: claude\n\n# Output directory for generated PRDs\noutputDirectory: ./lisa\n```\n\nInterview progress is saved to `./lisa/state.yaml`, allowing you to:\n- Resume interrupted interviews with `npx @blen/lisa --resume`\n- Recover from network errors or crashes\n- Continue multi-session planning work\n\nState is automatically cleared after successful PRD generation.\n\n### Plugin Runtime Files\n\nDuring a plugin interview:\n\n| File | Purpose |\n|------|---------|\n| `.claude/lisa-{slug}.md` | Interview state (iteration count, paths, settings) |\n| `.claude/lisa-draft.md` | Running draft spec updated throughout |\n\n## Programmatic Usage\n\nThe CLI can also be used as a library:\n\n```typescript\nimport { runInterview, exploreCodebase, generateMarkdown } from '@blen/lisa';\n\n// Explore codebase\nconst exploration = await exploreCodebase('/path/to/project');\nconsole.log(exploration.summary);\n\n// Generate PRD\nconst prd = {\n  overview: 'Feature overview...',\n  userStories: [...],\n  technicalNotes: '...'\n};\nconst markdown = generateMarkdown(prd, 'feature-slug');\n```\n\n### Supported File Types for Context\n\nLisa supports the following file types for `--context`:\n\n- **Markdown**: `.md`, `.markdown`\n- **Text**: `.txt`, `.text`\n- **Code**: `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.rb`, `.go`, `.rs`, `.java`\n- **Config**: `.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.conf`\n- **Web**: `.html`, `.css`, `.scss`, `.less`\n- **Other**: `.xml`, `.sql`, `.graphql`, `.gql`, `.sh`, `.bash`, `.zsh`\n\n## Complete Workflow: Lisa + Ralph\n\n```\n+------------------+     +------------------+\n|   Lisa Plans     | --> |   Ralph Does     |\n|                  |     |                  |\n| /lisa:plan       |     | /ralph-loop      |\n| \"my feature\"     |     |                  |\n+------------------+     +------------------+\n        |                       |\n        v                       v\n  +-----------+          +-----------+\n  | .md spec  |          | Working   |\n  | .json     |          | Code      |\n  | progress  |          |           |\n  +-----------+          +-----------+\n```\n\n1. **Lisa plans** - Generate comprehensive spec:\n   ```bash\n   /lisa:plan \"my feature\"\n   # or\n   npx @blen/lisa \"my feature\"\n   ```\n\n2. **Ralph does** - Implement iteratively:\n   ```bash\n   /ralph-loop\n   ```\n\nThe generated spec includes a pre-formatted Ralph Loop command with phases and verification steps.\n\nUse with [ralph-loop](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop) for a complete planning-to-implementation workflow.\n\n## Development\n\n### Plugin Development\n\nTo develop and test the plugin locally:\n\n```bash\n# Run Claude Code with the plugin loaded from local directory\ncc --plugin-dir /path/to/lisa\n\n# Example: if you cloned the repo to ~/projects/lisa\ncc --plugin-dir ~/projects/lisa\n```\n\n### Plugin Structure\n\n```\nlisa/\n├── .claude-plugin/\n│   └── plugin.json          # Plugin metadata (name, version, author)\n├── commands/\n│   ├── plan.md              # Main command (/lisa:plan)\n│   ├── resume.md            # Resume interrupted interviews (/lisa:resume)\n│   ├── cleanup.md           # Clean up state files (/lisa:cleanup)\n│   └── help.md              # Help documentation (/lisa:help)\n├── hooks/\n│   └── hooks.json           # Hook configuration (minimal)\n├── scripts/\n│   └── setup-lisa.sh        # Interview initialization\n└── README.md\n```\n\n### CLI Development\n\n#### Prerequisites\n\n- Node.js >= 18.0.0\n- npm\n\n#### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/blencorp/lisa.git\ncd lisa/cli\n\n# Install dependencies\nnpm install\n```\n\n#### Running Locally\n\nDuring development, use `npm run dev` to run the CLI directly without building:\n\n```bash\n# Run CLI with a feature description\nnpm run dev \"user authentication system\"\n\n# With options\nnpm run dev \"feature name\" -- --provider claude --first-principles\n\n# Resume an interrupted session\nnpm run dev -- --resume\n\n# Show help\nnpm run dev -- --help\n```\n\nNote: Use `--` before CLI flags to pass them through npm to the script.\n\n#### Building\n\n```bash\n# Compile TypeScript to JavaScript\nnpm run build\n\n# Output is written to ./dist/\n```\n\n#### Type Checking\n\n```bash\nnpm run typecheck\n```\n\n#### Linting\n\n```bash\n# Check for lint errors\nnpm run lint\n\n# Auto-fix lint errors\nnpm run lint:fix\n```\n\n### Testing\n\nThe CLI uses [Vitest](https://vitest.dev/) as its test framework.\n\n```bash\n# Run all tests once\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run a specific test file\nnpm test src/core/prd.test.ts\n\n# Run tests with coverage\nnpm test -- --coverage\n```\n\n#### Test Structure\n\n| Type | Location | Description |\n|------|----------|-------------|\n| Unit | `src/**/*.test.ts` | Tests for individual modules |\n| Integration | `src/integration/` | Tests for interview flow with mocked providers |\n| E2E | `src/e2e/` | Tests against real AI CLI providers |\n| Snapshot | `src/core/prd.snapshot.test.ts` | Validates PRD output formats |\n\n### CLI Project Structure\n\n```\ncli/\n├── src/\n│   ├── index.ts              # Public API exports\n│   ├── cli/                  # CLI interface (Commander.js, Inquirer)\n│   ├── core/                 # Core logic (orchestrator, state, PRD generation)\n│   ├── providers/            # AI provider implementations\n│   └── utils/                # Utility functions\n├── dist/                     # Compiled output\n├── package.json\n├── tsconfig.json\n├── vitest.config.ts\n└── README.md\n```\n\n## License\n\nMIT\n\n---\n\n**Version:** 1.2.0 (Plugin) | 0.1.0 (CLI)\n**Author:** BLEN Engineering Team\n\nBuilt with love by [BLEN, Inc](https://www.blencorp.com).\n\n### About BLEN\n\nBLEN, Inc is a digital services company that provides Emerging Technology (ML/AI, RPA), Digital Modernization (Legacy to Cloud), and Human-Centered Web/Mobile Design and Development.\n",
  "bytes": 15519,
  "sha": "d291d83795d43ed069f85ffbcd30fc4b5c853e8db1f902f211dd4df02a342660",
  "repo_slug": "blencorp/lisa",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_blencorp_lisa_lisa_421fd205/readme"
}