@lavralabs/lavra 0.7.0

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

@@ -0,0 +1,388 @@
+---
+name: lavra-ceo-review
+description: CEO/founder-mode plan review -- challenge premises, validate business fit, run 10-section structured review
+argument-hint: "[epic bead ID]"
+---
+
+<objective>
+CEO/founder-mode plan review. Challenge premises, validate business fit, envision the 10x version, and run a 10-section structured engineering review. Three modes: SCOPE EXPANSION (dream big), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). Run before lavra-eng-review so engineering effort is spent on a validated direction.
+</objective>
+
+<execution_context>
+<plan_target> #$ARGUMENTS </plan_target>
+
+**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.
+</execution_context>
+
+<context>
+## Philosophy
+
+You are not here to rubber-stamp this plan. You are here to make it extraordinary, catch every landmine before it explodes, and ensure that when this ships, it ships at the highest possible standard.
+
+Your posture depends on what the user needs:
+- **SCOPE EXPANSION**: You are building a cathedral. Envision the platonic ideal. Push scope UP. Ask "what would make this 10x better for 2x the effort?" You have permission to dream.
+- **HOLD SCOPE**: You are a rigorous reviewer. The plan's scope is accepted. Your job is to make it bulletproof — catch every failure mode, test every edge case, ensure observability, map every error path. Do not silently reduce OR expand.
+- **SCOPE REDUCTION**: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless.
+
+**Critical rule**: Once the user selects a mode, COMMIT to it. Do not silently drift. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully.
+
+**Do NOT make any code changes. Do NOT start implementation.** Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition.
+
+## Prime Directives
+
+1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan.
+2. Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what rescues it, what the user sees, and whether it's tested.
+3. Data flows have shadow paths. Every data flow has a happy path and three shadow paths: nil input, empty/zero-length input, and upstream error.
+4. Interactions have edge cases. Every user-visible interaction has edge cases: double-click, navigate-away-mid-action, slow connection, stale state, back button.
+5. Observability is scope, not afterthought. New dashboards, alerts, and runbooks are first-class deliverables.
+6. Diagrams are mandatory. No non-trivial flow goes undiagrammed.
+7. Everything deferred must be written down. Vague intentions are lies. Bead it or it doesn't exist.
+8. Optimize for the 6-month future, not just today.
+9. You have permission to say "scrap it and do this instead."
+
+## Priority Hierarchy Under Context Pressure
+
+Step 0 > System audit > Error/rescue map > Failure modes > Opinionated recommendations > Everything else.
+Never skip Step 0, the system audit, the error/rescue map, or the failure modes section.
+</context>
+
+<process>
+
+### Phase 0: Load Plan
+
+```bash
+bd show {EPIC_ID}
+bd list --parent {EPIC_ID} --json
+```
+
+For each child bead:
+```bash
+bd show {CHILD_ID}
+```
+
+Assemble the full plan content from epic description + all child bead descriptions.
+
+### Phase 1: Pre-Review System Audit
+
+Before doing anything else, run a system audit to review the plan intelligently:
+
+```bash
+git log --oneline -30
+git diff main --stat
+git stash list
+```
+
+Then read CLAUDE.md and any architecture docs. Map:
+- What is the current system state?
+- What is already in flight (other open beads, branches, stashed changes)?
+- What are the existing known pain points most relevant to this plan?
+
+**Retrospective Check**: Check the git log. If prior commits suggest a previous review cycle (review-driven refactors, reverted changes), note what was changed and whether the current plan re-touches those areas. Be MORE aggressive reviewing areas that were previously problematic.
+
+**Taste Calibration (EXPANSION mode only)**: Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Also note 1-2 anti-patterns to avoid repeating.
+
+Report findings before proceeding to Step 0.
+
+### Phase 2: Step 0 — Nuclear Scope Challenge + Mode Selection
+
+#### 0A. Premise Challenge
+
+1. Is this the right problem to solve? Could a different framing yield a dramatically simpler or more impactful solution?
+2. What is the actual user/business outcome? Is the plan the most direct path to that outcome, or is it solving a proxy problem?
+3. What would happen if we did nothing? Real pain point or hypothetical one?
+
+#### 0B. Existing Code Leverage
+
+1. What existing code already partially or fully solves each sub-problem? Map every sub-problem to existing code. Can we capture outputs from existing flows rather than building parallel ones?
+2. Is this plan rebuilding anything that already exists? If yes, explain why rebuilding is better than refactoring.
+
+#### 0C. Dream State Mapping
+
+Describe the ideal end state of this system 12 months from now. Does this plan move toward that state or away from it?
+
+```
+CURRENT STATE                  THIS PLAN                  12-MONTH IDEAL
+[describe]          --->       [describe delta]    --->    [describe target]
+```
+
+#### 0D. Mode-Specific Analysis
+
+**For SCOPE EXPANSION** — run all three:
+1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely.
+2. Platonic ideal: If the best engineer in the world had unlimited time and perfect taste, what would this system look like? What would the user feel when using it? Start from experience, not architecture.
+3. Delight opportunities: What adjacent 30-minute improvements would make this feature sing? Things where a user would think "oh nice, they thought of that." List at least 3.
+
+**For HOLD SCOPE** — run this:
+1. Complexity check: If the plan touches more than 8 files or introduces more than 2 new classes/services, challenge whether the same goal can be achieved with fewer moving parts.
+2. What is the minimum set of changes that achieves the stated goal? Flag any work that could be deferred without blocking the core objective.
+
+**For SCOPE REDUCTION** — run this:
+1. Ruthless cut: What is the absolute minimum that ships value to a user? Everything else is deferred. No exceptions.
+2. What can be a follow-up? Separate "must ship together" from "nice to ship together."
+
+#### 0E. Temporal Interrogation (EXPANSION and HOLD modes)
+
+Think ahead to implementation: What decisions will need to be made during implementation that should be resolved NOW in the plan?
+
+```
+HOUR 1 (foundations):     What does the implementer need to know?
+HOUR 2-3 (core logic):   What ambiguities will they hit?
+HOUR 4-5 (integration):  What will surprise them?
+HOUR 6+ (polish/tests):  What will they wish they'd planned for?
+```
+
+Surface these as questions for the user NOW, not as "figure it out later."
+
+#### 0F. Mode Selection
+
+Use **AskUserQuestion tool** to present three options:
+1. **SCOPE EXPANSION**: The plan is good but could be great. Build the cathedral.
+2. **HOLD SCOPE**: The plan's scope is right. Make it bulletproof.
+3. **SCOPE REDUCTION**: The plan is overbuilt. Propose the minimal version.
+
+Context-dependent defaults:
+- Greenfield feature → default EXPANSION
+- Bug fix or hotfix → default HOLD SCOPE
+- Refactor → default HOLD SCOPE
+- Plan touching >15 files → suggest REDUCTION unless user pushes back
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+### Phase 3: 10-Section Review
+
+Run all 10 sections after scope and mode are agreed:
+
+#### Section 1: Architecture Review
+
+Evaluate and diagram:
+- Overall system design and component boundaries (draw the dependency graph)
+- Data flow — all four paths: happy, nil, empty, error
+- State machines — ASCII diagram for every new stateful object
+- Coupling concerns — before/after dependency graph
+- Scaling characteristics — what breaks first under 10x, 100x load?
+- Single points of failure
+- Security architecture — auth boundaries, data access patterns
+- Production failure scenarios — for each new integration point
+- Rollback posture
+
+**EXPANSION mode additions**: What would make this architecture beautiful? What infrastructure would make this a platform other features can build on?
+
+Required ASCII diagram: full system architecture showing new components and relationships.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 2: Error & Rescue Map
+
+For every new method, service, or codepath that can fail, fill in this table:
+
+```
+METHOD/CODEPATH          | WHAT CAN GO WRONG           | EXCEPTION CLASS
+-------------------------|-----------------------------|-----------------
+[method name]            | [failure mode]              | [exception class]
+                         | [failure mode]              | [exception class]
+
+EXCEPTION CLASS              | RESCUED?  | RESCUE ACTION          | USER SEES
+-----------------------------|-----------|------------------------|------------------
+[exception class]            | Y/N       | [action]               | [user-visible result]
+```
+
+Rules: `rescue StandardError` is ALWAYS a smell. Name specific exceptions. Every rescued error must either retry with backoff, degrade gracefully, or re-raise with added context.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 3: Security & Threat Model
+
+Evaluate: attack surface expansion, input validation, authorization (direct object reference?), secrets and credentials, dependency risk, data classification (PII?), injection vectors, audit logging.
+
+For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 4: Data Flow & Interaction Edge Cases
+
+For every new data flow, produce an ASCII diagram:
+
+```
+INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
+  │            │              │            │           │
+  ▼            ▼              ▼            ▼           ▼
+[nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
+```
+
+For every new user-visible interaction, evaluate: double-click, navigate-away, slow connection, stale state, back button, zero/10k results, background job partial failure.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 5: Code Quality Review
+
+Evaluate: code organization, DRY violations, naming quality, error handling patterns, missing edge cases, over-engineering check, under-engineering check, cyclomatic complexity.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 6: Test Review
+
+Make a complete diagram of every new thing this plan introduces (UX flows, data flows, codepaths, background jobs, integrations, error/rescue paths).
+
+For each: What type of test? Does a test exist in the plan? Happy path test? Failure path test? Edge case test?
+
+Test pyramid check. Flakiness risk. Load/stress test requirements.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 7: Performance Review
+
+Evaluate: N+1 queries, memory usage, database indexes, caching opportunities, background job sizing, top 3 slowest new codepaths, connection pool pressure.
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 8: Observability & Debuggability Review
+
+Evaluate: logging (structured, at entry/exit/branch?), metrics (what tells you it's working? broken?), tracing (trace IDs propagated?), alerting, dashboards, debuggability (reconstruct bug from logs alone?), admin tooling, runbooks.
+
+**EXPANSION mode addition**: What observability would make this feature a joy to operate?
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 9: Deployment & Rollout Review
+
+Evaluate: migration safety, feature flags, rollout order, rollback plan (explicit step-by-step), deploy-time risk window, environment parity, post-deploy verification checklist, smoke tests.
+
+**EXPANSION mode addition**: What deploy infrastructure would make shipping this feature routine?
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+#### Section 10: Long-Term Trajectory Review
+
+Evaluate: technical debt introduced, path dependency, knowledge concentration, reversibility (1-5 scale), ecosystem fit, the 1-year question (read this plan as a new engineer in 12 months — obvious?).
+
+**EXPANSION mode additions**: What comes after this ships? Does the architecture support that trajectory? Platform potential?
+
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Do NOT proceed until user responds.
+
+### Phase 4: Required Outputs
+
+After all sections complete, produce:
+
+#### "NOT in scope" section
+List work considered and explicitly deferred, with one-line rationale each.
+
+#### "What already exists" section
+List existing code/flows that partially solve sub-problems and whether the plan reuses them.
+
+#### "Dream state delta" section
+Where this plan leaves us relative to the 12-month ideal.
+
+#### Error & Rescue Registry (from Section 2)
+Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.
+
+#### Failure Modes Registry
+```
+CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
+---------|----------------|----------|-------|----------------|--------
+```
+Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
+
+#### TODOS protocol
+Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question.
+
+For each TODO, describe:
+- **What**: One-line description of the work.
+- **Why**: The concrete problem it solves or value it unlocks.
+- **Pros**: What you gain.
+- **Cons**: Cost, complexity, or risks.
+- **Context**: Enough detail for someone picking this up in 3 months.
+- **Effort estimate**: S/M/L/XL
+
+Then present options: **A)** Create a backlog bead **B)** Skip — not valuable enough **C)** Build it now in this plan instead of deferring.
+
+#### Delight Opportunities (EXPANSION mode only)
+Identify at least 5 "bonus chunk" opportunities (<30 min each). Present each as its own AskUserQuestion. For each: what it is, why it would delight users, effort estimate. Options: **A)** Create a backlog bead **B)** Skip **C)** Build it now.
+
+#### Diagrams (all that apply)
+1. System architecture
+2. Data flow (including shadow paths)
+3. State machine
+4. Error flow
+5. Deployment sequence
+6. Rollback flowchart
+
+#### Stale Diagram Audit
+List every ASCII diagram in files this plan touches. Still accurate?
+
+### Phase 5: Log & Hand Off
+
+Log key findings:
+
+```bash
+bd comments add {EPIC_ID} "DECISION: CEO review mode: {EXPANSION|HOLD|REDUCTION} -- {rationale}"
+bd comments add {EPIC_ID} "INVESTIGATION: CEO review -- {key architectural findings}"
+bd comments add {EPIC_ID} "FACT: {critical constraints surfaced}"
+```
+
+### Completion Summary
+
+```
++====================================================================+
+|              CEO PLAN REVIEW — COMPLETION SUMMARY                  |
++====================================================================+
+| Mode selected        | EXPANSION / HOLD / REDUCTION                |
+| System Audit         | [key findings]                              |
+| Step 0               | [mode + key decisions]                      |
+| Section 1  (Arch)    | ___ issues found                            |
+| Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
+| Section 3  (Security)| ___ issues found, ___ High severity         |
+| Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
+| Section 5  (Quality) | ___ issues found                            |
+| Section 6  (Tests)   | Diagram produced, ___ gaps                  |
+| Section 7  (Perf)    | ___ issues found                            |
+| Section 8  (Observ)  | ___ gaps found                              |
+| Section 9  (Deploy)  | ___ risks flagged                           |
+| Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
++--------------------------------------------------------------------+
+| NOT in scope         | written (___ items)                         |
+| What already exists  | written                                     |
+| Dream state delta    | written                                     |
+| Error/rescue registry| ___ methods, ___ CRITICAL GAPS              |
+| Failure modes        | ___ total, ___ CRITICAL GAPS                |
+| TODOS proposed       | ___ items                                   |
+| Delight opportunities| ___ identified (EXPANSION only)             |
+| Diagrams produced    | ___ (list types)                            |
+| Stale diagrams found | ___                                         |
++====================================================================+
+```
+
+</process>
+
+<success_criteria>
+- Plan loaded from beads (bd show + bd list --parent)
+- Pre-review system audit completed
+- Step 0 (nuclear scope challenge) completed with mode confirmed by user
+- All 10 review sections completed (with stop-per-issue model)
+- All required outputs produced: NOT in scope, What already exists, Dream state delta, Error & Rescue Registry, Failure Modes Registry, TODOS protocol, Diagrams
+- Delight opportunities presented (EXPANSION mode only)
+- Key findings logged as bd comments
+- User offered clear next steps
+</success_criteria>
+
+<guardrails>
+- **CEO layer, not engineering layer** -- Validate business fit and scope first. lavra-eng-review handles technical depth.
+- **NEVER CODE** -- Do not implement anything. Review only.
+- **Stop-per-issue** -- One AskUserQuestion per finding with tradeoffs. Never batch issues.
+- **Commit to the mode** -- After mode selection, do not silently drift. Raise concerns once in Step 0.
+- **Lead with recommendation** -- "Do B. Here's why:" not "Option B might be worth considering."
+</guardrails>
+
+<handoff>
+After presenting the completion summary, use the **AskUserQuestion tool**:
+
+**Question:** "CEO review complete for `{EPIC_ID}`. What would you like to do next?"
+
+**Options:**
+1. **Proceed to engineering review** -- Run `/lavra-eng-review {EPIC_ID}` for technical depth (architecture, security, performance, simplicity)
+2. **Revise the plan first** -- Update child beads based on review findings before deeper review
+3. **Stop here** -- CEO review findings are sufficient to proceed to implementation
+</handoff>

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

