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

version
1.2.1
GitHub stars
121

Install

/plugin install lisa@lisa

Run it inside Claude Code after adding the marketplace with /plugin marketplace add blencorp/lisa.

Contents

Discovered from source

Commands 4

Lisa Cleanup Command

Remove all Lisa interview state files to reset the plugin state.

STEP 1: CHECK FOR STATE FILES

First, check what state files exist:

ls -la .claude/lisa-*.md 2>/dev/null || echo "NO_STATE_FILES"

STEP 2: HANDLE RESULTS

If NO state files exist:

Tell the user:

No Lisa state files found. Nothing to clean up.

Then STOP.

If state files exist:

List the files that will be deleted, then delete them:

rm .claude/lisa-*.md

Also clean up the draft file if it exists:

rm -f .claude/lisa-draft.md

Then confirm to the user:

Lisa cleanup complete. Deleted all interview state files.

To start a new interview, use:

/lisa:plan "your feature name"

IMPORTANT NOTES

  • This command only deletes state files in .claude/
  • It does NOT delete any completed specs in docs/specs/
  • Completed specifications are permanent and unaffected by cleanup
  • Use this when you want to abandon all in-progress interviews

Lisa Plan Help

Please explain the following to the user:

What is Lisa Plan?

Lisa plans. Ralph does.

Lisa Plan is an interactive specification gathering workflow that conducts in-depth feature interviews using the AskUserQuestion tool and generates comprehensive technical specifications. Use it with ralph-loop for a complete planning-to-implementation workflow.

Based on the technique described by @trq212: Start with a minimal spec, have Claude interview you about technical implementation, UI/UX, concerns, and trade-offs, then generate a complete specification.

Key Features:

  • Adaptive questioning based on responses
  • Non-obvious, in-depth questions covering technical, UX, and trade-off considerations
  • Continuous interview until you say "done" or "finalize"
  • Running draft maintained throughout
  • Final spec output in structured markdown format

Available Commands

/lisa:plan <FEATURE_NAME> [OPTIONS]

Start a specification interview for a feature.

Usage:

/lisa:plan "user authentication"
/lisa:plan "payment processing" --context docs/PRD.md
/lisa:plan "search feature" --output-dir specs/features --max-questions 20

Options:

  • --context <file> - Initial context file (PRD, requirements, etc.)
  • --output-dir <dir> - Output directory for specs (default: docs/specs)
  • --max-questions <n> - Maximum question rounds (default: unlimited)

/lisa:resume

Resume an interrupted specification interview.

Usage:

/lisa:resume

