smartlisa 0.1.0 → 0.1.3

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "lisa",
+  "description": "Project planning with milestones, epics, and stories. Break down work, track progress, and implement with full context.",
+  "version": "0.1.3",
+  "author": {
+    "name": "Rodrigo Klosowski",
+    "url": "https://rklosowski.com/"
+  }
+}

package/README.md

@@ -16,10 +16,35 @@ Lisa is the smart one. She breaks down complex projects into **Milestones → Ep
 
 ## Installation
 
+### CLI Tool
+
 ```bash
 npm install -g smartlisa
 ```
 
+### Claude Code Skills
+
+Lisa works as a Claude Code skill. Choose one installation method:
+
+**Via Plugin (Recommended)**
+```bash
+/plugin install github:klosowsk/lisa
+```
+
+**As Project Skills** (anyone cloning repo gets them)
+```bash
+# Copy to your project
+cp -r path/to/lisa/skills/lisa your-project/.claude/skills/
+cp -r path/to/lisa/skills/lisa-work your-project/.claude/skills/
+```
+
+**As Personal Skills** (available in all your projects)
+```bash
+# Symlink to your personal skills directory
+ln -s $(pwd)/skills/lisa ~/.claude/skills/lisa
+ln -s $(pwd)/skills/lisa-work ~/.claude/skills/lisa-work
+```
+
 ## Using with Claude Code
 
 Lisa is a Claude Code skill. Just ask:

package/dist/cli.js

@@ -468,7 +468,6 @@ var LisaError = class extends Error {
     this.name = "LisaError";
   }
 };
