@lavralabs/lavra 0.7.0

package/plugins/lavra/opencode/commands/lavra-compound.md

@@ -0,0 +1,168 @@
+<!-- Generated by lavra-compound v0.6.0 -->
+<!-- Source: lavra-compound.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: lavra-compound
+description: Document a recently solved problem to compound your team's knowledge
+argument-hint: "[optional: brief context about the fix or bead ID]"
+---
+
+<objective>
+Coordinate multiple subagents working in parallel to document a recently solved problem. Captures problem solutions while context is fresh, creating structured knowledge entries in `.lavra/memory/knowledge.jsonl` for searchability and future reference.
+</objective>
+
+<context>
+**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.
+
+**Usage:**
+```bash
+/lavra-compound                    # Document the most recent fix
+/lavra-compound BD-007             # Document solution for specific bead
+/lavra-compound [brief context]    # Provide additional context hint
+```
+
+**The Compounding Philosophy:**
+
+1. First time you solve "N+1 query in brief generation" -> Research (30 min)
+2. Document the solution -> knowledge.jsonl entries (5 min)
+3. Next time similar issue occurs -> Auto-recalled (instant)
+4. Knowledge compounds -> Team gets smarter
+
+**Each unit of engineering work should make subsequent units of work easier - not harder.**
+
+**Preconditions:**
+- Problem has been solved (not in-progress)
+- Solution has been verified working
+- Non-trivial problem (not simple typo or obvious error)
+</context>
+
+<guardrails>
+**Research subagents return TEXT DATA only - NO file writes.**
+
+Subagents in Phase 1 (research) must NOT use Write, Edit, or create any files. They analyze and return text data to the orchestrator. Only knowledge entries via `bd comments add` should be written (which triggers automatic capture via the memory-capture hook).
+</guardrails>
+
+<process>
+
+### 1. **Context Analyzer** (Parallel)
+   - Extracts conversation history
+   - Identifies problem type, component, symptoms
+   - If a bead ID is provided, reads bead details: `bd show {BEAD_ID}`
+   - Returns: knowledge entry skeleton (type, tags, content outline)
+
+### 2. **Solution Extractor** (Parallel)
+   - Analyzes all investigation steps
+   - Identifies root cause
+   - Extracts working solution with code examples
+   - Returns: Solution content block
+
+### 3. **Related Knowledge Finder** (Parallel)
+   - Searches `.lavra/memory/knowledge.jsonl` for related entries
+   - Identifies cross-references and links
+   - Finds related beads
+   - Returns: Links and relationships
+
+### 4. **Prevention Strategist** (Parallel)
+   - Develops prevention strategies
+   - Creates best practices guidance
+   - Generates test cases if applicable
+   - Returns: Prevention/testing content
+
+### 5. **Category Classifier** (Parallel)
+   - Determines optimal knowledge type (learned/decision/fact/pattern/investigation)
+   - Suggests tags based on content
+   - Returns: Type and tag recommendations
+
+### 6. **Knowledge Writer** (Parallel)
+   - Assembles complete knowledge entries
+   - Validates JSONL format
+   - Writes entries using `bd comments add` for auto-capture
+   - Creates the entries
+
+### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
+   Based on problem type detected, automatically invoke applicable agents:
+   - **performance_issue** -> `performance-oracle`
+   - **security_issue** -> `security-sentinel`
+   - **database_issue** -> `data-integrity-guardian`
+   - Any code-heavy issue -> `code-simplicity-reviewer`
+
+## What It Captures
+
+- **Problem symptom**: Exact error messages, observable behavior
+- **Investigation steps tried**: What didn't work and why
+- **Root cause analysis**: Technical explanation
+- **Working solution**: Step-by-step fix with code examples
+- **Prevention strategies**: How to avoid in future
+- **Cross-references**: Links to related beads and knowledge
+
+## Knowledge Entry Format
+
+All knowledge is logged via `bd comments add` which triggers the memory-capture hook:
+
+```bash
+# Root cause analysis
+bd comments add {BEAD_ID} "INVESTIGATION: {root cause explanation with technical details}"
+
+# Key learnings
+bd comments add {BEAD_ID} "LEARNED: {what worked, including code patterns}"
+
+# Important facts/constraints
+bd comments add {BEAD_ID} "FACT: {constraint, gotcha, or important detail}"
+
+# Patterns to follow
+bd comments add {BEAD_ID} "PATTERN: {coding pattern or convention that solved the problem}"
+
+# Decisions made
+bd comments add {BEAD_ID} "DECISION: {what was chosen and why, with alternatives considered}"
+```
+
+Each entry is auto-tagged based on content keywords and stored in `knowledge.jsonl`.
+
+</process>
+
+<success_criteria>
+- All 6 parallel subagents completed successfully
+- At least one knowledge entry per type (LEARNED, PATTERN, INVESTIGATION) created
+- Knowledge entries linked to the relevant bead
+- Root cause analysis documented
+- Prevention strategies captured
+- Related knowledge cross-referenced
+
+```
+Knowledge documentation complete!
+
+Primary Subagent Results:
+  - Context Analyzer: Identified {problem_type} in {component}
+  - Solution Extractor: Extracted {N} code fixes
+  - Related Knowledge Finder: Found {N} related entries
+  - Prevention Strategist: Generated test cases
+  - Category Classifier: Type: {type}, Tags: [{tags}]
+  - Knowledge Writer: Created {N} knowledge entries
+
+Specialized Agent Reviews (Auto-Triggered):
+  - {agent}: {finding}
+
+Knowledge entries created:
+  - LEARNED: {summary 1}
+  - PATTERN: {summary 2}
+  - INVESTIGATION: {summary 3}
+
+Linked to bead: {BEAD_ID}
+
+This knowledge will be searchable for future reference when similar
+issues occur.
+```
+</success_criteria>
+
+<handoff>
+What's next?
+1. Continue workflow (recommended)
+2. View knowledge entries: `.lavra/memory/recall.sh "{keyword}"`
+3. Other
+
+**Related Commands:**
+- `/lavra-plan` - Planning workflow (references documented knowledge)
+- `/lavra-checkpoint` - Quick knowledge capture during work
+- `/lavra-deepen` - Enhance plans with parallel research
+</handoff>

