@lavralabs/lavra 0.7.0

package/plugins/lavra/commands/lavra-eng-review.md

@@ -0,0 +1,262 @@
+---
+name: lavra-eng-review
+description: Engineering review -- parallel agents check architecture, simplicity, security, and performance
+argument-hint: "[epic bead ID] [--small]"
+---
+
+<objective>
+Review an epic plan using multiple specialized agents in parallel to catch technical issues before implementation begins. Engineering layer review: given we're building this, is the architecture sound? N+1s? Security holes? Run after lavra-ceo-review so engineering effort is spent on a validated direction.
+</objective>
+
+<execution_context>
+<epic_bead_id> #$ARGUMENTS </epic_bead_id>
+
+**If the epic bead ID above is empty:**
+1. Check for recent epic beads: `bd list --type epic --status=open --json`
+2. Ask the user: "Which epic plan would you like reviewed? Please provide the bead ID (e.g., `BD-001`)."
+
+Do not proceed until you have a valid epic bead ID.
+
+**Parse `--small` flag:**
+- If `--small` is present in the arguments, set BIG_SMALL_MODE=small
+- Default: BIG_SMALL_MODE=big
+- In `--small` mode, each agent returns only its **single most important finding**; synthesis produces a compact prioritized list
+</execution_context>
+
+<process>
+
+### Step 1: Load the Plan
+
+```bash
+# Read the epic
+bd show {EPIC_ID}
+
+# List and read all child beads
+bd list --parent {EPIC_ID} --json
+```
+
+For each child bead, read its full description:
+
+```bash
+bd show {CHILD_ID}
+```
+
+Assemble the full plan content from epic description + all child bead descriptions.
+
+**Retrospective check:**
+
+```bash
+git log --oneline -20
+```
+
+If prior commits suggest a previous review cycle on this branch (e.g., "address review feedback", reverted changes, refactor-after-review commits), note which areas were previously problematic. Pass this context to agents so they review those areas more aggressively. Recurring problem areas are architectural smells.
+
+### Step 2: Recall Relevant Knowledge + Read Workflow Config
+
+```bash
+# Search for knowledge related to the plan's topic
+.lavra/memory/recall.sh "{keywords from epic title}"
+.lavra/memory/recall.sh "{tech stack keywords}"
+```
+
+Include any relevant LEARNED/DECISION/FACT/PATTERN entries as context for reviewers.
+
+Read workflow config for model profile:
+
+```bash
+[ -f .lavra/config/lavra.json ] && cat .lavra/config/lavra.json
+```
+
+Parse `model_profile` (default: `"balanced"`). When `model_profile` is `"quality"`, dispatch `architecture-strategist`, `security-sentinel`, and `performance-oracle` with `model: opus`.
+
+### Step 3: Dispatch Review Agents in Parallel
+
+**In `--small` mode:** instruct each agent to return only its single most important finding.
+
+**In default (big) mode:** full parallel dispatch with complete analysis.
+
+Run these 4 agents simultaneously, passing the full plan content + retrospective context to each. Also request: (a) one realistic production failure scenario per new codepath (timeout, nil, race condition, etc.) and (b) any work that could be deferred without blocking the core objective:
+
+1. Task architecture-strategist("Review this plan for architectural soundness, scalability, and maintainability. For each new codepath, identify one realistic production failure. Flag any work deferrable without blocking the core objective. Plan: [full plan content]. Prior review context: [retrospective findings]") -- add `model: opus` if profile=quality
+2. Task code-simplicity-reviewer("Review this plan for unnecessary complexity, over-engineering, and opportunities to simplify. For each new codepath, identify one realistic production failure. Flag any work deferrable without blocking the core objective. Plan: [full plan content]. Prior review context: [retrospective findings]")
+3. Task security-sentinel("Review this plan for security vulnerabilities, missing auth checks, data exposure risks. For each new codepath, identify one realistic production failure. Plan: [full plan content]. Prior review context: [retrospective findings]") -- add `model: opus` if profile=quality
+4. Task performance-oracle("Review this plan for performance bottlenecks, N+1 queries, missing caching, scalability issues. For each new codepath, identify one realistic production failure. Plan: [full plan content]. Prior review context: [retrospective findings]") -- add `model: opus` if profile=quality
+
+### Step 4: Synthesize Findings
+
+After all agents complete, synthesize their feedback into a categorized report:
+
+**In `--small` mode:** produce a compact prioritized list (top finding per agent + single combined recommendation).
+
+**In default (big) mode:**
+
+```markdown
+## Engineering Review: {EPIC_ID} - {epic title}
+
+### Architecture
+[Findings from architecture-strategist]
+- Strengths: [what's well designed]
+- Concerns: [architectural issues]
+- Suggestions: [improvements]
+
+### Simplicity
+[Findings from code-simplicity-reviewer]
+- Over-engineering risks: [what could be simpler]
+- Unnecessary abstractions: [what to remove]
+- Suggestions: [simplifications]
+
+### Security
+[Findings from security-sentinel]
+- Vulnerabilities: [security risks found]
+- Missing protections: [what needs adding]
+- Suggestions: [security improvements]
+
+### Performance
+[Findings from performance-oracle]
+- Bottlenecks: [performance concerns]
+- Missing optimizations: [what to add]
+- Suggestions: [performance improvements]
+
+### Failure Modes
+Per-new-codepath analysis from agent findings:
+```
+CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
+---------|----------------|----------|-------|----------------|--------
+[path]   | [failure]      | Y/N      | Y/N   | [visible/silent]| Y/N
+```
+Flag any row with RESCUED=N AND TEST=N AND USER SEES=Silent as **CRITICAL GAP**.
+
+### NOT in Scope
+Work the agents flagged as deferrable without blocking the core objective:
+- [item] -- [one-line rationale]
+- [item] -- [one-line rationale]
+
+### Summary
+- **Critical issues:** [count] - Must fix before implementing
+- **Important suggestions:** [count] - Should consider
+- **Minor improvements:** [count] - Nice to have
+
+### Recommended Changes
+1. [Most impactful change]
+2. [Second most impactful]
+3. [Third most impactful]
+
+### Completion Summary
+```
+Architecture issues: N  |  Simplicity: N  |  Security: N  |  Performance: N
+Critical gaps: N  |  TODOs proposed: N
+```
+```
+
+### Step 5: Log Key Findings + TODOS Protocol
+
+Log significant findings:
+
+```bash
+bd comments add {EPIC_ID} "LEARNED: Engineering review found: {key insight}"
+```
+
+**TODOS section:** For each deferrable item surfaced by agents, present as its own AskUserQuestion — never batch, one per question:
+
+- **What**: One-line description of the work.
+- **Why**: The concrete problem it solves or value it unlocks.
+- **Pros**: What you gain by doing this work.
+- **Cons**: Cost, complexity, or risks.
+- **Context**: Enough detail for someone picking this up in 3 months.
+- **Effort estimate**: S/M/L/XL
+
+Options: **A)** Create a backlog bead **B)** Skip — not valuable enough **C)** Build it now in this plan instead of deferring.
+
+</process>
+
+<success_criteria>
+- All 4 review agents dispatched and completed
+- Retrospective check performed (prior review cycles noted if any)
+- Findings synthesized into categorized report with severity levels
+- Failure modes table produced with CRITICAL GAP flagging
+- NOT in scope section included
+- Completion summary table produced
+- TODOs presented one-per-AskUserQuestion
+- Critical issues clearly identified
+- Key findings logged as knowledge comments
+</success_criteria>
+
+<handoff>
+After presenting the review, use the **AskUserQuestion tool** to present these options:
+
+**Question:** "Engineering review complete for `{EPIC_ID}`. What would you like to do next?"
+
+**Options:**
+1. **Apply feedback** - Update child beads with review suggestions
+2. **Run `/lavra-research`** - Gather additional evidence with domain-matched agents
+3. **Start `/lavra-work`** - Begin implementing the first child bead
+4. **Run `/lavra-work {EPIC_ID}`** - Work on multiple child beads in parallel
+5. **Dismiss** - Acknowledge review without changes
+
+## Applying Feedback (when option 1 is selected)
+
+**Do not proceed informally.** Follow this exact protocol.
+
+### Step A: Build the Recommendation Checklist
+
+Before touching any bead, extract every actionable recommendation from the review report. Number them sequentially:
+
+```
+RECOMMENDATIONS TO APPLY:
+[ ] 1. [Exact recommendation from Architecture section]
+[ ] 2. [Exact recommendation from Architecture section]
+[ ] 3. [Exact recommendation from Simplicity section]
+[ ] 4. [Exact recommendation from Security section]
+[ ] 5. [Exact recommendation from Performance section]
+...
+```
+
+Print this numbered list to the user before starting. If the review had a "Recommended Changes" section, include all items from it. Also include any critical/important issues from each category.
+
+**Total count:** State how many recommendations you found (e.g., "Found 12 recommendations. Applying now.")
+
+### Step B: Apply Each Recommendation
+
+Work through the list one at a time. For each recommendation:
+
+1. **Identify the target bead** - Which child bead (or epic) does this apply to?
+2. **Read the current description**: `bd show {BEAD_ID}`
+3. **Update it**: `bd update {BEAD_ID} -d "{updated description with recommendation applied}"`
+4. **Mark complete** in your working list: `[x] 1. ...`
+
+If a recommendation applies to multiple beads, update each one.
+
+If a recommendation is architectural (affects the whole plan), update the epic description.
+
+If a recommendation is contradictory or inapplicable, mark it `[SKIPPED: reason]` -- do NOT silently omit it.
+
+### Step C: Completeness Verification
+
+After applying all changes, do a completeness pass:
+
+1. Re-read the original review report
+2. Compare each recommendation against your working checklist
+3. For any item not marked `[x]` or `[SKIPPED]`, apply it now
+
+Then print the final checklist state:
+
+```
+APPLIED:
+[x] 1. [recommendation] -> Updated {BEAD_ID}
+[x] 2. [recommendation] -> Updated {BEAD_ID}
+[x] 3. [recommendation] -> Updated {EPIC_ID}
+
+SKIPPED:
+[SKIPPED: contradicts architectural decision] 4. [recommendation]
+
+TOTAL: {N} applied, {M} skipped out of {N+M} recommendations
+```
+
+**Do not say "done" until every recommendation is either marked applied or explicitly skipped with a reason.**
+
+### Step D: Log Changes
+
+```bash
+bd comments add {EPIC_ID} "DECISION: Applied engineering review feedback. {N} recommendations applied across {K} beads. Key changes: {top 3 changes}"
+```
+</handoff>