-var RalphError = LisaError;
 function generateId(prefix) {
   return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 6)}`;
 }
@@ -582,7 +581,6 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import YAML from "yaml";
 var LISA_DIR = ".lisa";
-var RALPH_DIR = LISA_DIR;
 var FileSystemStateAdapter = class {
   rootDir;
   lisaDir;
@@ -842,7 +840,7 @@ var StateManager = class {
   // Path Helpers
   // --------------------------------------------------------------------------
   getPath(relativePath) {
-    return path2.join(this.adapter.getRootDir(), RALPH_DIR, relativePath);
+    return path2.join(this.adapter.getRootDir(), LISA_DIR, relativePath);
   }
   getEpicDir(epicId, slug) {
     return this.getPath(path2.join(PATHS.epics.dir, `${epicId}-${slug}`));
@@ -1130,7 +1128,7 @@ var StateManager = class {
   async assembleProjectContext() {
     const project = await this.readProject();
     if (!project) {
-      throw new RalphError("Project not initialized", "NOT_INITIALIZED");
+      throw new LisaError("Project not initialized", "NOT_INITIALIZED");
     }
     return {
       project,
@@ -1148,7 +1146,7 @@ var StateManager = class {
     const index = await this.readMilestoneIndex();
     const milestone = index?.milestones.find((m) => m.id === milestoneId);
     if (!milestone) {
-      throw new RalphError(`Milestone ${milestoneId} not found`, "NOT_FOUND");
+      throw new LisaError(`Milestone ${milestoneId} not found`, "NOT_FOUND");
     }
     const milestoneDiscovery = await this.readMilestoneDiscovery(milestoneId);
     const siblingEpics = [];
@@ -1182,18 +1180,18 @@ var StateManager = class {
     const epicDirs = await this.listEpicDirs();
     const epicDir = epicDirs.find((d) => d.startsWith(`${epicId}-`));
     if (!epicDir) {
-      throw new RalphError(`Epic ${epicId} not found`, "NOT_FOUND");
+      throw new LisaError(`Epic ${epicId} not found`, "NOT_FOUND");
     }
     const slug = epicDir.split("-").slice(1).join("-");
     const epic = await this.readEpic(epicId, slug);
     if (!epic) {
-      throw new RalphError(`Epic ${epicId} not found`, "NOT_FOUND");
+      throw new LisaError(`Epic ${epicId} not found`, "NOT_FOUND");
     }
     const projectContext = await this.assembleProjectContext();
     const index = await this.readMilestoneIndex();
     const milestone = index?.milestones.find((m) => m.id === epic.milestone);
     if (!milestone) {
-      throw new RalphError(`Milestone ${epic.milestone} not found`, "NOT_FOUND");
+      throw new LisaError(`Milestone ${epic.milestone} not found`, "NOT_FOUND");
     }
     const milestoneDiscovery = await this.readMilestoneDiscovery(epic.milestone);
     const epicDiscovery = await this.readEpicDiscovery(epicId, slug);
@@ -1232,19 +1230,19 @@ var StateManager = class {
     const epicDirs = await this.listEpicDirs();
     const epicDir = epicDirs.find((d) => d.startsWith(`${epicId}-`));
     if (!epicDir) {
-      throw new RalphError(`Epic ${epicId} not found`, "NOT_FOUND");
+      throw new LisaError(`Epic ${epicId} not found`, "NOT_FOUND");
     }
     const slug = epicDir.split("-").slice(1).join("-");
     const prd = await this.readPrd(epicId, slug);
     if (!prd) {
-      throw new RalphError(
+      throw new LisaError(
         `PRD not found for ${epicId}. Generate PRD first.`,
         "MISSING_PRD"
       );
     }
     const architecture = await this.readArchitecture(epicId, slug);
     if (!architecture) {
-      throw new RalphError(
+      throw new LisaError(
         `Architecture not found for ${epicId}. Generate architecture first.`,
         "MISSING_ARCH"
       );
@@ -1746,7 +1744,7 @@ function getHowGuidance(storyId, hasArchitecture) {
 // src/core/commands/status.ts
 async function overview(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found. Run 'discover init' first.", "NOT_INITIALIZED");
+    return error("No Lisa project found. Run 'discover init' first.", "NOT_INITIALIZED");
   }
   const project = await state.readProject();
   const index = await state.readMilestoneIndex();
@@ -1820,7 +1818,7 @@ async function overview(state) {
     }
   };
   const sections = [
-    section.header("Ralph Status"),
+    section.header("Lisa Status"),
     section.subheader(`Project: ${project.name}`),
     section.dim(`  Status: ${project.status}`),
     section.dim(`  Updated: ${timeAgo(project.updated)}`)
@@ -1902,7 +1900,7 @@ async function overview(state) {
 }
 async function board(state, options = {}) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const allStories = [];
   const epicDirs = await state.listEpicDirs();
@@ -1935,7 +1933,7 @@ async function board(state, options = {}) {
     blocked: columns.blocked,
     deferred: columns.deferred
   };
-  const sections = [section.header("Ralph Board")];
+  const sections = [section.header("Lisa Board")];
   if (allStories.length === 0) {
     sections.push(section.info("No stories found."));
     return success(data, sections);
@@ -2068,7 +2066,7 @@ async function story(state, options) {
 }
 async function context(state, options = {}) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const { target, full, format } = options;
   if (!target) {
@@ -2780,8 +2778,8 @@ async function init(state, options) {
   const projectName = options.name || "Untitled Project";
   const project = await state.initialize(projectName);
   const sections = [
-    section.header("Initializing Ralph"),
-    section.success(`Created .ralph/ directory`),
+    section.header("Initializing Lisa"),
+    section.success(`Created .lisa/ directory`),
     section.success(`Project: ${project.name}`),
     section.success(`ID: ${project.id}`),
     section.blank(),
@@ -2806,7 +2804,7 @@ async function init(state, options) {
 }
 async function status(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found. Run 'discover init' first.", "NOT_INITIALIZED");
+    return error("No Lisa project found. Run 'discover init' first.", "NOT_INITIALIZED");
   }
   const context2 = await state.readDiscoveryContext();
   const constraints = await state.readConstraints();
@@ -2874,7 +2872,7 @@ async function status(state) {
 }
 async function start(state, options = {}) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found. Run 'discover init' first.", "NOT_INITIALIZED");
+    return error("No Lisa project found. Run 'discover init' first.", "NOT_INITIALIZED");
   }
   const history = await state.readDiscoveryHistory();
   const context2 = await state.readDiscoveryContext();
@@ -2956,7 +2954,7 @@ async function start(state, options = {}) {
 }
 async function addEntry(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   let history = await state.readDiscoveryHistory();
   if (!history) {
@@ -2982,7 +2980,7 @@ async function addEntry(state, options) {
 }
 async function complete(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const history = await state.readDiscoveryHistory();
   if (!history) {
@@ -3041,7 +3039,7 @@ async function findMilestoneById(state, milestoneId) {
 }
 async function element(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const { elementType, elementId } = options;
   if (elementType === "epic") {
@@ -3099,7 +3097,7 @@ async function element(state, options) {
 }
 async function addElementEntry(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const entry = {
     timestamp: now(),
@@ -3157,7 +3155,7 @@ function updateElementDiscoveryFromEntry(discovery, entry, question) {
 }
 async function completeElement(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   if (options.elementType === "epic") {
     const epicInfo = await findEpicByIdOrSlug(state, options.elementId);
@@ -3461,7 +3459,7 @@ function getStoriesGuidance(ctx) {
 // src/core/commands/plan.ts
 async function showMilestones(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const index = await state.readMilestoneIndex();
   const context2 = await state.readDiscoveryContext();
@@ -3531,7 +3529,7 @@ async function showMilestones(state) {
 }
 async function addMilestone(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   let index = await state.readMilestoneIndex();
   if (!index) {
@@ -3557,7 +3555,7 @@ async function addMilestone(state, options) {
 }
 async function showEpics(state, options = {}) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const index = await state.readMilestoneIndex();
   if (!index?.milestones || index.milestones.length === 0) {
@@ -3661,7 +3659,7 @@ async function showEpics(state, options = {}) {
 }
 async function addEpic(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const index = await state.readMilestoneIndex();
   if (!index) {
@@ -3737,7 +3735,7 @@ async function addEpic(state, options) {
 }
 async function planEpic(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const ctx = await state.assembleEpicContext(options.epicId);
   const epicDirs = await state.listEpicDirs();
@@ -4331,7 +4329,7 @@ function getDismissFeedbackGuidance(feedbackId) {
 // src/core/commands/feedback.ts
 async function markStory(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const parsed = parseStoryId(options.storyId);
   if (!parsed) {
@@ -4399,7 +4397,7 @@ async function markStory(state, options) {
 }
 async function addFeedback(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const parsed = parseStoryId(options.storyId);
   if (!parsed) {
@@ -4450,7 +4448,7 @@ async function addFeedback(state, options) {
 }
 async function listFeedback(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const feedbackQueue = await state.readFeedbackQueue();
   const stuckQueue = await state.readStuckQueue();
@@ -4516,7 +4514,7 @@ async function listFeedback(state) {
 }
 async function resolveFeedback(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const feedbackQueue = await state.readFeedbackQueue();
   if (!feedbackQueue) {
@@ -4558,7 +4556,7 @@ async function resolveFeedback(state, options) {
 }
 async function dismissFeedback(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const feedbackQueue = await state.readFeedbackQueue();
   if (!feedbackQueue) {
@@ -5032,7 +5030,7 @@ async function validateCoverageInternal(state) {
 }
 async function runFullValidation(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const issues = [];
   const sections = [section.header("Validation")];
@@ -5159,7 +5157,7 @@ async function runFullValidation(state) {
 }
 async function validateLinks(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const linksResult = await validateLinksInternal(state);
   await state.writeLinks(linksResult);
@@ -5195,7 +5193,7 @@ async function validateLinks(state) {
 }
 async function validateCoverage(state) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const coverageResult = await validateCoverageInternal(state);
   await state.writeCoverage(coverageResult);
@@ -5257,7 +5255,7 @@ async function validateCoverage(state) {
 }
 async function validateEpic(state, options) {
   if (!await state.isInitialized()) {
-    return error("No Ralph project found.", "NOT_INITIALIZED");
+    return error("No Lisa project found.", "NOT_INITIALIZED");
   }
   const epicDirs = await state.listEpicDirs();
   const epicDir = epicDirs.find((d) => d.startsWith(`${options.epicId}-`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartlisa",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "AI-powered planning system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -38,9 +38,11 @@
   },
   "files": [
     "dist",
-    ".claude"
+    ".claude-plugin",
+    "skills"
   ],
   "scripts": {
+    "init:claude": "node scripts/init-claude.js",
     "lisa": "tsx src/adapters/cli/index.ts",
     "build": "node esbuild.config.js",
     "build:watch": "node esbuild.config.js --watch",
@@ -53,7 +55,10 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "ci": "npm run typecheck && npm run lint && npm run test"
+    "ci": "npm run typecheck && npm run lint && npm run test",
+    "version:patch": "node scripts/bump-version.js patch",
+    "version:minor": "node scripts/bump-version.js minor",
+    "version:major": "node scripts/bump-version.js major"
   },
   "dependencies": {
     "chalk": "^5.3.0",

package/skills/lisa/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: lisa
+description: Plan and organize projects into milestones, epics, and stories. Use when breaking down work, creating roadmaps, planning features, asking "what should I work on?", "lisa status", "show me the board", organizing a project, or when user wants to scope and structure development work. Also triggers on "help me plan", "break this down", "create a roadmap", or "add milestone/epic/story".
+user-invocable: true
+---
+
+# Lisa - Planning Mode
+
+Plan and organize projects into milestones, epics, and stories.
+
+## Quick Start
+
+```bash
+# Check project status
+lisa status
+
+# Start a new project
+lisa discover init "Project Name"
+
+# View the board
+lisa status board
+```
+
+## Workflow
+
+### New Project
+
+1. **Ask for project name** - Confirm what they're building
+2. **Initialize**: `lisa discover init "Project Name"`
+3. **Check for existing code** - Read key files to understand patterns
+4. **Discovery conversation** - Natural Q&A about problem, vision, constraints
+   - For brownfield: suggest answers based on what you read
+
+### Existing Project
+
+1. **Check status**: `lisa status`
+2. **View board**: `lisa status board`
+3. **Add to plan** or **work on stories** as needed
+
+## Commands Reference
+
+| Action | Command |
+|--------|---------|
+| Project overview | `lisa status` |
+| Kanban board | `lisa status board` |
+| Story details | `lisa status show <id>` |
+| Start discovery | `lisa discover init "Name"` |
+| Continue discovery | `lisa discover` |
+| View milestones | `lisa plan milestones` |
+| Add milestone | `lisa plan add-milestone --name 'Name' --description 'Desc'` |
+| Add epic | `lisa plan add-epic --milestone M1 --name 'Name' --description 'Desc'` |
+| Generate stories | `lisa plan stories E1` |
+| Mark progress | `lisa feedback mark <id> <status>` |
+| Validate plan | `lisa validate` |
+
+## ID Formats
+
+| Type | Format | Example |
+|------|--------|---------|
+| Milestone | `M#` | `M1` |
+| Epic | `E#` | `E1` |
+| Story | `E#.S#` | `E1.S2` |
+
+## References
+
+- [commands.md](references/commands.md) - Full command reference
+- [examples.md](references/examples.md) - Workflow examples

