@lavralabs/lavra 0.7.0

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

@@ -0,0 +1,330 @@
+---
+name: lavra-ship
+description: Fully automated ship sequence from code-ready to PR-open with beads closed and knowledge captured
+argument-hint: "[bead ID or branch name]"
+---
+
+<objective>
+Fully automated ship sequence. One command to go from "code is ready" to "PR is open, beads are closed, knowledge is captured." Procedural and deterministic -- every step either passes or the pipeline halts with a clear reason.
+</objective>
+
+<execution_context>
+<ship_target> #$ARGUMENTS </ship_target>
+
+<requirements>
+- Git repository with GitHub CLI (`gh`) installed and authenticated
+- `bd` CLI installed for bead management
+- Code changes already committed or staged (this is a ship command, not a work command)
+</requirements>
+</execution_context>
+
+<process>
+
+### Phase 1: Pre-Flight Checks
+
+Validate that the workspace is in a shippable state. Any failure here halts the pipeline.
+
+1. **Branch Safety**
+
+   ```bash
+   current_branch=$(git branch --show-current)
+   ```
+
+   If `current_branch` is `main` or `master`: HALT. Print "Cannot ship from main/master. Create a feature branch first." Do not proceed.
+
+2. **Working Tree Status**
+
+   ```bash
+   git status --porcelain
+   ```
+
+   If there are uncommitted changes:
+   - Show the list of modified/untracked files
+   - Ask: "There are uncommitted changes. Commit them now before shipping?"
+   - If yes: stage relevant files, create a commit with a conventional message
+   - If no: HALT. Print "Uncommitted changes must be resolved before shipping."
+
+3. **Bead Status**
+
+   If a bead ID was provided as argument, use that. Otherwise, detect from branch name or in-progress beads:
+
+   ```bash
+   # Try branch name first (bd-{ID}/... pattern)
+   bead_id=$(echo "$current_branch" | grep -oE 'bd-[a-z0-9-]+' | head -1)
+
+   # Fall back to in-progress beads
+   if [ -z "$bead_id" ]; then
+     bd list --status=in_progress --json | jq -r '.[].id'
+   fi
+   ```
+
+   If beads are still `in_progress`:
+   - List them with titles
+   - Warn: "These beads are still in_progress. They will be closed after the PR is created."
+   - Proceed (this is a warning, not a blocker)
+
+   If no beads are found: proceed without bead tracking (branch-only ship).
+
+### Phase 2: Sync with Upstream
+
+Rebase onto the latest default branch to avoid merge conflicts in the PR.
+
+```bash
+default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+if [ -z "$default_branch" ]; then
+  default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
+fi
+
+git fetch origin "$default_branch"
+git rebase "origin/$default_branch"
+```
+
+If rebase conflicts occur: HALT. Print the conflicting files and instruct:
+- "Rebase conflicts detected. Resolve conflicts, then run `git rebase --continue` and re-run /lavra-ship."
+
+Do not force-push. Do not skip the rebase.
+
+### Phase 3: Run Tests
+
+Auto-detect the project's test runner and execute it. If no test runner is found, skip with a note.
+
+**Detection order** (check for existence, run the first match):
+
+| Check | Command |
+|-------|---------|
+| `package.json` has `"test"` script | `npm test` or `yarn test` or `bun test` |
+| `package.json` has `"check"` script | `npm run check` |
+| `Makefile` has `test` target | `make test` |
+| `pytest.ini`, `pyproject.toml` with pytest, or `tests/` dir with Python files | `pytest` |
+| `Gemfile` with rspec or `spec/` dir | `bundle exec rspec` |
+| `Cargo.toml` | `cargo test` |
+| `go.mod` | `go test ./...` |
+| `.github/workflows/` with test jobs | Note: "CI will run tests. Skipping local test run." |
+
+```bash
+# Detect and run (pseudo-code -- implement the detection logic)
+```
+
+If tests fail: HALT. Print the failure output. Do not proceed -- broken code does not ship.
+
+If no test runner detected: print "No test runner detected. Skipping local tests." and proceed.
+
+### Phase 4: Pre-Landing Review Gate
+
+Run a lightweight review focused on ship-blockers only. This is NOT a full /lavra-review -- it checks for things that should never ship.
+
+**4a. Goal Verification** *(skippable via `lavra.json` `workflow.goal_verification: false`)*
+
+Read workflow config:
+```bash
+[ -f .lavra/config/lavra.json ] && cat .lavra/config/lavra.json
+```
+
+Parse `model_profile` from the config (default: `"balanced"`). For each bead being shipped that has a `## Validation` section, dispatch the `goal-verifier` agent. Add `model: opus` when `model_profile` is `"quality"`:
+
+```
+Task(goal-verifier, "Verify goal completion for {BEAD_ID}. Validation criteria: {validation section}. What section: {what section}.")
+-- add model: opus if profile=quality
+```
+
+**Interpret results:**
+- Exists-level failures → CRITICAL (halt the ship)
+- Substantive-level failures → CRITICAL (halt the ship)
+- Wired-level failures → WARNING (proceed but include in PR body)
+
+Store goal verification results for the PR body.
+
+**4b. Security & Quality Scan**
+
+Scan the diff for:
+
+```bash
+git diff "origin/$default_branch"...HEAD
+```
+
+**Check for these categories:**
+
+1. **Security issues**: hardcoded secrets, API keys, passwords, tokens, private keys in the diff
+2. **Debug leftovers**: `console.log`, `debugger`, `binding.pry`, `byebug`, `import pdb`, `print(` used for debugging, `TODO: remove`
+3. **Hardcoded values**: localhost URLs, hardcoded IPs, test credentials that should be environment variables
+4. **Unresolved conflicts**: `<<<<<<<`, `=======`, `>>>>>>>`
+
+**Severity classification:**
+
+- CRITICAL (halts the ship): secrets, unresolved conflicts, credentials
+- WARNING (noted but proceeds): debug leftovers, TODOs, hardcoded localhost
+
+If CRITICAL issues found: HALT. List each issue with file and line number. Print "Critical issues must be resolved before shipping."
+
+If only WARNING issues: print the warnings, then proceed. Include them in the PR description.
+
+### Phase 5: Create PR
+
+Generate the PR from the accumulated context.
+
+1. **Gather PR context**
+
+   ```bash
+   # Commits on this branch not in default branch
+   git log --oneline "origin/$default_branch"..HEAD
+
+   # Files changed
+   git diff --stat "origin/$default_branch"...HEAD
+
+   # Bead titles (if beads were found)
+   bd show {BEAD_ID} --json | jq -r '.title'
+   ```
+
+2. **Generate PR title**
+
+   - If single bead: use bead title, prefixed with bead ID
+   - If multiple beads: summarize the common theme
+   - If no beads: derive from branch name, converting hyphens to spaces
+   - Keep under 70 characters
+
+3. **Push and create PR**
+
+   ```bash
+   git push -u origin "$current_branch"
+
+   gh pr create --title "{generated title}" --body "$(cat <<'PRBODY'
+   ## Summary
+
+   {1-3 bullet points describing what changed and why}
+
+   ## Beads Addressed
+
+   {list of bead IDs and titles, or "N/A" if no beads}
+
+   ## Goal Verification
+
+   {goal-verifier results table, or "Skipped (no Validation sections)" or "Disabled via lavra.json"}
+
+   ## Deviations
+
+   {count} deviation(s) logged during implementation:
+   {list of DEVIATION: comments from beads, or "None"}
+
+   ## Test Results
+
+   {test runner output summary, or "No local test runner detected -- relying on CI"}
+
+   ## Review Notes
+
+   {any WARNING items from Phase 4, or "No issues detected"}
+
+   ## Changes
+
+   {git diff --stat summary}
+   PRBODY
+   )"
+   ```
+
+   Capture and store the PR URL from the output.
+
+### Phase 6: Close Beads and Capture Knowledge
+
+For each bead that was in_progress:
+
+1. **Check for knowledge comments**
+
+   ```bash
+   bd show {BEAD_ID} | grep -cE "LEARNED:|DECISION:|FACT:|PATTERN:|INVESTIGATION:|DEVIATION:"
+   ```
+
+   If zero knowledge comments exist on the bead: log at least one before closing.
+
+   ```bash
+   bd comments add {BEAD_ID} "LEARNED: {most significant insight from the work}"
+   ```
+
+2. **Close the bead**
+
+   ```bash
+   bd close {BEAD_ID} --reason="Shipped in PR {PR_URL}"
+   ```
+
+3. **Check for compound-worthy findings**
+
+   ```bash
+   bd show {BEAD_ID} | grep -cE "LEARNED:|INVESTIGATION:"
+   ```
+
+   If LEARNED or INVESTIGATION comments exist, note this for the summary -- the user may want to run /lavra-compound later to extract reusable knowledge.
+
+### Phase 7: Push Beads Backup
+
+Persist the bead state so it survives across machines and sessions.
+
+```bash
+bd backup
+git add .beads/backup/
+git commit -m "chore: sync beads backup after shipping"
+git push
+```
+
+### Phase 8: Summary
+
+Print a concise ship report:
+
+```
+## Ship Complete
+
+**PR:** {PR_URL}
+**Branch:** {current_branch} -> {default_branch}
+
+### Beads Closed
+- {BEAD_ID}: {title}
+- {BEAD_ID}: {title}
+(or "No beads tracked for this ship")
+
+### Knowledge Captured
+- {count} knowledge entries logged across {count} beads
+(or "No knowledge entries -- consider running /lavra-compound")
+
+### Warnings
+- {any WARNING items from Phase 4}
+(or "None")
+
+### Suggested Follow-ups
+- Review the PR: {PR_URL}
+- Run /lavra-compound to extract reusable knowledge (if LEARNED/INVESTIGATION comments found)
+- Monitor CI results: gh pr checks {PR_NUMBER}
+```
+
+</process>
+
+<success_criteria>
+- [ ] Branch is not main/master
+- [ ] No uncommitted changes at ship time
+- [ ] Rebased on latest default branch without conflicts
+- [ ] Tests pass (or no test runner detected)
+- [ ] No critical security or quality issues in the diff
+- [ ] PR created with descriptive title and body
+- [ ] All in_progress beads closed with reason linking to PR
+- [ ] At least one knowledge comment per closed bead
+- [ ] Beads backup pushed to remote
+- [ ] Summary printed with PR URL and next steps
+</success_criteria>
+
+<guardrails>
+
+### Never Force-Push
+Use `git push`, never `git push --force` or `git push --force-with-lease`. If the push fails, diagnose and fix -- do not override.
+
+### Never Push to Main/Master
+If the current branch is main or master, halt immediately. Ship creates PRs, it does not push directly to protected branches.
+
+### Stop on Test Failures
+If tests fail, the pipeline halts. Do not skip tests, do not ignore failures. Broken code does not ship.
+
+### Stop on Critical Review Findings
+Secrets, credentials, and unresolved merge conflicts are ship-blockers. The pipeline halts until they are resolved.
+
+### Do Not Substitute for Full Review
+Phase 4 is a safety net, not a code review. It catches ship-blockers only. For thorough review, use /lavra-review before or after /lavra-ship.
+
+### Bead Closure is Permanent
+Beads are closed with a reason linking to the PR. If the PR is later rejected, the user must manually reopen beads. This command does not handle PR rejection workflows.
+
+</guardrails>

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