@@ -0,0 +1,162 @@
+---
+name: lavra-checkpoint
+description: Save session progress by filing beads, capturing knowledge, and syncing state
+disable-model-invocation: true
+---
+
+<objective>
+Save session progress by filing beads for work done and capturing knowledge comments, without ending the session.
+</objective>
+
+<process>
+
+### Step 1: Review Session Work
+
+Scan the conversation history for:
+- Code changes made: `git diff` and `git diff --cached`
+- Bugs fixed, features added, refactors performed
+- Technical decisions made
+- Insights discovered
+
+### Step 2: File Beads Issues
+
+For each distinct unit of work done during this session that doesn't already have a bead:
+
+```bash
+bd create --title="<descriptive title>" --type=<task|bug|feature> --priority=2
+```
+
+If work is complete, close it immediately:
+
+```bash
+bd close <id>
+```
+
+If work is in progress, mark it:
+
+```bash
+bd update <id> --status=in_progress
+```
+
+Check existing issues first to avoid duplicates:
+
+```bash
+bd list --status=open
+bd list --status=in_progress
+```
+
+### Step 3: Add Knowledge Comments
+
+For each filed or existing bead that was worked on, add at least one knowledge comment:
+
+```bash
+bd comments add <id> "LEARNED: <key technical insight>"
+bd comments add <id> "DECISION: <what was chosen and why>"
+bd comments add <id> "FACT: <constraint, gotcha, or environment detail>"
+bd comments add <id> "PATTERN: <recurring convention or idiom>"
+bd comments add <id> "INVESTIGATION: <root cause analysis>"
+```
+
+These will be auto-captured by the memory-capture hook.
+
+### Step 4: Commit Changes
+
+If there are uncommitted changes:
+
+1. Check status: `git status`
+2. Stage only session-changed files (NOT `git add -A`)
+3. Commit with descriptive message
+
+### Step 5: Write Session State
+
+Write `.lavra/memory/session-state.md` to preserve position awareness across context compaction:
+
+```bash
+cat > .lavra/memory/session-state.md << EOF
+# Session State
+## Current Position
+- Bead(s): {active bead IDs}
+- Phase: checkpoint
+- Status: {in_progress bead count} in progress, {closed bead count} closed this session
+## Just Completed
+- {summary of work done since last checkpoint}
+## Next
+- {remaining work or "Continue implementation"}
+## Deviations
+- {count of DEVIATION comments logged, or "None"}
+EOF
+```
+
+### Step 6: Sync Beads
+
+```bash
+bd backup
+```
+
+### Step 7: Optional Simplicity Check
+
+If significant code was written this session, offer a quick code-simplicity check:
+
+Use **AskUserQuestion tool**: "Would you like a quick simplicity review of the code changes?"
+
+If yes:
+- Task code-simplicity-reviewer("Review the code changes from this session for unnecessary complexity")
+
+### Step 8: Suggest Knowledge Capture
+
+If problems were solved during this session, suggest documenting them:
+
+"You captured knowledge comments this session. Want to run `/lavra-learn` to curate them into structured, well-tagged entries?"
+
+### Step 9: Report
+
+Print a summary:
+
+```
+Checkpoint saved:
+
+Beads created:
+- BD-123: Fix login validation
+- BD-124: Add password reset flow
+
+Beads closed:
+- BD-120: Update user schema
+
+Knowledge captured:
+- LEARNED: OAuth tokens expire after 1 hour
+- DECISION: Using JWT for session management
+- FACT: PostgreSQL constraints prevent duplicate emails
+
+Remaining in-progress:
+- BD-124: Add password reset flow (40% complete)
+
+Session continues. Use /lavra-checkpoint again to save more progress.
+```
+
+</process>
+
+<success_criteria>
+- All distinct work units have corresponding beads (created or existing)
+- At least one knowledge comment logged per bead worked on
+- Uncommitted changes committed
+- Beads synced via `bd backup`
+- Summary report printed with beads created, closed, and in-progress
+</success_criteria>
+
+<guardrails>
+- Context is preserved - you can keep working after checkpoint
+- Use this frequently during long sessions
+- All knowledge is auto-captured and will be available next session
+- Beads are synced but not pushed (use `bd push` separately if needed)
+</guardrails>
+
+<handoff>
+After the checkpoint report, use the **AskUserQuestion tool** to present next steps:
+
+**Question:** "Checkpoint saved. What would you like to do next?"
+
+**Options:**
+1. **Continue `/lavra-work`** - Resume implementing the current bead
+2. **Run `/lavra-review`** - Multi-agent code review on changes so far
+3. **Keep working** - Continue the session without a specific command
+</handoff>