package/skills/lisa/references/commands.md

@@ -0,0 +1,201 @@
+# Lisa Command Reference
+
+Complete reference for all Lisa CLI commands. Use `--help` with any command for quick help.
+
+## Discovery Commands
+
+Gather project context through guided discovery sessions.
+
+```bash
+lisa discover [subcommand] [options]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| *(none)* | Start or continue discovery session |
+| `init <name>` | Initialize new project |
+| `status` | Show discovery progress and gaps |
+| `complete` | Mark discovery phase complete |
+| `add-entry` | Add discovery entry manually |
+| `epic <id>` | Start discovery for specific epic |
+| `milestone <id>` | Start discovery for milestone |
+
+### Discovery Options
+
+| Option | Description |
+|--------|-------------|
+| `--quick` | Essentials only (problem, vision, success) |
+| `--standard` | Balanced depth (default) |
+| `--deep` | Comprehensive discovery |
+
+### Add Entry Options
+
+| Option | Description |
+|--------|-------------|
+| `--category <cat>` | Category: `problem`, `goals`, `users`, `constraints`, `scope`, `technical`, `risks`, `success` |
+| `--question '<q>'` | The discovery question |
+| `--answer '<a>'` | The answer/information |
+
+---
+
+## Plan Commands
+
+Create and manage roadmap artifacts.
+
+```bash
+lisa plan [subcommand] [options]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| *(none)* | Show milestones |
+| `milestones` | List all milestones |
+| `add-milestone` | Add new milestone |
+| `epics [M1]` | List epics (optionally filter by milestone) |
+| `add-epic` | Add new epic to milestone |
+| `epic <id>` | View/plan specific epic |
+| `stories <id>` | List stories for epic |
+
+### Add Milestone Options
+
+| Option | Description |
+|--------|-------------|
+| `--name '<name>'` | Milestone name (required) |
+| `--description '<desc>'` | Milestone description (required) |
+
+### Add Epic Options
+
+| Option | Description |
+|--------|-------------|
+| `--milestone <M1>` | Parent milestone ID (required) |
+| `--name '<name>'` | Epic name (required) |
+| `--description '<desc>'` | Epic description (required) |
+
+---
+
+## Status Commands
+
+View project state and story details.
+
+```bash
+lisa status [subcommand] [options]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| *(none)* | Project overview with phase and progress |
+| `board [epic]` | Kanban board (optionally filter by epic) |
+| `show <id>` | Detailed story information |
+| `context [target]` | Context for project, milestone, epic, or story |
+| `why <id>` | Explain story lineage (trace requirements) |
+| `how <id>` | Implementation guidance |
+
+### Status Options
+
+| Option | Description |
+|--------|-------------|
+| `--full` | Full output without truncation |
+| `--format json` | Output in JSON format |
+
+### ID Formats
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Milestone | `M1` | Milestone 1 |
+| Epic | `E1` | Epic 1 |
+| Story | `E1.S2` | Epic 1, Story 2 |
+
+---
+
+## Feedback Commands
+
+Track progress and manage feedback items.
+
+```bash
+lisa feedback [subcommand] [options]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| *(none)* | List all pending feedback items |
+| `mark <id> <status>` | Update story status |
+| `add <id>` | Add feedback to story |
+| `resolve <fb-id>` | Mark feedback as resolved |
+| `dismiss <fb-id>` | Dismiss feedback without action |
+
+### Story Statuses
+
+| Status | Description |
+|--------|-------------|
+| `todo` | Not started |
+| `assigned` | Assigned to someone |
+| `in_progress` | Work in progress |
+| `review` | In review |
+| `done` | Completed |
+| `blocked` | Blocked by dependency/issue |
+| `deferred` | Postponed to later |
+
+### Feedback Types
+
+| Type | Description |
+|------|-------------|
+| `blocker` | Something blocking progress |
+| `gap` | Missing information or requirement |
+| `scope` | Scope change or clarification needed |
+| `conflict` | Conflicting requirements |
+| `question` | Question needing answer |
+
+### Feedback Options
+
+| Option | Description |
+|--------|-------------|
+| `--reason '<text>'` | Reason for status change (mark) |
+| `--type <type>` | Feedback type (add) |
+| `--message '<text>'` | Feedback message (add) |
+| `--resolution '<text>'` | Resolution note (resolve) |
+
+---
+
+## Validate Commands
+
+Check plan integrity and coverage.
+
+```bash
+lisa validate [subcommand]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| *(none)* | Run full validation suite |
+| `links` | Check all cross-references |
+| `coverage` | Check requirement coverage |
+| `epic <id>` | Validate specific epic |
+
+### What Gets Validated
+
+- All story IDs reference valid epics
+- All epic IDs reference valid milestones
+- No orphaned or dangling references
+- Requirements have implementing stories
+- Stories have acceptance criteria
+- Epic scope is complete and consistent
+
+---
+
+## Global Options
+
+Available on all commands:
+
+| Option | Description |
+|--------|-------------|
+| `--help`, `-h` | Show help for command |
+| `--full` | Show full output without truncation |
+| `--format json` | Output in JSON format |
+
+## Examples
+
+```bash
+lisa status --help
+lisa discover --deep
+lisa feedback mark E1.S2 done
+```

package/skills/lisa/references/examples.md

@@ -0,0 +1,277 @@
+# Lisa Workflow Examples
+
+Practical examples for common planning scenarios.
+
+## Example 1: Starting a New Project
+
+User says: "Help me plan a todo app"
+
+```bash
+# 1. Initialize the project
+lisa discover init "Todo App"
+
+# 2. Start discovery (ask about problem, users, goals)
+lisa discover
+
+# 3. Check discovery progress
+lisa discover status
+
+# 4. For comprehensive planning, use deep mode
+lisa discover --deep
+```
+
+**Key points:**
+- Always ask user for the project name before initializing
+- Discovery is iterative - run it multiple times to fill gaps
+- Check status to see what's missing
+
+---
+
+## Example 2: Brownfield Project (Existing Codebase)
+
+User says: "Help me plan features for my existing app"
+
+```bash
+# 1. Initialize with existing codebase
+lisa discover init "My Existing App"
+
+# 2. Analyze the codebase first
+lisa discover codebase
+
+# 3. Continue with regular discovery
+lisa discover
+```
+
+**Key points:**
+- Run `codebase` analysis before general discovery
+- This captures existing patterns, tech stack, and structure
+
+---
+
+## Example 3: Creating the Roadmap
+
+User says: "Break this into milestones and epics"
+
+```bash
+# 1. Check discovery is sufficient
+lisa discover status
+
+# 2. Generate/view milestones
+lisa plan milestones
+
+# 3. Add milestones manually if needed
+lisa plan add-milestone \
+  --name 'MVP' \
+  --description 'Core todo CRUD functionality'
+
+lisa plan add-milestone \
+  --name 'Collaboration' \
+  --description 'Shared lists and real-time sync'
+
+# 4. Generate epics for milestone
+lisa plan epics M1
+
+# 5. Add epics manually if needed
+lisa plan add-epic \
+  --milestone M1 \
+  --name 'Task Management' \
+  --description 'Create, edit, delete, complete tasks'
+```
+
+**Key points:**
+- Focus on one milestone at a time with `plan epics M1`
+
+---
+
+## Example 4: Generating Stories
+
+User says: "Generate stories for the authentication epic"
+
+```bash
+# 1. View epic details
+lisa plan epic E1
+
+# 2. Generate stories for the epic
+lisa plan stories E1
+
+# 3. View the generated stories
+lisa status board E1
+```
+
+---
+
+## Example 5: Working on Stories
+
+User says: "What should I work on?" or "Show me story E1.S2"
+
+```bash
+# View the kanban board
+lisa status board
+
+# Get details on a specific story
+lisa status show E1.S2
+
+# Understand why this story exists
+lisa status why E1.S2
+
+# Get implementation guidance
+lisa status how E1.S2
+
+# Get full context for implementation
+lisa status context E1.S2 --full
+```
+
+---
+
+## Example 6: Tracking Progress
+
+User says: "I finished E1.S2" or "E1.S3 is blocked"
+
+```bash
+# Mark story as done
+lisa feedback mark E1.S2 done
+
+# Mark story as blocked with reason
+lisa feedback mark E1.S3 blocked \
+  --reason "Waiting for API documentation"
+
+# Start working on a story
+lisa feedback mark E1.S4 in_progress
+
+# Mark for review
+lisa feedback mark E1.S4 review
+```
+
+---
+
+## Example 7: Adding Feedback
+
+User says: "There's a problem with this story" or "I have a question"
+
+```bash
+# Report a blocker
+lisa feedback add E1.S2 \
+  --type blocker \
+  --message "API endpoint returns wrong format"
+
+# Ask a question
+lisa feedback add E1.S3 \
+  --type question \
+  --message "Should we support pagination?"
+
+# Report scope issue
+lisa feedback add E2.S1 \
+  --type scope \
+  --message "This needs to handle bulk operations too"
+
+# View all pending feedback
+lisa feedback
+
+# Resolve feedback
+lisa feedback resolve fb-abc123 \
+  --resolution "Added pagination support"
+
+# Dismiss feedback (not actionable)
+lisa feedback dismiss fb-xyz789
+```
+
+---
+
+## Example 8: Validation
+
+User says: "Validate my plan" or "Check for issues"
+
+```bash
+# Run full validation
+lisa validate
+
+# Check just cross-references
+lisa validate links
+
+# Check requirement coverage
+lisa validate coverage
+
+# Validate specific epic
+lisa validate epic E1
+```
+
+---
+
+## Example 9: Quick Status Check
+
+User says: "Lisa status" or "What's the project state?"
+
+```bash
+# Project overview
+lisa status
+
+# Kanban board
+lisa status board
+
+# Context for a specific item
+lisa status context E1 --full
+lisa status context M1
+```
+
+---
+
+## Workflow Decision Tree
+
+```
+User request → What phase are we in?
+
+No .lisa/ directory?
+  → Ask for project name
+  → lisa discover init "Name"
+
+Discovery incomplete?
+  → lisa discover
+  → lisa discover status
+
+No milestones?
+  → lisa plan milestones
+
+No epics?
+  → lisa plan epics M1
+
+No stories?
+  → lisa plan stories E1
+
+Working on implementation?
+  → lisa status how E1.S2
+  → lisa feedback mark E1.S2 in_progress
+
+Need to validate?
+  → lisa validate
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Starting a conversation about planning
+
+1. Check if `.lisa/` exists
+2. If not, ask user: "What would you like to name this project?"
+3. Initialize and start discovery
+
+### Pattern: User asks "what's next?"
+
+```bash
+lisa status
+lisa status board
+```
+
+### Pattern: User completed work
+
+```bash
+lisa feedback mark <story-id> done
+lisa status board  # Show updated board
+```
+
+### Pattern: User is stuck
+
+```bash
+lisa status how <story-id>  # Implementation guidance
+lisa status why <story-id>  # Context and reasoning
+```