@@ -0,0 +1,159 @@
+---
+name: lavra-triage
+description: Triage and categorize beads for prioritization
+argument-hint: "[bead ID or empty]"
+disable-model-invocation: true
+---
+
+<objective>
+Present all findings, decisions, or issues one by one for triage. Go through each bead and decide whether to keep, modify, dismiss, or defer it. Useful for triaging code review findings, security audit results, performance analysis, or any categorized findings that need tracking.
+</objective>
+
+<execution_context>
+<bead_input> #$ARGUMENTS </bead_input>
+
+**First, determine if the argument is a bead ID or empty:**
+
+Check if the argument matches a bead ID pattern:
+- Pattern: lowercase alphanumeric segments separated by hyphens (e.g., `bikiniup-xhr`, `beads-123`, `fix-auth-bug2`)
+- Regex: `^[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$`
+
+**If the argument matches a bead ID pattern:**
+
+1. Try to load the bead using the Bash tool:
+   ```bash
+   bd show "#$ARGUMENTS" --json
+   ```
+
+2. If the bead exists:
+   - Extract the `title` and `type` fields from the JSON array (first element)
+   - Example: `bd show "#$ARGUMENTS" --json | jq -r '.[0].type'`
+   - Announce: "Triaging bead #$ARGUMENTS: {title}"
+
+   **If the bead is an epic:**
+   - List all child beads:
+     ```bash
+     bd list --parent "#$ARGUMENTS" --json
+     ```
+   - Triage the epic's child beads
+
+   **If the bead is not an epic:**
+   - Triage just that single bead
+
+3. If the bead doesn't exist (command fails):
+   - Report: "Bead ID '#$ARGUMENTS' not found. Please check the ID or provide a valid bead ID."
+   - Stop execution
+
+**If the argument does NOT match a bead ID pattern (or is empty):**
+- Triage all open beads (original behavior):
+  ```bash
+  bd list --status=open --json
+  ```
+
+Read each bead's full details:
+```bash
+bd show {BEAD_ID}
+```
+</execution_context>
+
+<process>
+
+### Step 1: Present Each Bead
+
+For each bead, present in this format:
+
+```
+---
+Bead #X: {BEAD_ID} - [Brief Title]
+
+Severity: P1 (CRITICAL) / P2 (IMPORTANT) / P3 (NICE-TO-HAVE)
+
+Category: [Security/Performance/Architecture/Bug/Feature/etc.]
+
+Description:
+[Detailed explanation from bead description]
+
+Location: [file_path:line_number if applicable]
+
+Problem Scenario:
+[Step by step what's wrong or could happen]
+
+Proposed Solution:
+[How to fix it]
+
+Estimated Effort: [Small (< 2 hours) / Medium (2-8 hours) / Large (> 8 hours)]
+
+---
+What would you like to do with this bead?
+1. Keep - approve for work
+2. Modify - change priority, description, or details
+3. Dismiss - close/remove this bead
+4. Defer - keep but lower priority
+```
+
+### Step 2: Handle User Decision
+
+**When user says "Keep":**
+1. Update bead status to ready: `bd update {BEAD_ID} --status=open`
+2. Confirm: "Approved: `{BEAD_ID}` - {title} -> Ready to work on"
+
+**When user says "Modify":**
+- Ask what to modify (priority, description, details)
+- Update the bead: `bd update {BEAD_ID} --priority {N} -d "{new description}"`
+- Present revised version
+- Ask again: Keep/Modify/Dismiss/Defer
+
+**When user says "Dismiss":**
+- Close the bead: `bd close {BEAD_ID} --reason "Dismissed during triage"`
+- Log: `bd comments add {BEAD_ID} "DECISION: Dismissed during triage - {reason}"`
+- Skip to next item
+
+**When user says "Defer":**
+- Lower priority: `bd update {BEAD_ID} --priority 5`
+- Add tag: `bd update {BEAD_ID} --tags "deferred"`
+- Log: `bd comments add {BEAD_ID} "DECISION: Deferred during triage - {reason}"`
+
+### Step 3: Progress Tracking
+
+Every time you present a bead, include:
+- **Progress:** X/Y completed (e.g., "3/10 completed")
+
+### Step 4: Final Summary
+
+After all items processed:
+
+```markdown
+## Triage Complete
+
+**Total Items:** [X]
+**Kept (ready for work):** [Y]
+**Modified:** [Z]
+**Dismissed:** [A]
+**Deferred:** [B]
+
+### Approved Beads (Ready for Work):
+- {BD-XXX}: {title} - Priority {N}
+- {BD-YYY}: {title} - Priority {N}
+
+### Dismissed Beads:
+- {BD-ZZZ}: {title} - Reason: {reason}
+
+### Deferred Beads:
+- {BD-AAA}: {title} - Reason: {reason}
+```
+
+</process>
+
+<guardrails>
+- DO NOT implement fixes or write code during triage
+- Triage is for decisions only
+- Implementation happens in `/lavra-work`
+</guardrails>
+
+<handoff>
+What would you like to do next?
+
+1. Run /lavra-work to resolve the approved beads
+2. Run /lavra-work {BEAD_ID} on a specific bead
+3. Nothing for now
+</handoff>