package/plugins/lavra/commands/lavra-import.md

@@ -0,0 +1,194 @@
+---
+name: lavra-import
+description: Import a markdown plan into beads as an epic with child tasks
+argument-hint: "[path/to/plan.md] [optional epic title]"
+---
+
+<objective>
+Import a markdown plan document into beads as an epic with child task beads. Automatically extracts research findings, decisions, and implementation steps from the markdown structure.
+</objective>
+
+<execution_context>
+<input_document> #$ARGUMENTS </input_document>
+</execution_context>
+
+<process>
+
+### Phase 1: Parse Arguments
+
+1. **Extract Arguments**
+
+   Parse the #$ARGUMENTS to get:
+   - File path (required)
+   - Epic title (optional)
+
+   If no arguments provided:
+   - Ask: "Please provide the path to the markdown plan file, e.g.: /lavra-import plan.md"
+   - Stop execution
+
+   If only file path provided, the title will be auto-extracted from the first `#` header in the markdown file.
+
+2. **Validate File Path**
+
+   ```bash
+   # Check if file exists and is readable
+   if [[ ! -f "{file_path}" ]]; then
+     echo "Error: File not found: {file_path}"
+     exit 1
+   fi
+   ```
+
+   If file doesn't exist:
+   - Report: "File not found: {file_path}. Please provide a valid markdown file path."
+   - Stop execution
+
+3. **Extract Title from Markdown** (if not provided)
+
+   Read the first line starting with `#` to extract the title:
+
+   ```bash
+   # Extract title from first # header
+   title=$(grep -E "^# " "{file_path}" | head -1 | sed 's/^# *//')
+
+   if [[ -z "$title" ]]; then
+     echo "Error: Could not find title in markdown file (no # header found)"
+     exit 1
+   fi
+   ```
+
+   If no `#` header found and no title argument provided:
+   - Ask: "No title found in markdown file. Please provide a title: /lavra-import {file_path} \"Your Epic Title\""
+   - Stop execution
+
+### Phase 2: Run Import Script
+
+1. **Call Import Script**
+
+   Execute the import script with the validated arguments:
+
+   ```bash
+   # Determine PLUGIN_DIR based on whether this is a global or project install
+   if [[ -f ".claude/scripts/import-plan.sh" ]]; then
+     SCRIPT_PATH=".claude/scripts/import-plan.sh"
+   elif [[ -f ".opencode/scripts/import-plan.sh" ]]; then
+     SCRIPT_PATH=".opencode/scripts/import-plan.sh"
+   else
+     echo "Error: import-plan.sh script not found"
+     echo "Expected at .claude/scripts/import-plan.sh or .opencode/scripts/import-plan.sh"
+     exit 1
+   fi
+
+   bash "$SCRIPT_PATH" "{file_path}" "{title}"
+   ```
+
+2. **Capture Script Output**
+
+   The import-plan.sh script will output:
+   - Progress messages as it creates beads
+   - Epic ID when created
+   - Child bead IDs as they're created
+   - Summary with next steps
+
+   Capture the epic ID from the output:
+
+   ```bash
+   # Extract epic ID from output
+   epic_id=$(echo "$output" | grep -oE 'Created epic: [A-Z]+-[0-9]+' | grep -oE '[A-Z]+-[0-9]+' | head -1)
+   ```
+
+### Phase 3: Report Results
+
+1. **Display Summary**
+
+   Present the import results to the user:
+
+   ```
+   Successfully imported plan from {file_path}
+
+   Epic created: {EPIC_ID}
+   Title: {title}
+
+   Child beads created: {count}
+
+   View the epic:
+     bd show {EPIC_ID}
+
+   List all child beads:
+     bd list --parent {EPIC_ID}
+   ```
+
+</process>
+
+<context>
+
+## Expected Markdown Format
+
+The import script expects markdown with this structure:
+
+```markdown
+# Epic Title
+Description of the overall feature or project.
+
+## Research / Background
+Research findings and context...
+
+## Decisions / Approach
+Architectural decisions and chosen approach...
+
+## Implementation Steps / Tasks
+### Step 1: Database Schema
+Details about database changes...
+
+### Step 2: API Endpoints
+Details about API implementation...
+
+### Step 3: Frontend Components
+Details about UI changes...
+```
+
+**Key sections:**
+- `# Epic Title` - Becomes the epic bead title (if not provided as argument)
+- `## Research / Background / Context` - Captured as INVESTIGATION comments
+- `## Decisions / Choices / Approach` - Captured as DECISION comments
+- `## Implementation Steps / Tasks / Work` - Each `### Step` becomes a child bead
+  - Child beads are created sequentially with dependencies (Step 2 depends on Step 1, etc.)
+
+## Error Handling
+
+**Common errors and solutions:**
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| File not found | Invalid file path | Check path and try again |
+| No title in markdown | Missing `#` header | Provide title as argument |
+| Script not found | Plugin not installed | Run plugin installation |
+| No implementation steps | Missing `###` headers | Add implementation section with steps |
+
+## Notes
+
+- The import script automatically creates sequential dependencies (each step depends on the previous)
+- Research and decision sections are captured as knowledge comments on the epic
+- Child bead descriptions are extracted from the content between `###` headers
+- The script expects the plan to have an "Implementation Steps" section with `###` subheadings
+</context>
+
+<success_criteria>
+- Valid markdown file with clear structure
+- At least one `#` header for the title (or title provided as argument)
+- An "Implementation Steps" section with at least one `### Step`
+- Each step has descriptive content below the `###` header
+- File path validated before calling the script
+- Title extracted from markdown if not provided
+- Clear progress and results displayed
+- Actionable next steps suggested
+- Errors handled gracefully with helpful messages
+</success_criteria>
+
+<handoff>
+Plan imported as epic `{EPIC_ID}`. What would you like to do next?
+
+1. **Run `/lavra-research {EPIC_ID}`** - Gather evidence for each child bead with domain-matched research agents
+2. **Run `/lavra-eng-review {EPIC_ID}`** - Get feedback from reviewers on the plan
+3. **Start `/lavra-work {EPIC_ID}.1`** - Begin implementing the first child bead
+4. **View epic** - Show the full epic bead details
+</handoff>