package/plugins/lavra/opencode/commands/lavra-deepen.md

@@ -0,0 +1,389 @@
+<!-- Generated by lavra-compound v0.6.0 -->
+<!-- Source: lavra-deepen.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: lavra-deepen
+description: Enhance a plan with parallel research agents for each section to add depth, best practices, and implementation details
+argument-hint: "[epic bead ID]"
+---
+
+<objective>
+Take an existing plan (from `/lavra-plan`) and enhance each section with parallel research agents. Each major element gets dedicated research to find best practices, performance optimizations, quality enhancements, edge cases, and real-world implementation examples. The result is a deeply grounded, production-ready plan with concrete implementation details.
+</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 would you like to deepen? Please provide the bead ID (e.g., `BD-001`)."
+
+Do not proceed until you have a valid epic bead ID.
+</execution_context>
+
+<context>
+**Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
+</context>
+
+<process>
+
+### 1. Parse and Analyze Plan Structure
+
+<thinking>
+First, read the epic bead and its children to identify each major section that can be enhanced with research.
+</thinking>
+
+**Read the epic and its children:**
+
+```bash
+# Read the epic
+bd show {EPIC_ID}
+
+# List all child beads
+bd list --parent {EPIC_ID} --json
+```
+
+**For each child bead, read its description:**
+
+```bash
+bd show {CHILD_ID}
+```
+
+**Extract from the plan:**
+- [ ] Overview/Problem Statement (from epic description)
+- [ ] Child bead titles and descriptions (implementation steps)
+- [ ] Technical approaches mentioned
+- [ ] Code examples and file references
+- [ ] Acceptance criteria
+- [ ] Any UI/UX components mentioned
+- [ ] Technologies/frameworks mentioned (Rails, React, Python, TypeScript, etc.)
+- [ ] Domain areas (data models, APIs, UI, security, performance, etc.)
+
+**Create a section manifest:**
+```
+Section 1: [Child bead title] - [Brief description of what to research]
+Section 2: [Child bead title] - [Brief description of what to research]
+...
+```
+
+### 2. Discover and Apply Available Skills
+
+<thinking>
+Dynamically discover all available skills and match them to plan sections. Don't assume what skills exist - discover them at runtime.
+</thinking>
+
+**Step 1: Discover ALL available skills from ALL sources**
+
+```bash
+# 1. Project-local skills (highest priority - project-specific)
+ls .claude/skills/
+
+# 2. User's global skills (~/.claude/)
+ls ~/.claude/skills/
+
+# 3. Plugin skills
+find ~/.claude/plugins/cache -type d -name "skills" 2>/dev/null
+
+# 4. Check installed_plugins.json for all plugin locations
+cat ~/.claude/plugins/installed_plugins.json
+```
+
+**Important:** Check EVERY source. Don't assume any single plugin is the only one. Use skills from ANY installed plugin that's relevant.
+
+**Step 2: For each discovered skill, read its SKILL.md to understand what it does**
+
+```bash
+# For each skill directory found, read its documentation
+cat [skill-path]/SKILL.md
+```
+
+**Step 3: Match skills to plan content**
+
+For each skill discovered:
+- Read its SKILL.md description
+- Check if any plan sections match the skill's domain
+- If there's a match, spawn a sub-agent to apply that skill's knowledge
+
+**Step 4: Spawn a sub-agent for EVERY matched skill**
+
+**CRITICAL: For EACH skill that matches, spawn a separate sub-agent and instruct it to USE that skill.**
+
+For each matched skill:
+```
+Task general-purpose: "You have the [skill-name] skill available at [skill-path].
+
+YOUR JOB: Use this skill on the plan.
+
+1. Read the skill: cat [skill-path]/SKILL.md
+2. Follow the skill's instructions exactly
+3. Apply the skill to this content:
+
+[relevant plan section or full plan]
+
+4. Return the skill's full output
+
+The skill tells you what to do - follow it. Execute the skill completely."
+```
+
+**Spawn ALL skill sub-agents in PARALLEL:**
+- 1 sub-agent per matched skill
+- Each sub-agent reads and uses its assigned skill
+- All run simultaneously
+- 10, 20, 30 skill sub-agents is fine
+
+### 3. Discover and Apply Learnings/Solutions
+
+<thinking>
+Check for documented learnings from knowledge.jsonl. These are solved problems stored as JSONL entries. Search for relevant learnings.
+</thinking>
+
+**Search for relevant learnings:**
+
+```bash
+# Search knowledge for each key topic in the plan
+.lavra/memory/recall.sh "{topic 1}"
+.lavra/memory/recall.sh "{topic 2}"
+.lavra/memory/recall.sh "{technology}"
+
+# Search with --all to include archived knowledge
+.lavra/memory/recall.sh --all "{broad topic}"
+```
+
+**For each relevant learning found, spawn a sub-agent:**
+
+```
+Task general-purpose: "
+LEARNING ENTRY: [key and content from knowledge.jsonl]
+
+Check if this learning applies to this plan:
+
+---
+[full plan content from epic + children]
+---
+
+If relevant:
+- Explain specifically how it applies
+- Quote the key insight or solution
+- Suggest where/how to incorporate it
+
+If NOT relevant after deeper analysis:
+- Say 'Not applicable: [reason]'
+"
+```
+
+**Spawn sub-agents in PARALLEL for all relevant learnings.**
+
+**These learnings are institutional knowledge - applying them prevents repeating past mistakes.**
+
+### 4. Launch Per-Section Research Agents
+
+<thinking>
+For each major section in the plan, spawn dedicated sub-agents to research improvements. Use the Explore agent type for open-ended research.
+</thinking>
+
+**For each identified section, launch parallel research:**
+
+```
+Task Explore: "Research best practices, patterns, and real-world examples for: [section topic].
+Find:
+- Industry standards and conventions
+- Performance considerations
+- Common pitfalls and how to avoid them
+- Documentation and tutorials
+Return concrete, actionable recommendations."
+```
+
+**Use WebSearch for current best practices:**
+
+Search for recent (2024-2026) articles, blog posts, and documentation on topics in the plan.
+
+### 5. Discover and Run ALL Review Agents
+
+<thinking>
+Dynamically discover every available agent and run them ALL against the plan. Don't filter, don't skip, don't assume relevance. 40+ parallel agents is fine. Use everything available.
+</thinking>
+
+**Step 1: Discover ALL available agents from ALL sources**
+
+```bash
+# 1. Project-local agents (highest priority - project-specific)
+find .claude/agents -name "*.md" 2>/dev/null
+
+# 2. User's global agents (~/.claude/)
+find ~/.claude/agents -name "*.md" 2>/dev/null
+
+# 3. Plugin agents
+find ~/.claude/plugins/cache -path "*/agents/*.md" 2>/dev/null
+
+# 4. Check installed_plugins.json to find all plugin locations
+cat ~/.claude/plugins/installed_plugins.json
+```
+
+**For review/research/design/docs agents only (SKIP workflow agents):**
+
+**Step 2: Launch ALL agents in parallel**
+
+For EVERY agent discovered, launch a Task in parallel:
+
+```
+Task [agent-name]: "Review this plan using your expertise. Apply all your checks and patterns. Plan content: [full plan content]"
+```
+
+**CRITICAL RULES:**
+- Do NOT filter agents by "relevance" - run them ALL
+- Do NOT skip agents because they "might not apply" - let them decide
+- Launch ALL agents in a SINGLE message with multiple Task tool calls
+- 20, 30, 40 parallel agents is fine - use everything
+- Each agent may catch something others miss
+- The goal is MAXIMUM coverage, not efficiency
+
+### 6. Wait for ALL Agents and Synthesize Everything
+
+<thinking>
+Wait for ALL parallel agents to complete - skills, research agents, review agents, everything. Then synthesize all findings into a comprehensive enhancement.
+</thinking>
+
+**Collect outputs from ALL sources:**
+
+1. **Skill-based sub-agents** - Each skill's full output (code examples, patterns, recommendations)
+2. **Learnings sub-agents** - Relevant documented learnings from knowledge.jsonl
+3. **Research agents** - Best practices, documentation, real-world examples
+4. **Review agents** - All feedback from every reviewer (architecture, security, performance, simplicity, etc.)
+5. **Web searches** - Current best practices and articles
+
+**For each agent's findings, extract:**
+- [ ] Concrete recommendations (actionable items)
+- [ ] Code patterns and examples (copy-paste ready)
+- [ ] Anti-patterns to avoid (warnings)
+- [ ] Performance considerations (metrics, benchmarks)
+- [ ] Security considerations (vulnerabilities, mitigations)
+- [ ] Edge cases discovered (handling strategies)
+- [ ] Documentation links (references)
+- [ ] Skill-specific patterns (from matched skills)
+- [ ] Relevant learnings (past solutions that apply - prevent repeating mistakes)
+
+**Deduplicate and prioritize:**
+- Merge similar recommendations from multiple agents
+- Prioritize by impact (high-value improvements first)
+- Flag conflicting advice for human review
+- Group by child bead
+
+### 7. Enhance Child Bead Descriptions
+
+<thinking>
+Merge research findings back into each child bead, adding depth without changing the original structure.
+</thinking>
+
+**For each child bead, update its description:**
+
+```bash
+bd update {CHILD_ID} -d "## What
+
+[Original content preserved]
+
+## Context
+
+[Original context preserved]
+
+### Research Insights
+
+**Best Practices:**
+- [Concrete recommendation 1]
+- [Concrete recommendation 2]
+
+**Performance Considerations:**
+- [Optimization opportunity]
+- [Benchmark or metric to target]
+
+**Implementation Details:**
+[Concrete code examples from research]
+
+**Edge Cases:**
+- [Edge case 1 and how to handle]
+- [Edge case 2 and how to handle]
+
+**References:**
+- [Documentation URL 1]
+- [Documentation URL 2]
+
+## Testing
+
+[Original + enhanced testing criteria]
+
+## Validation
+
+[Original + enhanced validation criteria]
+
+## Dependencies
+
+[Original dependencies]"
+```
+
+**Log findings as knowledge comments:**
+
+```bash
+bd comments add {CHILD_ID} "INVESTIGATION: {key research finding for this step}"
+bd comments add {CHILD_ID} "PATTERN: {recommended pattern discovered}"
+bd comments add {CHILD_ID} "FACT: {constraint or gotcha from research}"
+```
+
+### 8. Add Enhancement Summary to Epic
+
+Update the epic bead description with a summary:
+
+```bash
+bd comments add {EPIC_ID} "INVESTIGATION: Plan deepened with research from [count] agents, [count] skills, and [count] learnings. Key improvements: [top 3 improvements]"
+```
+
+</process>
+
+<success_criteria>
+- [ ] All original content preserved in child beads
+- [ ] Every agent recommendation either applied or explicitly noted as inapplicable
+- [ ] Research insights clearly marked and attributed
+- [ ] No contradictions between sections
+- [ ] Enhancement summary accurately reflects changes
+
+**Completeness verification:**
+
+**Step 1: Build agent finding inventory**
+
+For each agent that ran, list the concrete recommendations it returned. Group by child bead:
+
+```
+BEAD {CHILD_ID}: {title}
+  From architecture-strategist: [recommendation 1]
+  From security-sentinel: [recommendation 2]
+  From performance-oracle: [recommendation 3]
+  ...
+```
+
+**Step 2: Verify each was applied**
+
+Re-read each updated child bead description (`bd show {CHILD_ID}`) and confirm each recommendation from the inventory above is reflected. If any are missing, apply them now.
+
+**Do not report completion until the inventory is fully accounted for.**
+</success_criteria>
+
+<guardrails>
+NEVER CODE! Just research and enhance the plan.
+</guardrails>
+
+<handoff>
+After updating all child beads, use the **AskUserQuestion tool** to present these options:
+
+**Question:** "Plan deepened for epic `{EPIC_ID}`. What would you like to do next?"
+
+**Options:**
+1. **Run `/lavra-eng-review`** - Get feedback from reviewers on enhanced plan
+2. **Start `/lavra-work`** - Begin implementing the first child bead
+3. **Deepen further** - Run another round of research on specific sections
+4. **View changes** - Show what was added to each child bead
+
+Based on selection:
+- **`/lavra-eng-review`** -> Call the /lavra-eng-review command with the epic bead ID
+- **`/lavra-work`** -> Call the /lavra-work command with the first ready child bead ID
+- **Deepen further** -> Ask which sections need more research, then re-run those agents
+- **View changes** -> Show before/after for each child bead
+</handoff>