@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/file-todos/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: file-todos
+description: "This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes."
+disable-model-invocation: true
+---
+
+# File-Based Todo Tracking Skill
+
+## Overview
+
+The `todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
+
+This skill should be used when:
+- Creating new todos from findings or feedback
+- Managing todo lifecycle (pending → ready → complete)
+- Triaging pending items for approval
+- Checking or managing dependencies
+- Converting PR comments or code findings into tracked work
+- Updating work logs during todo execution
+
+## File Naming Convention
+
+Todo files follow this naming pattern:
+
+```
+{issue_id}-{status}-{priority}-{description}.md
+```
+
+**Components:**
+- **issue_id**: Sequential number (001, 002, 003...) - never reused
+- **status**: `pending` (needs triage), `ready` (approved), `complete` (done)
+- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have)
+- **description**: kebab-case, brief description
+
+**Examples:**
+```
+001-pending-p1-mailer-test.md
+002-ready-p1-fix-n-plus-1.md
+005-complete-p2-refactor-csv.md
+```
+
+## File Structure
+
+Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
+
+**Required sections:**
+- **Problem Statement** - What is broken, missing, or needs improvement?
+- **Findings** - Investigation results, root cause, key discoveries
+- **Proposed Solutions** - Multiple options with pros/cons, effort, risk
+- **Recommended Action** - Clear plan (filled during triage)
+- **Acceptance Criteria** - Testable checklist items
+- **Work Log** - Chronological record with date, actions, learnings
+
+**Optional sections:**
+- **Technical Details** - Affected files, related components, DB changes
+- **Resources** - Links to errors, tests, PRs, documentation
+- **Notes** - Additional context or decisions
+
+**YAML frontmatter fields:**
+```yaml
+---
+status: ready              # pending | ready | complete
+priority: p1              # p1 | p2 | p3
+issue_id: "002"
+tags: [rails, performance, database]
+dependencies: ["001"]     # Issue IDs this is blocked by
+---
+```
+
+## Common Workflows
+
+### Creating a New Todo
+
+**To create a new todo from findings or feedback:**
+
+1. Determine next issue ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1`
+2. Copy template: `cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md`
+3. Edit and fill required sections:
+   - Problem Statement
+   - Findings (if from investigation)
+   - Proposed Solutions (multiple options)
+   - Acceptance Criteria
+   - Add initial Work Log entry
+4. Determine status: `pending` (needs triage) or `ready` (pre-approved)
+5. Add relevant tags for filtering
+
+**When to create a todo:**
+- Requires more than 15-20 minutes of work
+- Needs research, planning, or multiple approaches considered
+- Has dependencies on other work
+- Requires manager approval or prioritization
+- Part of larger feature or refactor
+- Technical debt needing documentation
+
+**When to act immediately instead:**
+- Issue is trivial (< 15 minutes)
+- Complete context available now
+- No planning needed
+- User explicitly requests immediate action
+- Simple bug fix with obvious solution
+
+### Triaging Pending Items
+
+**To triage pending todos:**
+
+1. List pending items: `ls todos/*-pending-*.md`
+2. For each todo:
+   - Read Problem Statement and Findings
+   - Review Proposed Solutions
+   - Make decision: approve, defer, or modify priority
+3. Update approved todos:
+   - Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md`
+   - Update frontmatter: `status: pending` → `status: ready`
+   - Fill "Recommended Action" section with clear plan
+   - Adjust priority if different from initial assessment
+4. Deferred todos stay in `pending` status
+
+**Use slash command:** `/triage` for interactive approval workflow
+
+### Managing Dependencies
+
+**To track dependencies:**
+
+```yaml
+dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
+dependencies: []               # No blockers - can work immediately
+```
+
+**To check what blocks a todo:**
+```bash
+grep "^dependencies:" todos/003-*.md
+```
+
+**To find what a todo blocks:**
+```bash
+grep -l 'dependencies:.*"002"' todos/*.md
+```
+
+**To verify blockers are complete before starting:**
+```bash
+for dep in 001 002 003; do
+  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
+done
+```
+
+### Updating Work Logs
+
+**When working on a todo, always add a work log entry:**
+
+```markdown
+### YYYY-MM-DD - Session Title
+
+**By:** Claude Code / Developer Name
+
+**Actions:**
+- Specific changes made (include file:line references)
+- Commands executed
+- Tests run
+- Results of investigation
+
+**Learnings:**
+- What worked / what didn't
+- Patterns discovered
+- Key insights for future work
+```
+
+Work logs serve as:
+- Historical record of investigation
+- Documentation of approaches attempted
+- Knowledge sharing for team
+- Context for future similar work
+
+### Completing a Todo
+
+**To mark a todo as complete:**
+
+1. Verify all acceptance criteria checked off
+2. Update Work Log with final session and results
+3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md`
+4. Update frontmatter: `status: ready` → `status: complete`
+5. Check for unblocked work: `grep -l 'dependencies:.*"002"' todos/*-ready-*.md`
+6. Commit with issue reference: `feat: resolve issue 002`
+
+## Integration with Development Workflows
+
+| Trigger | Flow | Tool |
+|---------|------|------|
+| Code review | `/workflows:review` → Findings → `/triage` → Todos | Review agent + skill |
+| PR comments | `/resolve_pr_parallel` → Individual fixes → Todos | gh CLI + skill |
+| Code TODOs | `/resolve_todo_parallel` → Fixes + Complex todos | Agent + skill |
+| Planning | Brainstorm → Create todo → Work → Complete | Skill |
+| Feedback | Discussion → Create todo → Triage → Work | Skill + slash |
+
+## Quick Reference Commands
+
+**Finding work:**
+```bash
+# List highest priority unblocked work
+grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md
+
+# List all pending items needing triage
+ls todos/*-pending-*.md
+
+# Find next issue ID
+ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'
+
+# Count by status
+for status in pending ready complete; do
+  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
+done
+```
+
+**Dependency management:**
+```bash
+# What blocks this todo?
+grep "^dependencies:" todos/003-*.md
+
+# What does this todo block?
+grep -l 'dependencies:.*"002"' todos/*.md
+```
+
+**Searching:**
+```bash
+# Search by tag
+grep -l "tags:.*rails" todos/*.md
+
+# Search by priority
+ls todos/*-p1-*.md
+
+# Full-text search
+grep -r "payment" todos/
+```
+
+## Key Distinctions
+
+**File-todos system (this skill):**
+- Markdown files in `todos/` directory
+- Development/project tracking
+- Standalone markdown files with YAML frontmatter
+- Used by humans and agents
+
+**Rails Todo model:**
+- Database model in `app/models/todo.rb`
+- User-facing feature in the application
+- Active Record CRUD operations
+- Different from this file-based system
+
+**TaskCreate/TaskUpdate/TaskList tools:**
+- In-memory task tracking during agent sessions
+- Temporary tracking for single conversation
+- Not persisted to disk
+- Different from both systems above

package/plugins/lavra/skills/file-todos/assets/todo-template.md

@@ -0,0 +1,155 @@
+---
+status: pending
+priority: p2
+issue_id: "XXX"
+tags: []
+dependencies: []
+---
+
+# Brief Task Title
+
+Replace with a concise title describing what needs to be done.
+
+## Problem Statement
+
+What is broken, missing, or needs improvement? Provide clear context about why this matters.
+
+**Example:**
+- Template system lacks comprehensive test coverage for edge cases discovered during PR review
+- Email service is missing proper error handling for rate-limit scenarios
+- Documentation doesn't cover the new authentication flow
+
+## Findings
+
+Investigation results, root cause analysis, and key discoveries.
+
+- Finding 1 (with specifics: file, line number if applicable)
+- Finding 2
+- Key discovery with impact assessment
+- Related issues or patterns discovered
+
+**Example format:**
+- Identified 12 missing test scenarios in `app/models/user_test.rb`
+- Current coverage: 60% of code paths
+- Missing: empty inputs, special characters, large payloads
+- Similar issues exist in `app/models/post_test.rb` (~8 scenarios)
+
+## Proposed Solutions
+
+Present multiple options with pros, cons, effort estimates, and risk assessment.
+
+### Option 1: [Solution Name]
+
+**Approach:** Describe the solution clearly.
+
+**Pros:**
+- Benefit 1
+- Benefit 2
+
+**Cons:**
+- Drawback 1
+- Drawback 2
+
+**Effort:** 2-3 hours
+
+**Risk:** Low / Medium / High
+
+---
+
+### Option 2: [Solution Name]
+
+**Approach:** Describe the solution clearly.
+
+**Pros:**
+- Benefit 1
+- Benefit 2
+
+**Cons:**
+- Drawback 1
+- Drawback 2
+
+**Effort:** 4-6 hours
+
+**Risk:** Low / Medium / High
+
+---
+
+### Option 3: [Solution Name]
+
+(Include if you have alternatives)
+
+## Recommended Action
+
+**To be filled during triage.** Clear, actionable plan for resolving this todo.
+
+**Example:**
+"Implement both unit tests (covering each scenario) and integration tests (full pipeline) before merging. Estimated 4 hours total effort. Target coverage > 85% for this module."
+
+## Technical Details
+
+Affected files, related components, database changes, or architectural considerations.
+
+**Affected files:**
+- `app/models/user.rb:45` - full_name method
+- `app/services/user_service.rb:12` - validation logic
+- `test/models/user_test.rb` - existing tests
+
+**Related components:**
+- UserMailer (depends on user validation)
+- AccountPolicy (authorization checks)
+
+**Database changes (if any):**
+- Migration needed? Yes / No
+- New columns/tables? Describe here
+
+## Resources
+
+Links to errors, tests, PRs, documentation, similar issues.
+
+- **PR:** #1287
+- **Related issue:** #456
+- **Error log:** [link to AppSignal incident]
+- **Documentation:** [relevant docs]
+- **Similar patterns:** Issue #200 (completed, ref for approach)
+
+## Acceptance Criteria
+
+Testable checklist items for verifying completion.
+
+- [ ] All acceptance criteria checked
+- [ ] Tests pass (unit + integration if applicable)
+- [ ] Code reviewed and approved
+- [ ] (Example) Test coverage > 85%
+- [ ] (Example) Performance metrics acceptable
+- [ ] (Example) Documentation updated
+
+## Work Log
+
+Chronological record of work sessions, actions taken, and learnings.
+
+### 2025-11-12 - Initial Discovery
+
+**By:** Claude Code
+
+**Actions:**
+- Identified 12 missing test scenarios
+- Analyzed existing test coverage (file:line references)
+- Reviewed similar patterns in codebase
+- Drafted 3 solution approaches
+
+**Learnings:**
+- Similar issues exist in related modules
+- Current test setup supports both unit and integration tests
+- Performance testing would be valuable addition
+
+---
+
+(Add more entries as work progresses)
+
+## Notes
+
+Additional context, decisions, or reminders.
+
+- Decision: Include both unit and integration tests for comprehensive coverage
+- Blocker: Depends on completion of issue #001
+- Timeline: Priority for sprint due to blocking other work

package/plugins/lavra/skills/git-worktree/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: git-worktree
+description: This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles.
+disable-model-invocation: true
+---
+
+# Git Worktree Manager
+
+This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.
+
+## What This Skill Does
+
+- **Create worktrees** from main branch with clear branch names
+- **List worktrees** with current status
+- **Switch between worktrees** for parallel work
+- **Clean up completed worktrees** automatically
+- **Interactive confirmations** at each step
+- **Automatic .gitignore management** for worktree directory
+- **Automatic .env file copying** from main repo to new worktrees
+
+## CRITICAL: Always Use the Manager Script
+
+**NEVER call `git worktree add` directly.** Always use the `worktree-manager.sh` script.
+
+The script handles critical setup that raw git commands don't:
+1. Copies `.env`, `.env.local`, `.env.test`, etc. from main repo
+2. Ensures `.worktrees` is in `.gitignore`
+3. Creates consistent directory structure
+
+```bash
+# CORRECT - Always use the script
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name
+
+# WRONG - Never do this directly
+git worktree add .worktrees/feature-name -b feature-name main
+```
+
+## When to Use This Skill
+
+Use this skill in these scenarios:
+
+1. **Code Review (`/workflows:review`)**: If NOT already on the target branch (PR branch or requested branch), offer worktree for isolated review
+2. **Feature Work (`/workflows:work`)**: Always ask if user wants parallel worktree or live branch work
+3. **Parallel Development**: When working on multiple features simultaneously
+4. **Cleanup**: After completing work in a worktree
+
+## How to Use
+
+### In Claude Code Workflows
+
+The skill is automatically called from `/workflows:review` and `/workflows:work` commands:
+
+```
+# For review: offers worktree if not on PR branch
+# For work: always asks - new branch or worktree?
+```
+
+### Manual Usage
+
+You can also invoke the skill directly from bash:
+
+```bash
+# Create a new worktree (copies .env files automatically)
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
+
+# List all worktrees
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
+
+# Switch to a worktree
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
+
+# Copy .env files to an existing worktree (if they weren't copied)
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login
+
+# Clean up completed worktrees
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
+```
+
+## Commands
+
+### `create <branch-name> [from-branch]`
+
+Creates a new worktree with the given branch name.
+
+**Options:**
+- `branch-name` (required): The name for the new branch and worktree
+- `from-branch` (optional): Base branch to create from (defaults to `main`)
+
+**Example:**
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
+```
+
+**What happens:**
+1. Checks if worktree already exists
+2. Updates the base branch from remote
+3. Creates new worktree and branch
+4. **Copies all .env files from main repo** (.env, .env.local, .env.test, etc.)
+5. Shows path for cd-ing to the worktree
+
+### `list` or `ls`
+
+Lists all available worktrees with their branches and current status.
+
+**Example:**
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
+```
+
+**Output shows:**
+- Worktree name
+- Branch name
+- Which is current (marked with checkmark)
+- Main repo status
+
+### `switch <name>` or `go <name>`
+
+Switches to an existing worktree and cd's into it.
+
+**Example:**
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
+```
+
+**Optional:**
+- If name not provided, lists available worktrees and prompts for selection
+
+### `cleanup` or `clean`
+
+Interactively cleans up inactive worktrees with confirmation.
+
+**Example:**
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
+```
+
+**What happens:**
+1. Lists all inactive worktrees
+2. Asks for confirmation
+3. Removes selected worktrees
+4. Cleans up empty directories
+
+## Workflow Examples
+
+### Code Review with Worktree
+
+```bash
+# Claude Code recognizes you're not on the PR branch
+# Offers: "Use worktree for isolated review? (y/n)"
+
+# You respond: yes
+# Script runs (copies .env files automatically):
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name
+
+# You're now in isolated worktree for review with all env vars
+cd .worktrees/pr-123-feature-name
+
+# After review, return to main:
+cd ../..
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
+```
+
+### Parallel Feature Development
+
+```bash
+# For first feature (copies .env files):
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
+
+# Later, start second feature (also copies .env files):
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications
+
+# List what you have:
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
+
+# Switch between them as needed:
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
+
+# Return to main and cleanup when done:
+cd .
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
+```
+
+## Key Design Principles
+
+### KISS (Keep It Simple, Stupid)
+
+- **One manager script** handles all worktree operations
+- **Simple commands** with sensible defaults
+- **Interactive prompts** prevent accidental operations
+- **Clear naming** using branch names directly
+
+### Opinionated Defaults
+
+- Worktrees always created from **main** (unless specified)
+- Worktrees stored in **.worktrees/** directory
+- Branch name becomes worktree name
+- **.gitignore** automatically managed
+
+### Safety First
+
+- **Confirms before creating** worktrees
+- **Confirms before cleanup** to prevent accidental removal
+- **Won't remove current worktree**
+- **Clear error messages** for issues
+
+## Integration with Workflows
+
+### `/workflows:review`
+
+Instead of always creating a worktree:
+
+```
+1. Check current branch
+2. If ALREADY on target branch (PR branch or requested branch) -> stay there, no worktree needed
+3. If DIFFERENT branch than the review target -> offer worktree:
+   "Use worktree for isolated review? (y/n)"
+   - yes -> call git-worktree skill
+   - no -> proceed with PR diff on current branch
+```
+
+### `/workflows:work`
+
+Always offer choice:
+
+```
+1. Ask: "How do you want to work?
+   1. New branch on current worktree (live work)
+   2. Worktree (parallel work)"
+
+2. If choice 1 -> create new branch normally
+3. If choice 2 -> call git-worktree skill to create from main
+```
+
+## Troubleshooting
+
+### "Worktree already exists"
+
+If you see this, the script will ask if you want to switch to it instead.
+
+### "Cannot remove worktree: it is the current worktree"
+
+Switch out of the worktree first (to main repo), then cleanup:
+
+```bash
+cd $(git rev-parse --show-toplevel)
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
+```
+
+### Lost in a worktree?
+
+See where you are:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
+```
+
+### .env files missing in worktree?
+
+If a worktree was created without .env files (e.g., via raw `git worktree add`), copy them:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-name
+```
+
+Navigate back to main:
+
+```bash
+cd $(git rev-parse --show-toplevel)
+```
+
+## Technical Details
+
+### Directory Structure
+
+```
+.worktrees/
+├── feature-login/          # Worktree 1
+│   ├── .git
+│   ├── app/
+│   └── ...
+├── feature-notifications/  # Worktree 2
+│   ├── .git
+│   ├── app/
+│   └── ...
+└── ...
+
+.gitignore (updated to include .worktrees)
+```
+
+### How It Works
+
+- Uses `git worktree add` for isolated environments
+- Each worktree has its own branch
+- Changes in one worktree don't affect others
+- Share git history with main repo
+- Can push from any worktree
+
+### Performance
+
+- Worktrees are lightweight (just file system links)
+- No repository duplication
+- Shared git objects for efficiency
+- Much faster than cloning or stashing/switching