lisa

Lisa

Lisa plans. Ralph does.

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.

Table of Contents

• Overview
• Installation
  • Claude Code Plugin
  • Standalone CLI
• Quick Start
• Plugin Commands
• CLI Usage
• Output Files
• Interview Process
• First Principles Mode
• Configuration
• Programmatic Usage
• Complete Workflow: Lisa + Ralph
• Development
• License

Overview

Based on the technique described by @trq212:

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.

Lisa automates this workflow by:

• Conducting structured interviews about your feature
• Generating comprehensive PRDs in Markdown and JSON formats
• Supporting resume of interrupted sessions
• Optionally challenging assumptions with first-principles questioning

Installation

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
OpenCode	opencode	opencode.dev
Cursor	cursor or agent	cursor.sh
Codex	codex	codex.dev
GitHub Copilot	gh with Copilot extension	github.com/copilot

Quick Start

Plugin (Claude Code):

/lisa:plan "user authentication"

CLI:

npx @blen/lisa "user authentication"

Plugin Commands

/lisa:plan <FEATURE_NAME> [OPTIONS]

Start a specification interview for a feature.

Arguments:

• FEATURE_NAME (required) - Name of the feature to spec out

Options:

Option	Description	Default
--context <file>	Initial context file (PRD, requirements, etc.)	none
--output-dir <dir>	Output directory for generated specs	docs/specs
--max-questions <n>	Maximum question rounds (0 = unlimited)	0
--first-principles	Challenge assumptions before detailed spec gathering	false
-h, --help	Show help	-

Examples:

# Basic interview
/lisa:plan "user authentication"

# With existing context
/lisa:plan "payment processing" --context docs/PRD.md

# Custom output location
/lisa:plan "search feature" --output-dir specs/features

# Limit to 15 questions
/lisa:plan "caching layer" --max-questions 15

# Challenge assumptions first
/lisa:plan "new dashboard" --first-principles

# Combined options
/lisa:plan "api gateway" --context docs/arch.md --first-principles --max-questions 20

/lisa:resume

Resume an interrupted specification interview.

/lisa:resume

If you have interviews that were interrupted (session ended mid-interview), this command will:

1. List all in-progress interviews with feature names and timestamps
2. Let you select which interview to resume
3. Continue the interview from where you left off

/lisa:cleanup

Clean up all Lisa interview state files.

/lisa:cleanup

Removes all interview state files from .claude/lisa-*.md. Use this to:

• Abandon all in-progress interviews
• Reset Lisa to a clean state

Note: This does NOT delete completed specs in docs/specs/.

/lisa:help

Display help documentation about the Lisa workflow.

CLI Usage

Basic Usage

npx @blen/lisa "user authentication system"

Command Reference

Usage: npx @blen/lisa [options] [feature]

Arguments:
  feature                          Feature description to plan

Options:
  -v, --version                    Display the current version
  -r, --resume                     Resume a previously interrupted interview
  -f, --first-principles           Begin with foundational questions
  -c, --context <files...>         Reference documents to include
  -p, --provider <name>            AI provider: claude, opencode, cursor, codex, copilot
  -h, --help                       Display help

Examples

# With AI provider selection
npx @blen/lisa "feature description" --provider claude
npx @blen/lisa "feature description" --provider opencode
npx @blen/lisa "feature description" --provider cursor

# With context files
npx @blen/lisa "feature description" --context docs/spec.md
npx @blen/lisa "feature description" --context docs/spec.md docs/api.md

# First principles mode
npx @blen/lisa "feature description" --first-principles

# Resume an interrupted interview
npx @blen/lisa --resume

Output Files

Plugin Output

The plugin generates three files when the interview is finalized:

File	Location	Description
Markdown PRD	{output-dir}/{feature-slug}.md	Human-readable specification
Structured JSON	{output-dir}/{feature-slug}.json	Machine-readable spec for tooling
Progress File	{output-dir}/{feature-slug}-progress.txt	Empty file for Ralph to track learnings

Example: For /lisa:plan "user authentication":

• docs/specs/user-authentication.md
• docs/specs/user-authentication.json
• docs/specs/user-authentication-progress.txt

CLI Output

The CLI generates PRD files in the ./lisa/ directory:

File	Description
./lisa/{feature-slug}.md	Markdown PRD with overview, user stories, and technical notes
./lisa/{feature-slug}.json	JSON PRD for programmatic use

JSON Structure

The JSON output follows the snarktank/ralph format:

