Work one Beads issue from claim to completion.
-
Refresh session state
bd dolt pull
bd ready
If no issues are ready, report that to the user and stop.
-
Inspect and claim the issue
bd show <issue-id>
bd update <issue-id> --claim
From the issue description, extract:
- The OpenSpec change path (e.g.,
openspec/changes/add-account-health-summary/)
- The original task wording
- Acceptance criteria
- Expected validation command
- Likely file/module boundary
Surface past memory for this change and issue (run only if ruflo is installed):
ruflo memory search -q "openspec:<change-id> implementation decisions" 2>/dev/null | head -20 || true
ruflo memory search -q "<issue-title-keywords> patterns" 2>/dev/null | head -20 || true
ruflo intelligence suggest --context "$(bd show <issue-id> --format title 2>/dev/null)" 2>/dev/null | head -10 || true
-
Re-read the OpenSpec source
Read the referenced OpenSpec artifacts before touching any code:
openspec/changes/<change-id>/proposal.md — scope and requirementsopenspec/changes/<change-id>/design.md — architecture decisionsopenspec/changes/<change-id>/tasks.md — task context and neighboring tasks- Any capability spec file referenced in the issue description
State a short plan before editing:
Plan:
1. <what you will implement>
2. <where it lives>
3. <what tests you will write or update>
4. <validation command>
-
Implement — scoped to this issue only
Allowed scope: the files and modules named in the issue and its OpenSpec task.
Not allowed: unrelated integration wiring, UI changes, refactors, schema changes, or public API changes not named in this issue.
Follow TDD: write or update failing tests first, then implement.
If you discover extra work during implementation:
- Do NOT silently expand scope
- Use the openspec-beads-followup skill to triage it (in-scope bug vs. out-of-scope follow-up)
- If it blocks this issue, link the new issue as a dep before continuing
If you discover a spec gap (behavior is missing or contradictory in OpenSpec):
- Use the openspec-beads-scope-change skill to update OpenSpec first
- Do not implement behavior that isn't specified in OpenSpec
-
Validate
<project unit test command>
openspec validate <change-id>
If no unit test command exists yet, run the narrowest available validation and state why no tests apply.
For narrow changes, run the focused test command instead of the full suite:
<focused test command>
Do not run integration tests unless the user explicitly approves in this thread.
-
Tick the tasks.md checkbox
Before closing, mark this task done in the OpenSpec tasks file:
openspec/changes/<change-id>/tasks.md
Change - [ ] <task text> → - [x] <task text> for the task(s) this issue covers.
This keeps the tasks.md in sync with Beads so openspec validate and /opsx:verify have accurate completeness data.
-
Close or update
If complete:
bd close <issue-id> --reason="<what was implemented, what tests were added, that validation passes>"
Write a trajectory entry so future sessions can recall this work (run only if ruflo is installed):
source ~/.claude/ruflo/lib/tags.sh 2>/dev/null && \
KEY="$(ruflo_key_prefix)|openspec:<change-id>|issue:<issue-id>|type:trajectory|outcome:closed|ts:$(date +%s)" && \
VALUE="$(bd show <issue-id> --format markdown 2>/dev/null)
files: $(git diff --name-only main..HEAD 2>/dev/null | tr '\n' ',')
commit: $(git rev-parse HEAD 2>/dev/null)" && \
ruflo memory store -k "$KEY" -v "$VALUE" 2>/dev/null || true
bd ready
If blocked:
bd update <issue-id> --notes="Blocked: <reason>. Created <blocker-id> to resolve."
bd ready