If you have interrupted interviews (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

If no interrupted interviews exist, it will suggest using /lisa:plan to start a new one.

/lisa:cleanup

Clean up all Lisa interview state files.

Usage:

/lisa:cleanup

This command removes all interview state files from .claude/lisa-*.md. Use this when you want to:

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

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

/lisa:help

Show this help message.

Interview Flow

  1. Initialization - Creates state file and draft spec
  2. Interview - Asks non-obvious questions via AskUserQuestion tool
  3. Draft Updates - Maintains running draft every 2-3 questions
  4. Finalization - When you say "done" or "finalize", writes final spec

Question Types

The interview covers:

  • Technical Implementation - Data models, APIs, auth, error handling, integration
  • User Experience - Flows, edge cases, accessibility, error states
  • Trade-offs - Performance, security, scalability, MVP scope, technical debt

Output

  • Draft (during interview): .claude/lisa-draft.md
  • Final spec: docs/specs/{feature-slug}.md

Example Session

You: /lisa:plan "file upload feature"
Claude: [Asks about file types, size limits, storage backend via AskUserQuestion]
You: [Answers]
Claude: [Asks about virus scanning, thumbnail generation]
You: [Answers]
Claude: [Asks about error handling, retry logic]
You: done
Claude: [Writes final spec to docs/specs/file-upload-feature.md]

Canceling an Interview

To cancel an active interview, delete the state file or use the cleanup command:

# Remove all Lisa state files
rm .claude/lisa-*.md

# Or use the cleanup command
/lisa:cleanup

Using the Spec

After the interview completes, use the spec in a new Claude session:

cat docs/specs/your-feature.md | claude
# Or: "Read docs/specs/your-feature.md and implement it"

Complete Workflow: Lisa + Ralph

  1. Lisa plans - Generate comprehensive spec: /lisa:plan "my feature"
  2. Ralph does - Implement iteratively: /ralph-loop

Lisa plans. Ralph does. Ship faster.

Lisa Plan Command

Execute the setup script to initialize the specification interview:

"${CLAUDE_PLUGIN_ROOT}/scripts/setup-lisa.sh" $ARGUMENTS

You are now conducting a comprehensive specification interview. Follow the instructions provided by the setup script exactly.

INTERVIEW PHASE RULES

  1. EVERY question must use AskUserQuestion - plain text questions won't work
  2. Ask NON-OBVIOUS questions (not "what should it do?" but "how should X handle Y?")
  3. Continue until user says "done" or "finalize"
  4. Update the draft spec file regularly using the Write tool

FINALIZATION CONSTRAINTS - CRITICAL

When the user says "done", "finalize", "finished", or similar:

ALLOWED ACTIONS (Read and Write ONLY):

  • Read any files needed to compile the final spec
  • Write the final spec to {output-dir}/{slug}.md
  • Write the JSON spec to {output-dir}/{slug}.json
  • Write the progress file to {output-dir}/{slug}-progress.txt
  • Delete the state file at .claude/lisa-{slug}.md using Write with empty content

FORBIDDEN ACTIONS (DO NOT USE):

  • NO Bash tool calls - do not run any commands
  • NO Edit tool calls - do not modify existing code
  • NO Task tool calls - do not launch subagents
  • NO implementation of any kind - you are ONLY writing spec documents

FINALIZATION SEQUENCE:

  1. Write the final markdown spec file
  2. Write the JSON spec file
  3. Write the progress file with all phases marked as [PENDING]
  4. Delete the state file (.claude/lisa-{slug}.md)
  5. Output SPEC COMPLETE
  6. STOP IMMEDIATELY - do not continue with any other actions

CRITICAL: SPEC COMPLETE MEANS STOP

After outputting SPEC COMPLETE, you MUST stop. Do not:

  • Offer to implement the feature
  • Suggest next steps for implementation
  • Make any code changes
  • Run any commands

The spec is the deliverable. Implementation is a separate task.

Lisa Resume Command

Resume an interrupted specification interview.

STEP 1: SCAN FOR INTERRUPTED INTERVIEWS

First, scan for all existing interview state files:

ls -la .claude/lisa-*.md 2>/dev/null || echo "NO_STATE_FILES"

STEP 2: HANDLE RESULTS

If NO state files exist:

Tell the user:

No interrupted interviews found.

To start a new interview, use:

/lisa:plan "your feature name"

Then STOP - do not continue.

If state files exist:

For each .claude/lisa-*.md file found, read the YAML frontmatter to extract:

  • feature_name - The human-readable feature name
  • started_at - When the interview was started

Then present the list to the user using AskUserQuestion with options like:

  • Option 1: "Feature Name A (started: 2026-01-15)"
  • Option 2: "Feature Name B (started: 2026-01-17)"
  • etc.

STEP 3: RESUME SELECTED INTERVIEW

Once the user selects an interview:

  1. Read the full state file content
  2. Read the draft spec file at .claude/lisa-draft.md if it exists
  3. The state file contains the full interview prompt after the YAML frontmatter
  4. Continue the interview from where it left off

Tell the user:

Resuming interview for: [FEATURE_NAME]

I'll review the draft spec and continue with the next question.

Then read the draft spec to understand what's already been gathered, and ask the next appropriate question using AskUserQuestion.

INTERVIEW RULES (same as /lisa:plan)

  1. EVERY question must use AskUserQuestion - plain text questions won't work
  2. Ask NON-OBVIOUS questions (not "what should it do?" but "how should X handle Y?")
  3. Continue until user says "done" or "finalize"
  4. Update the draft spec file regularly using the Write tool

FINALIZATION CONSTRAINTS - CRITICAL

When the user says "done", "finalize", "finished", or similar:

ALLOWED ACTIONS (Read and Write ONLY):

  • Read any files needed to compile the final spec
  • Write the final spec to {output-dir}/{slug}.md
  • Write the JSON spec to {output-dir}/{slug}.json
  • Write the progress file to {output-dir}/{slug}-progress.txt
  • Delete the state file at .claude/lisa-{slug}.md using Write with empty content

FORBIDDEN ACTIONS (DO NOT USE):

  • NO Bash tool calls - do not run any commands
  • NO Edit tool calls - do not modify existing code
  • NO Task tool calls - do not launch subagents
  • NO implementation of any kind - you are ONLY writing spec documents

FINALIZATION SEQUENCE:

  1. Write the final markdown spec file
  2. Write the JSON spec file
  3. Write the progress file with all phases marked as [PENDING]
  4. Delete the state file (.claude/lisa-{slug}.md)
  5. Output SPEC COMPLETE
  6. STOP IMMEDIATELY - do not continue with any other actions

CRITICAL: SPEC COMPLETE MEANS STOP

After outputting SPEC COMPLETE, you MUST stop. Do not:

  • Offer to implement the feature
  • Suggest next steps for implementation
  • Make any code changes
  • Run any commands

The spec is the deliverable. Implementation is a separate task.

Sponsors

Details

Marketplace
blencorp/lisa
Author
BLEN Starter Kit
Category
Community