package/skills/lisa-work/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: lisa-work
+description: Implement Lisa stories with full context. Use when asked to "work on E1.S2", "implement this story", "start working on", "help me build", "pick up a task", "next story", or when implementing specific stories from the Lisa plan. Also triggers on "implement E1.S1", "let's code this story", or "start the next task".
+user-invocable: true
+---
+
+# Lisa - Implementation Mode
+
+Implement stories with full context, architecture, and acceptance criteria.
+
+## Quick Start
+
+```bash
+# Work on a specific story
+/lisa-work E1.S2
+
+# See available stories and pick one
+/lisa-work
+```
+
+## Workflow
+
+### Phase 1: Story Selection
+
+**If story ID provided** (e.g., `/lisa-work E1.S2`):
+- Validate the story exists
+- Load its context directly
+
+**If no story ID** (e.g., `/lisa-work`):
+1. Run `lisa status board` to see available stories
+2. Ask the user which story to work on
+3. Recommend stories that are `todo` with dependencies `done`
+
+### Phase 2: Load Context
+
+```bash
+lisa status context E1.S2 --full
+```
+
+### Phase 3: Mark In Progress
+
+```bash
+lisa feedback mark E1.S2 in_progress
+```
+
+### Phase 4: Present Working Context
+
+Summarize for the user:
+- **Story**: Title, description
+- **Acceptance Criteria**: As a checklist
+- **Architecture**: Relevant patterns
+- **Dependencies**: Status of prerequisites
+
+### Phase 5: Implement
+
+- Follow acceptance criteria as a checklist
+- Reference architecture for patterns
+- Never mention story IDs in code comments
+
+**If blocked:**
+```bash
+lisa feedback mark E1.S2 blocked --reason "Describe the issue"
+```
+
+### Phase 6: Complete
+
+1. Ask user to confirm all criteria are met
+2. Only after explicit approval:
+   ```bash
+   lisa feedback mark E1.S2 done --reason "Brief summary"
+   ```
+3. Offer next steps
+
+**Important:** Never mark done without user confirmation.
+
+## Commands Reference
+
+| Action | Command |
+|--------|---------|
+| View board | `lisa status board` |
+| Full context | `lisa status context <id> --full` |
+| Why it exists | `lisa status why <id>` |
+| Mark in progress | `lisa feedback mark <id> in_progress` |
+| Mark blocked | `lisa feedback mark <id> blocked --reason "..."` |
+| Mark done | `lisa feedback mark <id> done --reason "..."` |
+| Add feedback | `lisa feedback add <id> --type <type> --message "..."` |
+
+## Story Status Flow
+
+```
+todo → in_progress → review → done
+          ↓
+        blocked
+```
+
+## References
+
+- [workflow.md](references/workflow.md) - Detailed workflow and error handling

