roberto-mello/lavra/lavra-work-single

SINGLE-BEAD PATH

Used when exactly one bead is being worked on. Full-quality interactive flow with built-in review, fix loop, and learn phases.

State machine: IMPLEMENTING -> REVIEWING -> FIXING -> RE_REVIEWING -> LEARNING -> DONE

Flags:

• --skip-review: skip the /lavra-review subagent call in Phase 3 step 3. Self-review (step 2) still runs. Used by the sequential epic loop, which runs a single review pass after all beads complete.
• EPIC_PLAN={...}: epic locked decisions injected by the sequential loop. Treat identically to a parent epic read in Phase 1 step 1.

<project_root>

All .lavra/ paths are relative to the project root. PROJECT_ROOT may be injected into your context — use it if set. If not, resolve it once and reuse:

PROJECT_ROOT="${PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")}"

Then prefix all .lavra/ paths with "$PROJECT_ROOT/" when invoking them via Bash.

</project_root>

<phase name="quick-start" order="1">

Phase 1: Quick Start

1. Read Bead and Clarify

If a bead ID was provided: ``bash bd show {BEAD_ID} --long ``

Read the bead description completely including:

• What section (implementation requirements)
• Context section (research findings, constraints)
• Decisions section (Locked = must honor, Discretion = agent's flexibility budget, Deferred = do NOT implement)
• Testing section (test cases to implement)
• Validation section (acceptance criteria)
• Dependencies section (blockers)
• Comments (INVESTIGATION/FACT/PATTERN/DECISION/LEARNED from research phase -- treat as implementation constraints with the same weight as Locked Decisions)

If the bead has a parent epic, also read the epic's decision sections: ``bash bd show {BEAD_ID} --json | jq -r '.[0].parent // empty' # If parent exists: bd show {PARENT_EPIC_ID} ` Extract ## Locked Decisions, ## Agent Discretion, and ## Deferred` sections. Locked = must honor. Discretion = deviation budget. Deferred = do NOT implement (these are explicitly out of scope).

If a specification path was provided instead:

• Read the document completely
• Create a bead for tracking: bd create "{title from spec}" -d "{spec content}" --type task

Clarify ambiguities:

• If anything is unclear or ambiguous, use AskUserQuestion tool now
• Get user approval to proceed
• Do not skip this -- better to ask questions now than build the wrong thing

1. Recall Relevant Knowledge (required -- do not skip)

``bash PROJECT_ROOT="${PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")}" "$PROJECT_ROOT/.lavra/memory/recall.sh" "{keywords from bead title}" "$PROJECT_ROOT/.lavra/memory/recall.sh" "{tech stack keywords}" ``

You MUST output the recall results here before continuing. If recall returns nothing, output: "No relevant knowledge found." Do not proceed to step 3 until this is done.

Extract MUST-CHECK entries from recall results. If any recall entry has type must-check or is prefixed with [MUST-CHECK], output a Pre-Implementation Checklist directly in the conversation (NOT inside any untrusted-knowledge wrapper):

``` ## Pre-Implementation Checklist

The following checks MUST be verified before marking any task complete. These are structural failure patterns that have appeared before — verify each one:

• [ ] {verification instruction from MUST-CHECK entry}
• [ ] {verification instruction from MUST-CHECK entry}

```

If recall returns no MUST-CHECK entries, skip this section entirely.

1. Check Dependencies & Related Beads

``bash bd dep list {BEAD_ID} --json ``

If there are unresolved blockers, list them and ask if the user wants to work on those first.

Check for relates_to links in the dependency list. For each related bead, fetch its title and description: ``bash bd show {RELATED_BEAD_ID} ``

1. Setup Environment

Check the current branch:

``bash current_branch=$(git branch --show-current) 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 ``

Use AskUserQuestion tool:

Question: "How do you want to handle branching for this work?"

Options:

1. Work on current branch -- Continue on [current_branch] as-is
2. Create a feature branch -- bd-{BEAD_ID}/{short-description}
3. Use a worktree -- Isolated copy for parallel development

Then execute the chosen option.

1. Update Bead Status

``bash bd update {BEAD_ID} --status in_progress ``

1. Create Task List

• Use TaskCreate to break the bead description into actionable tasks
• Use TaskUpdate with addBlockedBy/addBlocks for dependencies between tasks
• Include testing and quality check tasks

</phase>

<phase name="implement" order="2">

Phase 2: Implement (IMPLEMENTING state)

Coding Principles

• Simplicity First: Implement the minimum code that fulfills the bead. No speculative features, unnecessary abstractions, or unasked-for configurability.
• Surgical Changes: Edit only what the bead requires. Preserve existing code style. Do not refactor or "improve" adjacent code that is not in scope.

