
lisa
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@lisaRun it inside Claude Code after adding the marketplace with /plugin marketplace add blencorp/lisa.
Contents
Discovered from sourceCommands 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:
- List all in-progress interviews with feature names and timestamps
- Let you select which interview to resume
- 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
- Initialization - Creates state file and draft spec
- Interview - Asks non-obvious questions via AskUserQuestion tool
- Draft Updates - Maintains running draft every 2-3 questions
- 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
- Lisa plans - Generate comprehensive spec:
/lisa:plan "my feature" - 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
- EVERY question must use AskUserQuestion - plain text questions won't work
- Ask NON-OBVIOUS questions (not "what should it do?" but "how should X handle Y?")
- Continue until user says "done" or "finalize"
- 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:
- Write the final markdown spec file
- Write the JSON spec file
- Write the progress file with all phases marked as [PENDING]
- Delete the state file (.claude/lisa-{slug}.md)
- Output SPEC COMPLETE
- 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 namestarted_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:
- Read the full state file content
- Read the draft spec file at
.claude/lisa-draft.mdif it exists - The state file contains the full interview prompt after the YAML frontmatter
- 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)
- EVERY question must use AskUserQuestion - plain text questions won't work
- Ask NON-OBVIOUS questions (not "what should it do?" but "how should X handle Y?")
- Continue until user says "done" or "finalize"
- 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:
- Write the final markdown spec file
- Write the JSON spec file
- Write the progress file with all phases marked as [PENDING]
- Delete the state file (.claude/lisa-{slug}.md)
- Output SPEC COMPLETE
- 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.
Hooks 1
Sponsors
Details
- Marketplace
- blencorp/lisa
- Author
- BLEN Starter Kit
- Category
- Community