package/skills/lisa-work/references/workflow.md

@@ -0,0 +1,226 @@
+# Lisa Work - Detailed Implementation Workflow
+
+Step-by-step guide for implementing stories with `/lisa-work`.
+
+## Story Selection Flow
+
+### With Story ID: `/lisa-work E1.S2`
+
+1. Validate the story exists:
+   ```bash
+   lisa status show E1.S2
+   ```
+
+2. If not found, show error and suggest:
+   ```bash
+   lisa status board
+   ```
+
+### Without Story ID: `/lisa-work`
+
+1. Get the current board:
+   ```bash
+   lisa status board
+   ```
+
+2. Present available stories to the user, highlighting:
+   - Stories with status `todo`
+   - Stories whose dependencies are all `done`
+
+3. Ask: "Which story would you like to work on?"
+
+4. Recommend the best candidate:
+   - First `todo` story with no pending dependencies
+   - Lowest epic number, then lowest story number
+
+## Context Loading
+
+### Primary Context
+
+```bash
+lisa status context E1.S2 --full
+```
+
+This returns:
+- Story details (title, description, acceptance criteria)
+- Epic information
+- Milestone context
+- Architecture reference
+- Project-level discovery context
+
+### Implementation Guidance
+
+```bash
+lisa status how E1.S2
+```
+
+This returns:
+- Implementation checklist based on acceptance criteria
+- Architecture reference snippets
+- Stack context (tech stack, patterns)
+- Dependency status
+
+### Story Rationale (Optional)
+
+```bash
+lisa status why E1.S2
+```
+
+Use this when the user wants to understand:
+- Why this story exists
+- What requirements it fulfills
+- How it connects to the epic/milestone goals
+
+## Working Context Presentation
+
+After loading context, present it in this format:
+
+```markdown
+## Working on: E1.S2 - [Story Title]
+
+**Epic:** E1 - [Epic Name]
+**Status:** in_progress
+
+### Description
+[Story description from context]
+
+### Acceptance Criteria
+- [ ] First criterion
+- [ ] Second criterion
+- [ ] Third criterion
+
+### Architecture Notes
+[Relevant sections from architecture.md]
+
+### Dependencies
+- E1.S1: done - [Title]
+
+### Ready to implement!
+```
+
+## During Implementation
+
+### Tracking Progress
+
+As you work through acceptance criteria:
+- Check off each criterion as it's completed
+- Reference architecture for patterns
+- Ask clarifying questions if needed
+
+### Handling Issues
+
+**Blocked by external dependency:**
+```bash
+lisa feedback mark E1.S2 blocked --reason "Waiting for API endpoint"
+lisa feedback add E1.S2 --type blocker --message "Need /api/users endpoint"
+```
+
+**Missing information:**
+```bash
+lisa feedback add E1.S2 --type gap --message "Architecture doesn't specify error handling"
+```
+
+**Scope question:**
+```bash
+lisa feedback add E1.S2 --type question --message "Should this support pagination?"
+```
+
+### Feedback Types
+
+| Type | Use When |
+|------|----------|
+| `blocker` | Something external is blocking progress |
+| `gap` | Missing information or requirement |
+| `scope` | Scope change or clarification needed |
+| `conflict` | Conflicting requirements found |
+| `question` | Need answer to proceed |
+
+## Completing Work
+
+### Review Before Closing
+
+**Never mark a story done without explicit user confirmation.**
+
+1. When all acceptance criteria appear complete, ask:
+   > "All acceptance criteria look complete. Would you like to review the changes before marking E1.S2 as done?"
+
+2. Wait for user response:
+   - **"Yes, mark it done"** → proceed to mark done
+   - **"Let me review"** → help them review the changes
+   - **"Not yet, I found an issue"** → continue implementation
+
+### Marking Done (After User Approval)
+
+Only after explicit user confirmation:
+
+```bash
+lisa feedback mark E1.S2 done --reason "Implemented all acceptance criteria"
+```
+
+### Next Steps
+
+After completion, offer:
+1. Work on the next story
+2. View the updated board
+3. Take a break
+
+```bash
+lisa status board
+```
+
+## Error Handling
+
+### Story Not Found
+
+```
+Error: Story E1.S99 not found.
+
+Available stories:
+  lisa status board
+```
+
+### Epic Not Found
+
+```
+Error: Epic E99 not found.
+
+Check available epics:
+  lisa plan epics
+```
+
+### No Stories Available
+
+```
+No todo stories found.
+
+Options:
+- Generate stories: lisa plan stories E1
+- Check board: lisa status board
+```
+
+### Dependencies Not Complete
+
+```
+Warning: E1.S2 depends on E1.S1 which is still 'todo'.
+
+Recommendation:
+- Work on E1.S1 first
+- Or proceed with caution (may need rework)
+```
+
+### Context Loading Failure
+
+```
+Error: Architecture not found for E1.
+
+Generate artifacts first:
+  lisa plan epic E1
+```
+
+## Tips for Effective Implementation
+
+1. **Read the architecture first** - Understand patterns before coding
+2. **Check dependencies** - Ensure prerequisite stories are done
+3. **Work through criteria sequentially** - Don't skip around
+4. **Mark blocked early** - Don't spin on issues
+5. **Add feedback for plan gaps** - Help improve future stories