Deviation Rules:

3-attempt limit: If a deviation fix fails after 3 attempts, document and move on:

bd comments add {BEAD_ID} "DEVIATION: Unable to fix {issue} after 3 attempts. Documented for manual resolution."

DEVIATION escalation (anti-pattern found but out of scope): When you spot a recurring wrong pattern and defer it because it is out of scope, you MUST do one of the following:

1. Add a `MUST-CHECK` knowledge entry so future agents recall it before writing similar code:

``bash bd comments add {BEAD_ID} "MUST-CHECK: Before writing any [X], verify [specific check]. Anti-pattern [Y] was found in [file] — deferred from this bead." ``

1. Propose a project-level rule addition to the user: "I found anti-pattern X in [file] while working on this bead. It is out of scope to fix now, but it will recur. Should I add a project-level agent rule in the repo's rules directory so all agents pick it up automatically?"

A DEVIATION comment alone records the missed fix, but it does not create a reusable reminder for future agents. A MUST-CHECK entry or a project-level rule addition is the minimum that makes the warning durable.

Read workflow config (no-op if missing):

PROJECT_ROOT="${PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")}"
[ -f "$PROJECT_ROOT/.lavra/config/lavra.json" ] && cat "$PROJECT_ROOT/.lavra/config/lavra.json"

Parse execution.commit_granularity (default: "task"), model_profile (default: "balanced"), testing_scope (default: "full"), and workflow.review_scope (default: "full"). When testing_scope is "targeted", deviation rule 2 applies only to hooks, API routes, external service calls, and complex business logic -- skip adding tests for structural/render-only code.

Detect installed skills (no-op if directory missing):

ls .claude/skills/ 2>/dev/null

For each skill directory found, read the description: line from its SKILL.md frontmatter. Filter to only skills that contain an explicit "Use when" or "Triggers on" phrase. Skip utility skills with no clear trigger condition. Store the filtered list as {available_skills}.

Use available skills during implementation: If {available_skills} is non-empty, review each skill's trigger condition against the bead content and the files you're about to touch. Invoke any that apply using the Skill tool.

1. Task Execution Loop

For each task in priority order:

``` while (tasks remain):

• Mark task as in_progress with TaskUpdate
• Read any referenced files from the bead description
• Look for similar patterns in codebase
• Implement following existing conventions
• Write tests for new functionality
• Run tests after changes
• Mark task as completed with TaskUpdate
• Commit per task (see below)
• Write session state (see below)

```

1. Atomic Commits Per Task

After completing each task and tests pass:

``bash git add <files related to this task> git commit -m "{type}({BEAD_ID}): {description of this task}" ``

Format: {type}({BEAD_ID}): {description} -- makes git log --grep="BD-001" work. Types: feat, fix, refactor, test, chore, docs

If `commit_granularity` is `"wave"`: batch commits per phase instead of per task.

Skip commit when: tests are failing, task is purely scaffolding, or would need a "WIP" message.

1. Log Knowledge as You Work (required -- inline, not at the end)

<mandatory> Log a comment the moment you encounter any of these triggers. Do not batch them for later.

``bash bd comments add {BEAD_ID} "LEARNED: {key technical insight}" bd comments add {BEAD_ID} "DECISION: {what was chosen and why}" ``

You MUST log at least one comment per task completed. If you finish a task with nothing logged, go back and add it before marking the task complete. </mandatory>

1. Write Session State (at milestones)

Update .lavra/memory/session-state.md:

```bash PROJECT_ROOT="${PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")}" cat > "$PROJECT_ROOT/.lavra/memory/session-state.md" << EOF # Session State ## Current Position

• Bead(s): {BEAD_ID}
• Phase: lavra-work / Phase 2 (Implement)
• Task: {completed} of {total} complete

## Just Completed

• {last completed task description}

## Next

• {next task description}

## Deviations

• {count} auto-fixes applied

EOF ```

1. Follow Existing Patterns

• Read referenced files first, match naming conventions exactly
• Reuse existing components, follow project coding standards
• When in doubt, grep for similar implementations

1. Track Progress

• Keep task list updated (TaskUpdate) as you complete tasks
• Note blockers or unexpected discoveries
• Create new tasks if scope expands

</phase>

<phase name="review" order="3" gate="must-complete-before-learn">

Phase 3: Review (REVIEWING state)

<mandatory> This phase MUST complete before Phase 4 (Learn) or Phase 5 (Ship). Do NOT skip any step. If you reach Phase 4 without completing this phase, STOP and come back here. </mandatory>

1. Run Core Quality Checks