package/plugins/lavra/commands/lavra-learn.md

@@ -0,0 +1,176 @@
+---
+name: lavra-learn
+description: Curate raw knowledge comments into structured, well-tagged entries for future auto-recall
+argument-hint: "[bead IDs to process, or omit for all closed-today beads]"
+---
+
+<objective>
+Turn raw LEARNED/DECISION/FACT/PATTERN/INVESTIGATION comments captured during work sessions into structured, deduplicated, well-tagged knowledge entries in `.lavra/memory/knowledge.jsonl`. This is the step that converts inline observations into searchable, recallable knowledge that makes future work easier.
+</objective>
+
+<context>
+**When to use:**
+- After `/lavra-work` completes (auto-suggested when LEARNED/INVESTIGATION comments exist)
+- Manually after any work session to consolidate what was captured
+- Periodically to clean up and connect knowledge across beads
+
+**Knowledge flow:**
+```
+Work session -> inline bd comments (raw) -> /lavra-learn (structured) -> auto-recall (future sessions)
+```
+
+Raw comments logged during work are often terse, context-dependent, and untagged beyond auto-detection. This command reviews them with full context, produces well-titled entries with accurate tags, deduplicates against existing knowledge, and synthesizes higher-level patterns when multiple entries connect.
+
+**Usage:**
+```bash
+/lavra-learn                       # Process all beads closed today
+/lavra-learn BD-042                # Process specific bead
+/lavra-learn BD-042 BD-043 BD-044  # Process multiple beads
+```
+</context>
+
+<process>
+
+### Step 1: Gather Raw Entries
+
+Collect all knowledge comments from the target beads.
+
+**If bead IDs were provided:**
+```bash
+bd show {BEAD_ID} --json
+# Extract comments matching LEARNED:|DECISION:|FACT:|PATTERN:|INVESTIGATION: prefixes
+```
+
+**If no bead IDs provided, find beads closed today:**
+```bash
+bd list --status=closed --json | jq '[.[] | select(.updated_at >= "'$(date +%Y-%m-%d)'")]'
+```
+
+For each bead, collect:
+- All comments with knowledge prefixes
+- Bead title and description (for context)
+- Related bead IDs from dependencies
+
+If no knowledge comments are found in the target beads, report that and exit -- there is nothing to curate.
+
+### Step 2: Analyze and Cross-Reference
+
+Review all gathered entries together and identify:
+
+1. **Recurring themes** -- multiple entries touching the same concept, API, or component
+2. **Related decisions** -- choices that reinforce or depend on each other
+3. **Complementary facts** -- constraints that together define a boundary
+4. **Gaps** -- work that clearly produced insights but no comment was logged (flag these but do not fabricate entries)
+
+Load existing knowledge for deduplication:
+```bash
+.lavra/memory/recall.sh "{keywords from gathered entries}" --all
+```
+
+### Step 3: Structure Each Entry
+
+For each raw comment, produce a structured knowledge entry:
+
+| Field | Guideline |
+|-------|-----------|
+| **key** | Lowercase, hyphenated, searchable title. Include the domain and the insight. Example: `learned-oauth-redirect-uri-must-match-exactly` |
+| **type** | Preserve the original prefix (learned/decision/fact/pattern/investigation) |
+| **content** | Rewrite for clarity and future recall. Remove session-specific references ("the bug we just fixed"). Keep it concise -- one to three sentences. Include code snippets only when they are the insight. |
+| **tags** | 3-6 tags covering: technology, domain area, and concept. Prefer existing tags from knowledge.jsonl for consistency. |
+| **source** | `user` |
+| **bead** | Source bead ID |
+
+### Step 4: Deduplicate
+
+For each structured entry, check knowledge.jsonl for near-duplicates:
+
+- **Exact key match**: Update the existing entry content and tags rather than creating a new one
+- **Similar content, different key**: Merge into the existing entry if the insight is the same, or keep both if they capture genuinely different aspects
+- **Superseded entry**: If the new entry corrects or supersedes an older one, update the old entry rather than creating a conflicting duplicate
+
+Report what was deduplicated and why.
+
+### Step 5: Synthesize Patterns
+
+If three or more entries share a theme, create a higher-level PATTERN entry that connects them:
+
+```bash
+bd comments add {BEAD_ID} "PATTERN: {synthesized insight connecting multiple observations}"
+```
+
+Synthesized patterns should:
+- Reference the underlying entries by concept (not by key, since keys may change)
+- Capture the higher-level principle, not just repeat the individual facts
+- Be actionable -- a future developer reading this should know what to do differently
+
+Only synthesize when the pattern is genuine. Do not force connections.
+
+### Step 6: Store
+
+Write all structured entries via `bd comments add` with appropriate prefixes so the memory-capture hook processes them into knowledge.jsonl:
+
+```bash
+bd comments add {BEAD_ID} "LEARNED: {structured content}"
+bd comments add {BEAD_ID} "DECISION: {structured content}"
+bd comments add {BEAD_ID} "FACT: {structured content}"
+bd comments add {BEAD_ID} "PATTERN: {structured content}"
+bd comments add {BEAD_ID} "INVESTIGATION: {structured content}"
+```
+
+The memory-capture hook will auto-tag and store each entry. The structured content from Step 3 ensures the auto-tagger has clear keywords to work with.
+
+</process>
+
+<success_criteria>
+- All knowledge comments from target beads reviewed and structured
+- Each entry has a clear, searchable key and 3-6 accurate tags
+- Near-duplicates identified and handled (updated or merged, not duplicated)
+- Cross-bead patterns synthesized where genuine connections exist
+- All entries stored via `bd comments add` for hook processing
+
+```
+Knowledge curation complete.
+
+Beads processed: {list of bead IDs}
+Entries structured: {N} (from {M} raw comments)
+Duplicates resolved: {N} updated, {N} merged
+Patterns synthesized: {N}
+Tag coverage: {list of top tags used}
+
+Entries created:
+  - {TYPE}: {key} (bead: {BEAD_ID})
+  - ...
+```
+</success_criteria>
+
+<guardrails>
+
+### This is curation, not research
+
+Do not launch subagents to investigate code or analyze architecture. The raw material is the knowledge comments already captured during work. Your job is to structure, deduplicate, and connect -- not to generate new findings.
+
+### Preserve the original author's intent
+
+When rewriting content for clarity, do not change the technical meaning. If an entry says "Enum comparison fails unless you cast to string first," do not generalize it to "Type coercion is important" -- the specific detail is the value.
+
+### Quality over quantity
+
+Five well-structured, accurately tagged entries are more valuable than fifteen vague ones. If a raw comment is too terse to understand without the original session context, flag it as needing clarification rather than guessing.
+
+### Tags must be useful for recall
+
+Tags exist so auto-recall can surface entries when working on related problems. Use concrete terms (oauth, postgres, rate-limiting) not abstract ones (important, tricky, gotcha).
+
+</guardrails>
+
+<handoff>
+What's next?
+1. View knowledge entries: `.lavra/memory/recall.sh "{keyword}"`
+2. Continue working on another bead
+3. Run `/lavra-checkpoint` to save session progress
+
+**Related Commands:**
+- `/lavra-work` - Execute work on a bead (captures raw knowledge inline)
+- `/lavra-checkpoint` - Save progress and sync state
+- `/lavra-recall` - Search knowledge base mid-session
+</handoff>