Skip to content
Back to search

lisa

MarketplaceWorks with Claude CodeGitHub

Lisa plans. Ralph does. Interactive specification interview workflow for Claude Code that conducts in-depth feature interviews and generates comprehensive specs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blencorp--lisa/badge.svg)](/listings/blencorp--lisa)

HTML

<a href="/listings/blencorp--lisa"><img src="/api/listings/blencorp--lisa/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code Plugin

# Add the marketplace
/plugin marketplace add blencorp/lisa

# Install the plugin
/plugin install lisa

Standalone CLI

The CLI works with multiple AI providers. Run it directly with npx:

npx @blen/lisa "user authentication"

**Prerequisites:** At least one AI CLI tool must be installed:

| Provider | CLI Command | Installation | |----------|-------------|--------------| | Claude Code | `claude` | [anthropic.com](https://anthropic.com) | | OpenCode | `opencode` | [opencode.dev](https://opencode.dev) | | Cursor | `cursor` or `agent` | [cursor.sh](https://cursor.sh) | | Codex | `codex` | [codex.dev](https://codex.dev) | | GitHub Copilot | `gh` with Copilot extension | [github.com/copilot](https://github.com/copilot) |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "lisa",
  3. "owner": {
  4. "name": "BLEN, Inc",
  5. "email": "engineering@blencorp.com"
  6. },
  7. "metadata": {
  8. "description": "Interactive specification interview workflow for Claude Code"
  9. },
  10. "plugins": [
  11. {
  12. "name": "lisa",
  13. "source": "./",
  14. "description": "Interactive specification interview workflow that conducts in-depth feature interviews using AskUserQuestion and generates comprehensive specs. Lisa plans. Ralph does.",
  15. "version": "1.2.1",
  16. "author": {
  17. "name": "BLEN Starter Kit"
  18. }
  19. }
  20. ]
  21. }