{
  "project": "user-authentication",
  "branchName": "ralph/user-authentication",
  "description": "User authentication with email/password and OAuth",
  "userStories": [
    {
      "id": "US-001",
      "category": "setup",
      "title": "Database schema for users",
      "description": "As a developer, I want user tables created so that I can store credentials",
      "acceptanceCriteria": [
        "Migration creates users table with id, email, password_hash columns",
        "Unique constraint on email column",
        "npm run migrate completes without errors"
      ],
      "passes": false,
      "notes": ""
    }
  ]
}

Category values:

• setup - Initial setup, configuration, scaffolding
• core - Core feature functionality
• integration - Connecting with other systems
• polish - UI refinements, error handling, edge cases

Interview Process

How It Works

1. Initialization: Creates state files to track interview progress

2. Interview Loop:

   • AI asks probing questions using interactive prompts
   • Interview continues until you say "done" or "finalize"
   • Draft spec updated every 2-3 questions
   • Questions adapt based on your answers
   • If interrupted, use resume to continue

3. Completion Detection: When you say "done", "finalize", "finished", "that's all", "complete", or "wrap up"

4. Finalization: Generates all output files

Interview Coverage

The interview systematically covers:

Scope Definition

• What is explicitly OUT of scope?
• MVP vs full vision boundaries
• Related features to avoid touching

User Stories

• Discrete stories completable in one coding session
• Verifiable acceptance criteria (not vague)
  • Good: "API returns 200 for valid input", "Response < 200ms"
  • Bad: "Works correctly", "Is fast", "Handles errors"

Technical Implementation

• Data models and storage
• API design (endpoints, methods, auth)
• Integration with existing systems
• Error handling and edge cases

User Experience

• User flows and journeys
• Edge cases and error states
• Accessibility considerations

Trade-offs

• Performance requirements
• Security considerations
• Scalability expectations

Implementation Phases

• 2-4 incremental phases
• Verification command for each phase
• Minimum viable first phase

First Principles Mode

Use --first-principles to challenge assumptions before diving into details:

Plugin:

/lisa:plan "new feature" --first-principles

CLI:

npx @blen/lisa "new feature" --first-principles

Phase 1 - Challenge the Approach (3-5 questions):

• "What specific problem have you observed that led to this idea?"
• "What happens if we don't build this at all?"
• "What's the absolute simplest thing that might solve this?"
• "What would have to be true for this to be the wrong approach?"
• "Is there an existing solution we could use instead?"

Phase 2 - Detailed Spec: Only proceeds after validating the approach is sound.

Configuration

CLI Configuration

The CLI stores configuration in ./lisa/config.yaml:

# Lisa CLI Configuration
# Default AI provider (claude, opencode, cursor, codex, copilot)
defaultProvider: claude

# Output directory for generated PRDs
outputDirectory: ./lisa

Interview progress is saved to ./lisa/state.yaml, allowing you to:

• Resume interrupted interviews with npx @blen/lisa --resume
• Recover from network errors or crashes
• Continue multi-session planning work

State is automatically cleared after successful PRD generation.

Plugin Runtime Files

During a plugin interview:

File	Purpose
.claude/lisa-{slug}.md	Interview state (iteration count, paths, settings)
.claude/lisa-draft.md	Running draft spec updated throughout

Programmatic Usage

The CLI can also be used as a library:

import { runInterview, exploreCodebase, generateMarkdown } from '@blen/lisa';

// Explore codebase
const exploration = await exploreCodebase('/path/to/project');
console.log(exploration.summary);

// Generate PRD
const prd = {
  overview: 'Feature overview...',
  userStories: [...],
  technicalNotes: '...'
};
const markdown = generateMarkdown(prd, 'feature-slug');

Supported File Types for Context

Lisa supports the following file types for --context:

• Markdown: .md, .markdown
• Text: .txt, .text
• Code: .ts, .tsx, .js, .jsx, .py, .rb, .go, .rs, .java
• Config: .json, .yaml, .yml, .toml, .ini, .conf
• Web: .html, .css, .scss, .less
• Other: .xml, .sql, .graphql, .gql, .sh, .bash, .zsh

Complete Workflow: Lisa + Ralph

+------------------+     +------------------+
|   Lisa Plans     | --> |   Ralph Does     |
|                  |     |                  |
| /lisa:plan       |     | /ralph-loop      |
| "my feature"     |     |                  |
+------------------+     +------------------+
        |                       |
        v                       v
  +-----------+          +-----------+
  | .md spec  |          | Working   |
  | .json     |          | Code      |
  | progress  |          |           |
  +-----------+          +-----------+

1. Lisa plans - Generate comprehensive spec:

   /lisa:plan "my feature"
   # or
   npx @blen/lisa "my feature"
   

2. Ralph does - Implement iteratively: