@lavralabs/lavra 0.7.0

package/plugins/lavra/docs/quickstart.md

@@ -0,0 +1,267 @@
+# Quick Start Guide
+
+## Installation
+
+```bash
+# From the plugin directory
+cd ~/Documents/projects/lavra
+./install.sh /path/to/your-project
+
+# Restart Claude Code
+```
+
+## Verify Installation
+
+```bash
+cd /path/to/your-project
+
+# Check that files were created
+ls -la .claude/hooks/        # Should see auto-recall.sh, memory-capture.sh
+ls -la .claude/commands/     # Should see lavra-*.md files
+ls -la .lavra/memory/        # Should see knowledge.jsonl, recall.sh
+```
+
+## Configuration
+
+### Workflow config (automatic)
+
+The installer creates `.lavra/config/lavra.json` with default settings. Edit to toggle:
+- `workflow.research` -- skip research phase in `/lavra-design`
+- `workflow.plan_review` -- skip plan review phase in `/lavra-design`
+- `workflow.goal_verification` -- skip goal verification in `/lavra-work` and `/lavra-ship`
+- `execution.max_parallel_agents` -- limit parallel subagents (default: 3)
+- `execution.commit_granularity` -- `"task"` (default, atomic) or `"wave"` (legacy)
+
+Existing projects get this file automatically on next session start (version self-heal).
+
+### Codebase analysis (optional, for brownfield projects)
+
+If you're installing lavra into an existing project, run `/project-setup` to generate a codebase profile:
+
+```
+/project-setup
+```
+
+When prompted "Run codebase analysis?", choose Y. This dispatches 3 parallel agents to analyze your stack, architecture, and conventions, saving the results to `.lavra/config/codebase-profile.md`. This file is used by `/lavra-design` and `/lavra-work` as planning context.
+
+## Your First Workflow
+
+### 1. Create a bead
+
+```bash
+bd create "Add user profile page" -d "Display user info with edit capability"
+# Returns: BD-001
+```
+
+### 2. Plan it (optional but recommended)
+
+```
+/lavra-plan BD-001
+```
+
+This dispatches research agents to gather:
+- Best practices for profile pages
+- Framework documentation
+- Existing patterns in your codebase
+
+Creates child beads for each step.
+
+### 3. Work on it
+
+```
+/lavra-work BD-001.1
+```
+
+This:
+- Shows you relevant knowledge automatically
+- Updates status to in_progress
+- Offers investigation if you want it
+
+### 4. Implement
+
+Just code normally:
+```bash
+# Edit files
+# Make commits
+```
+
+### 5. Log learnings
+
+```bash
+bd comments add BD-001.1 "LEARNED: Profile images should be lazy-loaded for performance"
+bd comments add BD-001.1 "DECISION: Using Gravatar for default avatars"
+bd comments add BD-001.1 "FACT: Max upload size is 5MB (nginx limit)"
+```
+
+These get auto-captured to `.lavra/memory/knowledge.jsonl`.
+
+### 6. Review
+
+```
+/lavra-review BD-001.1
+```
+
+This dispatches multiple reviewers:
+- Security audit
+- Performance check
+- Code quality review
+- Architecture validation
+
+Creates follow-up beads for any issues found.
+
+### 7. Close
+
+```bash
+bd close BD-001.1
+```
+
+## Next Session
+
+When you start a new session:
+
+1. The `auto-recall` hook runs automatically
+2. It sees you have open beads
+3. It searches knowledge for relevant entries
+4. Injects them as context
+
+You get relevant learnings without manually searching!
+
+## Available Commands
+
+| Command | Use When |
+|---------|----------|
+| `/lavra-plan {id or desc}` | Starting a complex feature, need research |
+| `/lavra-work {id}` | Starting work on a bead |
+| `/lavra-review {id}` | Before closing a bead, want multi-agent review |
+| `/lavra-research {id or question}` | Need deep understanding before implementing |
+| `/lavra-checkpoint` | Want to save progress during long session |
+
+## Manual Knowledge Search
+
+```bash
+# Search by keyword
+.lavra/memory/recall.sh "authentication"
+
+# Show recent
+.lavra/memory/recall.sh --recent 10
+
+# Show stats
+.lavra/memory/recall.sh --stats
+
+# Filter by type
+.lavra/memory/recall.sh "jwt" --type learned
+```
+
+## Example: Full Feature Flow
+
+```bash
+# Day 1: Research and planning
+bd create "Add two-factor authentication" -d "TOTP-based 2FA with QR codes"
+# => BD-050
+
+/lavra-plan BD-050
+# Researches best practices, security considerations, framework options
+# Creates child beads:
+#   BD-050.1: Database schema for OTP secrets
+#   BD-050.2: QR code generation endpoint
+#   BD-050.3: Verification endpoint
+#   BD-050.4: Settings UI
+
+# Day 2: Implement first step
+/lavra-work BD-050.1
+# Auto-recalls security knowledge from yesterday's research
+
+# Edit files, create migration
+git add -A
+git commit -m "Add OTP secrets table"
+
+bd comments add BD-050.1 "LEARNED: OTP secrets MUST be encrypted at rest"
+bd comments add BD-050.1 "DECISION: Using rotp gem for TOTP generation"
+bd comments add BD-050.1 "FACT: Backup codes needed for account recovery"
+
+/lavra-review BD-050.1
+# Security review catches missing index on user_id
+# Creates BD-051: Add index to otp_secrets.user_id
+
+# Fix the issue
+git add -A
+git commit -m "Add index to otp_secrets.user_id"
+bd close BD-051
+
+bd close BD-050.1
+
+# Continue with BD-050.2...
+```
+
+## Tips
+
+1. **Log liberally**: Every insight is valuable. Future you will thank you.
+
+2. **Use prefixes consistently**:
+   - `LEARNED:` - Technical insights, gotchas, discoveries
+   - `DECISION:` - Choices made and why
+   - `FACT:` - Constraints, requirements, environment details
+   - `PATTERN:` - Coding patterns, conventions, idioms
+   - `INVESTIGATION:` - Root cause analysis, how things work
+   - `DEVIATION:` - Auto-fixes applied outside bead scope
+
+3. **Review before closing**: `/lavra-review` catches issues early
+
+4. **Plan complex features**: `/lavra-plan` prevents rework by researching upfront
+
+5. **Checkpoint long sessions**: `/lavra-checkpoint` saves progress without losing context
+
+6. **Trust auto-recall**: Knowledge will be injected when relevant, no need to search manually
+
+## Troubleshooting
+
+### Knowledge not appearing at session start
+
+```bash
+# Check if knowledge exists
+.lavra/memory/recall.sh --stats
+
+# Check if hook is installed
+ls -la .claude/hooks/auto-recall.sh
+
+# Check if hook is configured
+cat .claude/settings.json | jq '.hooks.SessionStart'
+```
+
+### Commands not showing up
+
+```bash
+# Check if commands are installed
+ls -la .claude/commands/lavra-*.md
+
+# Restart Claude Code (required after installation)
+```
+
+### Agents not found
+
+The plugin references compound-engineering agents but doesn't install them. If you don't have compound-engineering installed, the agent dispatches in commands will fail. You can either:
+
+1. Install compound-engineering plugin
+2. Or modify the commands to use different agent names
+3. Or just use basic beads workflow without the agent commands
+
+## Uninstall
+
+```bash
+cd ~/Documents/projects/lavra
+./uninstall.sh /path/to/your-project
+```
+
+This removes the plugin but **preserves**:
+- `.beads/` directory
+- All your beads
+- `knowledge.jsonl` with all accumulated knowledge
+
+## Next Steps
+
+Once you're comfortable with the basic workflow:
+
+1. Read the full [README.md](README.md) for all features
+2. Check [COMPARISON.md](../COMPARISON.md) to understand vs semantic-beads
+3. Customize the commands in `.claude/commands/` for your workflow
+4. Add custom tags to `.claude/hooks/memory-capture.sh` for better search

package/plugins/lavra/examples/example-plan.md

@@ -0,0 +1,197 @@
+# Add Two-Factor Authentication
+
+Add TOTP-based two-factor authentication to protect user accounts.
+
+## Background
+
+Users have requested 2FA for enhanced security. Current authentication is username/password only, which is vulnerable to credential stuffing attacks.
+
+Market research shows 73% of competitors offer 2FA, and it's becoming table stakes for security-conscious users.
+
+## Research
+
+**TOTP (Time-based One-Time Password)**
+- RFC 6238 standard
+- 6-digit codes that rotate every 30 seconds
+- Compatible with Google Authenticator, Authy, 1Password, etc.
+- More secure than SMS-based 2FA (no SIM swapping vulnerability)
+
+**Ruby gems available**:
+- `rotp` - TOTP generation and verification (8.3k downloads/week)
+- `rqrcode` - QR code generation for setup (1.2M downloads/week)
+
+**Security considerations**:
+- OTP secrets MUST be encrypted at rest
+- Backup codes needed for account recovery (10 single-use codes)
+- Rate limiting on verification attempts (max 3 failures, then lockout)
+- Must support account recovery flow if user loses device
+
+## Decisions
+
+**Choice: TOTP over SMS**
+- TOTP is more secure (no SIM swapping vulnerability)
+- Works offline (no dependency on SMS delivery)
+- Better UX (no waiting for SMS, works internationally)
+- Industry best practice per NIST guidelines
+
+**Choice: Required for admins, optional for users**
+- Admins handle sensitive operations, require 2FA
+- Users can opt-in for enhanced security
+- Gradual rollout reduces support burden
+
+**Choice: Using rotp + rqrcode gems**
+- Battle-tested libraries
+- Active maintenance
+- Simple API
+
+## Implementation Steps
+
+### Step 1: Database Schema
+
+Create `otp_secrets` table:
+- user_id (indexed, unique)
+- encrypted_secret (encrypted with Rails credentials)
+- backup_codes (jsonb array, encrypted)
+- enabled_at (timestamp)
+- last_used_at (timestamp)
+
+Migration checklist:
+- Add foreign key constraint to users
+- Add index on user_id
+- Encrypt secret column using lockbox or similar
+- Add validation for backup codes format
+
+### Step 2: OTP Secret Generation
+
+Create `OtpService` to handle:
+- Generate secure random secret (Base32 encoded)
+- Encrypt and store secret
+- Generate 10 backup codes (random 8-char alphanumeric)
+- Return QR code provisioning URI for authenticator apps
+
+API:
+```ruby
+OtpService.enable_for_user(user)
+# => { qr_code_uri: "otpauth://...", backup_codes: [...] }
+```
+
+### Step 3: QR Code Display Endpoint
+
+Create `Settings::TwoFactorController#new`:
+- GET /settings/two_factor/setup
+- Generates OTP secret via OtpService
+- Renders QR code using rqrcode
+- Shows backup codes (one-time display)
+- User must verify before enabling
+
+Response includes:
+- QR code image (SVG for crispness)
+- Manual entry key (for apps that don't scan QR)
+- 10 backup codes to save
+
+### Step 4: Verification Endpoint
+
+Create `Settings::TwoFactorController#create`:
+- POST /settings/two_factor/verify
+- Accepts 6-digit OTP code
+- Verifies against stored secret using rotp
+- Enables 2FA on success
+- Rate limits: max 3 attempts, 5-minute lockout
+
+Error cases:
+- Invalid code (wrong digits)
+- Expired code (clock drift tolerance: 30 seconds)
+- Rate limit exceeded
+- Secret not found
+
+### Step 5: Login Flow Integration
+
+Modify `SessionsController#create`:
+- After successful password authentication
+- If user has 2FA enabled, redirect to 2FA verification
+- Session marked as "partial" (authenticated but not 2FA verified)
+- Must verify OTP before full session granted
+
+Add `SessionsController#verify_otp`:
+- POST /sessions/verify_otp
+- Accepts 6-digit code or backup code
+- Verifies and completes login
+- Invalidates backup code if used
+- Rate limits: max 3 attempts, 5-minute lockout
+
+### Step 6: Settings UI
+
+Add 2FA section to user settings:
+- Show status (enabled/disabled)
+- Enable button → goes to setup flow
+- Disable button (requires password confirmation)
+- Regenerate backup codes option
+- View recovery options
+
+UI includes:
+- Clear status indicator (badge/icon)
+- Setup instructions
+- Troubleshooting help link
+
+### Step 7: Account Recovery Flow
+
+Add recovery mechanism for lost devices:
+- User can disable 2FA via email confirmation link
+- Requires password + email verification
+- Notifies user via email when 2FA is disabled
+- Logs security event for audit trail
+
+Security:
+- Email link expires in 1 hour
+- Single use only
+- Requires password entry after clicking link
+- Rate limited: max 3 requests per day
+
+## Testing Checklist
+
+- [ ] Setup flow generates valid TOTP secret
+- [ ] QR code scannable by Google Authenticator
+- [ ] Backup codes work for login
+- [ ] Backup codes invalidated after use
+- [ ] Rate limiting prevents brute force
+- [ ] Clock drift handled (30-second window)
+- [ ] Account recovery flow works
+- [ ] Email notifications sent correctly
+- [ ] Admin 2FA enforcement works
+- [ ] User opt-in works
+
+## Rollout Plan
+
+**Phase 1: Internal testing (Week 1)**
+- Deploy to staging
+- Team members test with their accounts
+- Validate all edge cases
+
+**Phase 2: Admins required (Week 2)**
+- Require all admin accounts to enable 2FA
+- Support team prepares for user questions
+- Monitor for issues
+
+**Phase 3: User opt-in (Week 3)**
+- Announce feature to all users
+- Settings page shows option
+- Monitor adoption rate
+
+**Phase 4: Encourage adoption (Week 4+)**
+- In-app banners for high-value accounts
+- Email campaign explaining benefits
+- Track metrics: adoption rate, support tickets
+
+## Success Metrics
+
+- 100% admin adoption within 1 week
+- 25% user adoption within 1 month
+- <5 support tickets per 1000 users
+- Zero account takeovers on 2FA-enabled accounts
+
+## Dependencies
+
+- Rails 7.0+ (has encrypted attributes built-in)
+- rotp gem
+- rqrcode gem
+- Email delivery working (for recovery flow)

package/plugins/lavra/gemini/agents/design/design-implementation-reviewer.md

@@ -0,0 +1,130 @@
+<!-- Generated by lavra v0.6.0 -->
+<!-- Source: design/design-implementation-reviewer.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: design-implementation-reviewer
+description: Verifies UI implementations match Figma design specifications. Use after HTML/CSS/React components are created or modified to compare implementation against Figma and identify discrepancies.
+kind: local
+model: gemini-2.5-pro
+max_turns: 30
+timeout_mins: 10
+---
+<examples>
+<example>
+  Context: The user has just implemented a new component based on a Figma design.
+  user: "I've finished implementing the hero section based on the Figma design"
+  assistant: "I'll review how well your implementation matches the Figma design."
+  <commentary>
+  Since UI implementation has been completed, use the design-implementation-reviewer agent to compare the live version with Figma.
+  </commentary>
+  </example>
+
+<example>
+  Context: After the general code agent has implemented design changes.
+  user: "Update the button styles to match the new design system"
+  assistant: "I've updated the button styles. Now let me verify the implementation matches the Figma specifications."
+  <commentary>
+  After implementing design changes, proactively use the design-implementation-reviewer to ensure accuracy.
+  </commentary>
+  </example>
+</examples>
+
+<role>
+You are an expert UI/UX implementation reviewer specializing in ensuring pixel-perfect fidelity between Figma designs and live implementations. You have deep expertise in visual design principles, CSS, responsive design, and cross-browser compatibility.
+</role>
+
+<process>
+
+1. **Capture Implementation State**
+   - Use agent-browser CLI to capture screenshots of the implemented UI
+   - Test different viewport sizes if the design includes responsive breakpoints
+   - Capture interactive states (hover, focus, active) when relevant
+   - Document the URL and selectors of the components being reviewed
+
+   ```bash
+   agent-browser open [url]
+   agent-browser snapshot -i
+   agent-browser screenshot output.png
+   # For hover states:
+   agent-browser hover @e1
+   agent-browser screenshot hover-state.png
+   ```
+
+2. **Retrieve Design Specifications**
+   - Use the Figma MCP to access the corresponding design files
+   - Extract design tokens (colors, typography, spacing, shadows)
+   - Identify component specifications and design system rules
+   - Note any design annotations or developer handoff notes
+
+3. **Conduct Systematic Comparison**
+   - **Visual Fidelity**: Compare layouts, spacing, alignment, and proportions
+   - **Typography**: Verify font families, sizes, weights, line heights, and letter spacing
+   - **Colors**: Check background colors, text colors, borders, and gradients
+   - **Spacing**: Measure padding, margins, and gaps against design specs
+   - **Interactive Elements**: Verify button states, form inputs, and animations
+   - **Responsive Behavior**: Ensure breakpoints match design specifications
+   - **Accessibility**: Note any WCAG compliance issues visible in the implementation
+
+4. **Generate Structured Review**
+   Structure your review as follows:
+   ```
+   ## Design Implementation Review
+
+   ### Correctly Implemented
+   - [List elements that match the design perfectly]
+
+   ### Minor Discrepancies
+   - [Issue]: [Current implementation] vs [Expected from Figma]
+     - Impact: [Low/Medium]
+     - Fix: [Specific CSS/code change needed]
+
+   ### Major Issues
+   - [Issue]: [Description of significant deviation]
+     - Impact: High
+     - Fix: [Detailed correction steps]
+
+   ### Measurements
+   - [Component]: Figma: [value] | Implementation: [value]
+
+   ### Recommendations
+   - [Suggestions for improving design consistency]
+   ```
+
+5. **Provide Actionable Fixes**
+   - Include specific CSS properties and values that need adjustment
+   - Reference design tokens from the design system when applicable
+   - Suggest code snippets for complex fixes
+   - Prioritize fixes based on visual impact and user experience
+
+</process>
+
+## Important Guidelines
+
+- **Be Precise**: Use exact pixel values, hex codes, and specific CSS properties
+- **Consider Context**: Some variations might be intentional (e.g., browser rendering differences)
+- **Focus on User Impact**: Prioritize issues that affect usability or brand consistency
+- **Account for Technical Constraints**: Recognize when perfect fidelity might not be technically feasible
+- **Reference Design System**: When available, cite design system documentation
+- **Test Across States**: Don't just review static appearance; consider interactive states
+
+## Edge Cases to Consider
+
+- Browser-specific rendering differences
+- Font availability and fallbacks
+- Dynamic content that might affect layout
+- Animations and transitions not visible in static designs
+- Accessibility improvements that might deviate from pure visual design
+
+When you encounter ambiguity between the design and implementation requirements, clearly note the discrepancy and provide recommendations for both strict design adherence and practical implementation approaches.
+
+<success_criteria>
+- Screenshots captured at all relevant viewport sizes and interactive states
+- Design tokens (colors, typography, spacing) compared with exact values
+- Discrepancies categorized by severity (minor vs major) with specific CSS fixes
+- Responsive breakpoints verified against design specifications
+- Accessibility issues noted where implementation deviates from WCAG compliance
+- Review structured with Correctly Implemented, Minor Discrepancies, and Major Issues sections
+</success_criteria>
+
+Your goal is to ensure the implementation delivers the intended user experience while maintaining design consistency and technical excellence.