README.md · README · 580 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <img src="lisa-banner.png" alt="Lisa Logo" width="1000" />
  2. # Lisa
  3. **Lisa plans. Ralph does.**
  4. Interactive 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.
  5. ## Table of Contents
  6. - [Overview](#overview)
  7. - [Installation](#installation)
  8. - [Claude Code Plugin](#claude-code-plugin)
  9. - [Standalone CLI](#standalone-cli)
  10. - [Quick Start](#quick-start)
  11. - [Plugin Commands](#plugin-commands)
  12. - [CLI Usage](#cli-usage)
  13. - [Output Files](#output-files)
  14. - [Interview Process](#interview-process)
  15. - [First Principles Mode](#first-principles-mode)
  16. - [Configuration](#configuration)
  17. - [Programmatic Usage](#programmatic-usage)
  18. - [Complete Workflow: Lisa + Ralph](#complete-workflow-lisa--ralph)
  19. - [Development](#development)
  20. - [License](#license)
  21. ## Overview
  22. Based on the technique described by [@trq212](https://twitter.com/trq212):
  23. > 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.
  24. Lisa automates this workflow by:
  25. - Conducting structured interviews about your feature
  26. - Generating comprehensive PRDs in Markdown and JSON formats
  27. - Supporting resume of interrupted sessions
  28. - Optionally challenging assumptions with first-principles questioning
  29. ## Installation
  30. ### Claude Code Plugin
  31. ```bash
  32. # Add the marketplace
  33. /plugin marketplace add blencorp/lisa
  34. # Install the plugin
  35. /plugin install lisa
  36. ```
  37. ### Standalone CLI
  38. The CLI works with multiple AI providers. Run it directly with npx:
  39. ```bash
  40. npx @blen/lisa "user authentication"
  41. ```
  42. **Prerequisites:** At least one AI CLI tool must be installed:
  43. | Provider | CLI Command | Installation |
  44. |----------|-------------|--------------|
  45. | Claude Code | `claude` | [anthropic.com](https://anthropic.com) |
  46. | OpenCode | `opencode` | [opencode.dev](https://opencode.dev) |
  47. | Cursor | `cursor` or `agent` | [cursor.sh](https://cursor.sh) |
  48. | Codex | `codex` | [codex.dev](https://codex.dev) |
  49. | GitHub Copilot | `gh` with Copilot extension | [github.com/copilot](https://github.com/copilot) |
  50. ## Quick Start
  51. **Plugin (Claude Code):**
  52. ```bash
  53. /lisa:plan "user authentication"
  54. ```
  55. **CLI:**
  56. ```bash
  57. npx @blen/lisa "user authentication"
  58. ```
  59. ## Plugin Commands
  60. ### `/lisa:plan <FEATURE_NAME> [OPTIONS]`
  61. Start a specification interview for a feature.
  62. **Arguments:**
  63. - `FEATURE_NAME` (required) - Name of the feature to spec out
  64. **Options:**
  65. | Option | Description | Default |
  66. |--------|-------------|---------|
  67. | `--context <file>` | Initial context file (PRD, requirements, etc.) | none |
  68. | `--output-dir <dir>` | Output directory for generated specs | `docs/specs` |
  69. | `--max-questions <n>` | Maximum question rounds (0 = unlimited) | `0` |
  70. | `--first-principles` | Challenge assumptions before detailed spec gathering | `false` |
  71. | `-h, --help` | Show help | - |
  72. **Examples:**
  73. ```bash
  74. # Basic interview
  75. /lisa:plan "user authentication"
  76. # With existing context
  77. /lisa:plan "payment processing" --context docs/PRD.md
  78. # Custom output location
  79. /lisa:plan "search feature" --output-dir specs/features
  80. # Limit to 15 questions
  81. /lisa:plan "caching layer" --max-questions 15
  82. # Challenge assumptions first
  83. /lisa:plan "new dashboard" --first-principles
  84. # Combined options
  85. /lisa:plan "api gateway" --context docs/arch.md --first-principles --max-questions 20
  86. ```
  87. ### `/lisa:resume`
  88. Resume an interrupted specification interview.
  89. ```bash
  90. /lisa:resume
  91. ```
  92. If you have interviews that were interrupted (session ended mid-interview), this command will:
  93. 1. List all in-progress interviews with feature names and timestamps
  94. 2. Let you select which interview to resume
  95. 3. Continue the interview from where you left off
  96. ### `/lisa:cleanup`
  97. Clean up all Lisa interview state files.
  98. ```bash
  99. /lisa:cleanup
  100. ```
  101. Removes all interview state files from `.claude/lisa-*.md`. Use this to:
  102. - Abandon all in-progress interviews
  103. - Reset Lisa to a clean state
  104. Note: This does NOT delete completed specs in `docs/specs/`.
  105. ### `/lisa:help`
  106. Display help documentation about the Lisa workflow.
  107. ## CLI Usage
  108. ### Basic Usage
  109. ```bash
  110. npx @blen/lisa "user authentication system"
  111. ```
  112. ### Command Reference
  113. ```
  114. Usage: npx @blen/lisa [options] [feature]
  115. Arguments:
  116. feature Feature description to plan
  117. Options:
  118. -v, --version Display the current version
  119. -r, --resume Resume a previously interrupted interview
  120. -f, --first-principles Begin with foundational questions
  121. -c, --context <files...> Reference documents to include
  122. -p, --provider <name> AI provider: claude, opencode, cursor, codex, copilot
  123. -h, --help Display help
  124. ```
  125. ### Examples
  126. ```bash
  127. # With AI provider selection
  128. npx @blen/lisa "feature description" --provider claude
  129. npx @blen/lisa "feature description" --provider opencode
  130. npx @blen/lisa "feature description" --provider cursor
  131. # With context files
  132. npx @blen/lisa "feature description" --context docs/spec.md
  133. npx @blen/lisa "feature description" --context docs/spec.md docs/api.md
  134. # First principles mode
  135. npx @blen/lisa "feature description" --first-principles
  136. # Resume an interrupted interview
  137. npx @blen/lisa --resume
  138. ```
  139. ## Output Files
  140. ### Plugin Output
  141. The plugin generates three files when the interview is finalized:
  142. | File | Location | Description |
  143. |------|----------|-------------|
  144. | Markdown PRD | `{output-dir}/{feature-slug}.md` | Human-readable specification |
  145. | Structured JSON | `{output-dir}/{feature-slug}.json` | Machine-readable spec for tooling |
  146. | Progress File | `{output-dir}/{feature-slug}-progress.txt` | Empty file for Ralph to track learnings |
  147. **Example:** For `/lisa:plan "user authentication"`:
  148. - `docs/specs/user-authentication.md`
  149. - `docs/specs/user-authentication.json`
  150. - `docs/specs/user-authentication-progress.txt`
  151. ### CLI Output
  152. The CLI generates PRD files in the `./lisa/` directory:
  153. | File | Description |
  154. |------|-------------|
  155. | `./lisa/{feature-slug}.md` | Markdown PRD with overview, user stories, and technical notes |
  156. | `./lisa/{feature-slug}.json` | JSON PRD for programmatic use |
  157. ### JSON Structure
  158. The JSON output follows the [snarktank/ralph](https://github.com/snarktank/ralph) format:
  159. ```json
  160. {
  161. "project": "user-authentication",
  162. "branchName": "ralph/user-authentication",
  163. "description": "User authentication with email/password and OAuth",
  164. "userStories": [
  165. {
  166. "id": "US-001",
  167. "category": "setup",
  168. "title": "Database schema for users",
  169. "description": "As a developer, I want user tables created so that I can store credentials",
  170. "acceptanceCriteria": [
  171. "Migration creates users table with id, email, password_hash columns",
  172. "Unique constraint on email column",
  173. "npm run migrate completes without errors"
  174. ],
  175. "passes": false,
  176. "notes": ""
  177. }
  178. ]
  179. }
  180. ```
  181. **Category values:**
  182. - `setup` - Initial setup, configuration, scaffolding
  183. - `core` - Core feature functionality
  184. - `integration` - Connecting with other systems
  185. - `polish` - UI refinements, error handling, edge cases
  186. ## Interview Process
  187. ### How It Works
  188. 1. **Initialization**: Creates state files to track interview progress
  189. 2. **Interview Loop**:
  190. - AI asks probing questions using interactive prompts
  191. - Interview continues until you say "done" or "finalize"
  192. - Draft spec updated every 2-3 questions
  193. - Questions adapt based on your answers
  194. - If interrupted, use resume to continue
  195. 3. **Completion Detection**: When you say "done", "finalize", "finished", "that's all", "complete", or "wrap up"
  196. 4. **Finalization**: Generates all output files
  197. ### Interview Coverage
  198. The interview systematically covers:
  199. **Scope Definition**
  200. - What is explicitly OUT of scope?
  201. - MVP vs full vision boundaries
  202. - Related features to avoid touching
  203. **User Stories**
  204. - Discrete stories completable in one coding session
  205. - Verifiable acceptance criteria (not vague)
  206. - Good: "API returns 200 for valid input", "Response < 200ms"
  207. - Bad: "Works correctly", "Is fast", "Handles errors"
  208. **Technical Implementation**
  209. - Data models and storage
  210. - API design (endpoints, methods, auth)
  211. - Integration with existing systems
  212. - Error handling and edge cases
  213. **User Experience**
  214. - User flows and journeys
  215. - Edge cases and error states
  216. - Accessibility considerations
  217. **Trade-offs**
  218. - Performance requirements
  219. - Security considerations
  220. - Scalability expectations
  221. **Implementation Phases**
  222. - 2-4 incremental phases
  223. - Verification command for each phase
  224. - Minimum viable first phase
  225. ## First Principles Mode
  226. Use `--first-principles` to challenge assumptions before diving into details:
  227. **Plugin:**
  228. ```bash
  229. /lisa:plan "new feature" --first-principles
  230. ```
  231. **CLI:**
  232. ```bash
  233. npx @blen/lisa "new feature" --first-principles
  234. ```
  235. **Phase 1 - Challenge the Approach (3-5 questions):**
  236. - "What specific problem have you observed that led to this idea?"
  237. - "What happens if we don't build this at all?"
  238. - "What's the absolute simplest thing that might solve this?"
  239. - "What would have to be true for this to be the wrong approach?"
  240. - "Is there an existing solution we could use instead?"
  241. **Phase 2 - Detailed Spec:** Only proceeds after validating the approach is sound.
  242. ## Configuration
  243. ### CLI Configuration
  244. The CLI stores configuration in `./lisa/config.yaml`:
  245. ```yaml
  246. # Lisa CLI Configuration
  247. # Default AI provider (claude, opencode, cursor, codex, copilot)
  248. defaultProvider: claude
  249. # Output directory for generated PRDs
  250. outputDirectory: ./lisa
  251. ```
  252. Interview progress is saved to `./lisa/state.yaml`, allowing you to:
  253. - Resume interrupted interviews with `npx @blen/lisa --resume`
  254. - Recover from network errors or crashes
  255. - Continue multi-session planning work
  256. State is automatically cleared after successful PRD generation.
  257. ### Plugin Runtime Files
  258. During a plugin interview:
  259. | File | Purpose |
  260. |------|---------|
  261. | `.claude/lisa-{slug}.md` | Interview state (iteration count, paths, settings) |
  262. | `.claude/lisa-draft.md` | Running draft spec updated throughout |
  263. ## Programmatic Usage
  264. The CLI can also be used as a library:
  265. ```typescript
  266. import { runInterview, exploreCodebase, generateMarkdown } from '@blen/lisa';
  267. // Explore codebase
  268. const exploration = await exploreCodebase('/path/to/project');
  269. console.log(exploration.summary);
  270. // Generate PRD
  271. const prd = {
  272. overview: 'Feature overview...',
  273. userStories: [...],
  274. technicalNotes: '...'
  275. };
  276. const markdown = generateMarkdown(prd, 'feature-slug');
  277. ```
  278. ### Supported File Types for Context
  279. Lisa supports the following file types for `--context`:
  280. - **Markdown**: `.md`, `.markdown`
  281. - **Text**: `.txt`, `.text`
  282. - **Code**: `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.rb`, `.go`, `.rs`, `.java`
  283. - **Config**: `.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.conf`
  284. - **Web**: `.html`, `.css`, `.scss`, `.less`
  285. - **Other**: `.xml`, `.sql`, `.graphql`, `.gql`, `.sh`, `.bash`, `.zsh`
  286. ## Complete Workflow: Lisa + Ralph
  287. ```
  288. +------------------+ +------------------+
  289. | Lisa Plans | --> | Ralph Does |
  290. | | | |
  291. | /lisa:plan | | /ralph-loop |
  292. | "my feature" | | |
  293. +------------------+ +------------------+
  294. | |
  295. v v
  296. +-----------+ +-----------+
  297. | .md spec | | Working |
  298. | .json | | Code |
  299. | progress | | |
  300. +-----------+ +-----------+
  301. ```
  302. 1. **Lisa plans** - Generate comprehensive spec:
  303. ```bash
  304. /lisa:plan "my feature"
  305. # or
  306. npx @blen/lisa "my feature"
  307. ```
  308. 2. **Ralph does** - Implement iteratively:
  309. ```bash
  310. /ralph-loop
  311. ```
  312. The generated spec includes a pre-formatted Ralph Loop command with phases and verification steps.
  313. Use with [ralph-loop](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop) for a complete planning-to-implementation workflow.
  314. ## Development
  315. ### Plugin Development
  316. To develop and test the plugin locally:
  317. ```bash
  318. # Run Claude Code with the plugin loaded from local directory
  319. cc --plugin-dir /path/to/lisa
  320. # Example: if you cloned the repo to ~/projects/lisa
  321. cc --plugin-dir ~/projects/lisa
  322. ```
  323. ### Plugin Structure
  324. ```
  325. lisa/
  326. ├── .claude-plugin/
  327. │ └── plugin.json # Plugin metadata (name, version, author)
  328. ├── commands/
  329. │ ├── plan.md # Main command (/lisa:plan)
  330. │ ├── resume.md # Resume interrupted interviews (/lisa:resume)
  331. │ ├── cleanup.md # Clean up state files (/lisa:cleanup)
  332. │ └── help.md # Help documentation (/lisa:help)
  333. ├── hooks/
  334. │ └── hooks.json # Hook configuration (minimal)
  335. ├── scripts/
  336. │ └── setup-lisa.sh # Interview initialization
  337. └── README.md
  338. ```
  339. ### CLI Development
  340. #### Prerequisites
  341. - Node.js >= 18.0.0
  342. - npm
  343. #### Setup
  344. ```bash
  345. # Clone the repository
  346. git clone https://github.com/blencorp/lisa.git
  347. cd lisa/cli
  348. # Install dependencies
  349. npm install
  350. ```
  351. #### Running Locally
  352. During development, use `npm run dev` to run the CLI directly without building:
  353. ```bash
  354. # Run CLI with a feature description
  355. npm run dev "user authentication system"
  356. # With options
  357. npm run dev "feature name" -- --provider claude --first-principles
  358. # Resume an interrupted session
  359. npm run dev -- --resume
  360. # Show help
  361. npm run dev -- --help
  362. ```
  363. Note: Use `--` before CLI flags to pass them through npm to the script.
  364. #### Building
  365. ```bash
  366. # Compile TypeScript to JavaScript
  367. npm run build
  368. # Output is written to ./dist/
  369. ```
  370. #### Type Checking
  371. ```bash
  372. npm run typecheck
  373. ```
  374. #### Linting
  375. ```bash
  376. # Check for lint errors
  377. npm run lint
  378. # Auto-fix lint errors
  379. npm run lint:fix
  380. ```
  381. ### Testing
  382. The CLI uses [Vitest](https://vitest.dev/) as its test framework.
  383. ```bash
  384. # Run all tests once
  385. npm test
  386. # Run tests in watch mode
  387. npm run test:watch
  388. # Run a specific test file
  389. npm test src/core/prd.test.ts
  390. # Run tests with coverage
  391. npm test -- --coverage
  392. ```
  393. #### Test Structure
  394. | Type | Location | Description |
  395. |------|----------|-------------|
  396. | Unit | `src/**/*.test.ts` | Tests for individual modules |
  397. | Integration | `src/integration/` | Tests for interview flow with mocked providers |
  398. | E2E | `src/e2e/` | Tests against real AI CLI providers |
  399. | Snapshot | `src/core/prd.snapshot.test.ts` | Validates PRD output formats |
  400. ### CLI Project Structure
  401. ```
  402. cli/
  403. ├── src/
  404. │ ├── index.ts # Public API exports
  405. │ ├── cli/ # CLI interface (Commander.js, Inquirer)
  406. │ ├── core/ # Core logic (orchestrator, state, PRD generation)
  407. │ ├── providers/ # AI provider implementations
  408. │ └── utils/ # Utility functions
  409. ├── dist/ # Compiled output
  410. ├── package.json
  411. ├── tsconfig.json
  412. ├── vitest.config.ts
  413. └── README.md
  414. ```
  415. ## License
  416. MIT
  417. ---
  418. **Version:** 1.2.0 (Plugin) | 0.1.0 (CLI)
  419. **Author:** BLEN Engineering Team
  420. Built with love by [BLEN, Inc](https://www.blencorp.com).
  421. ### About BLEN
  422. BLEN, 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.