chore(beads): migrate issue tracking from bd to br

Agents were told to run bd commands that beads_rust does not have (bd prime, bd remember, bd dolt push, bd tag, bd note, bd children), and bd's git hooks were still active, so bd could re-export its stale dolt state over br's JSONL on commit. - Rewrite AGENTS.md, docs/agents/issue-tracker.md, docs/agents/triage-labels.md and the .serena memories around br's real CLI surface - Replace bd's generated AGENTS.md block with br's (br agents --add) - Point the .claude session hooks at `br robot-docs guide` - Remove bd git hooks and unset core.hooksPath; br installs no hooks - Ignore br runtime files (local SQLite DB, recovery and merge artifacts) - Rewrite .beads/README.md, config.yaml and metadata.json for br Issue: nix-overlay-6pp
2026-10-21 18:47:16 +03:00
parent eefef7cce2
commit 722d608491
18 changed files with 217 additions and 372 deletions
@@ -19,12 +19,12 @@ This is a **Nix flake overlay** repository that provides additional packages for

 **MANDATORY** — Before writing code, running builds, or making any changes:

-1. **Run `bd prime`** — Get full workflow context and available commands
-2. **Check for existing issues** — Run `bd ready` to find available work
-3. **Claim the task** — Use `bd update <id> --claim` before starting
-4. **Track via `bd` ONLY** — NEVER use TodoWrite, TaskCreate, or markdown TODO lists. All task tracking goes through `bd`.
+1. **Run `br robot-docs guide`** — Get full workflow context and available commands
+2. **Check for existing issues** — Run `br ready` to find available work
+3. **Claim the task** — Use `br update <id> --claim` before starting
+4. **Track via `br` ONLY** — NEVER use TodoWrite, TaskCreate, or markdown TODO lists. All task tracking goes through `br`.

-Violating this rule means the agent is working outside the project's workflow. Stop and re-claim via `bd` first.
+Violating this rule means the agent is working outside the project's workflow. Stop and re-claim via `br` first.

 ### Required Skills

@@ -342,9 +342,9 @@ This skill provides:

 ```bash
 # 0. Claim the task via beads (MANDATORY before any work)
-bd ready              # Find available work
-bd show <id>          # Review task details
-bd update <id> --claim  # Claim the task
+br ready              # Find available work
+br show <id>          # Review task details
+br update <id> --claim  # Claim the task

 # 1. Create package directory
 mkdir -p packages/my-tool
@@ -372,46 +372,28 @@ git add packages/my-tool README.md
 # Then invoke: skill: "conventional-commit"

 # 8. Close the task via beads
-bd close <id>         # Mark task as complete
+br close <id>         # Mark task as complete
+br sync --flush-only  # Export issue state to .beads/issues.jsonl
+git add .beads/       # Stage the exported state
+git commit -m "sync beads"
 ```

 ## Agent skills

 ### Issue tracker

-Issues live in the beads database (`.beads/`, driven by the `bd` CLI), synced through `git push`. The Gitea remote is not the issue tracker. See `docs/agents/issue-tracker.md`.
+Issues live in the beads database (`.beads/`, driven by the `br` CLI), synced through `git push`. The Gitea remote is not the issue tracker. See `docs/agents/issue-tracker.md`.
+
+**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.

 ### Triage labels

-The five canonical triage roles keep their default names, applied as `bd` labels. See `docs/agents/triage-labels.md`.
+The five canonical triage roles keep their default names, applied as `br` labels. See `docs/agents/triage-labels.md`.

 ### Domain docs

 Single-context layout: `CONTEXT.md` plus `docs/adr/` at the repo root. See `docs/agents/domain.md`.

-<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
-## Beads Issue Tracker
-
-This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
-
-### Quick Reference
-
-```bash
-bd prime              # ALWAYS run first — get full context and command reference
-bd ready              # Find available work
-bd show <id>          # View issue details
-bd update <id> --claim  # Claim work (do this BEFORE starting any task)
-bd close <id>         # Complete work (do this AFTER pushing changes)
-bd remember           # Save persistent knowledge (use instead of MEMORY.md files)
-```
-
-### Rules
-
- **Use `bd` for ALL task tracking** — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- **Run `bd prime` BEFORE starting any work** — this provides session context and close protocol
- **Run `bd remember` for persistent knowledge** — do NOT use MEMORY.md files
- **If you forgot to claim** — stop working and claim via `bd` immediately
-
 ## Session Completion

 **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
@@ -421,25 +403,91 @@ bd remember           # Save persistent knowledge (use instead of MEMORY.md file
 1. **File issues for remaining work** - Create issues for anything that needs follow-up
 2. **Run quality gates** (if code changed) - Tests, linters, builds
 3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
+4. **Export and commit issue state** - `br` never runs git commands:
+   ```bash
+   br sync --flush-only
+   git add .beads/
+   git commit -m "sync beads"
+   ```
+5. **PUSH TO REMOTE** - This is MANDATORY:
   ```bash
   git pull --rebase
-   bd dolt push
   git push
   git status  # MUST show "up to date with origin"
   ```
-   Note: no Dolt remote is configured for this workspace, so `bd dolt push`
-   prints `No remote is configured — skipping.` and exits. That is expected,
-   NOT a failure. Beads state is versioned locally in `.beads/` and synced to
-   the shared repository via `git push` — the `git status` check above is the
-   real completion gate.
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
+6. **Clean up** - Clear stashes, prune remote branches
+7. **Verify** - All changes committed AND pushed
+8. **Hand off** - Provide context for next session

 **CRITICAL RULES:**
 - Work is NOT complete until `git push` succeeds
 - NEVER stop before pushing - that leaves work stranded locally
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
-<!-- END BEADS INTEGRATION -->
+
+<!-- br-agent-instructions-v1 -->
+
+---
+
+## Beads Workflow Integration
+
+This project uses [beads_rust](https://github.com/Dicklesworthstone/beads_rust) (`br`) for issue tracking. Issues are stored in `.beads/` and tracked in git.
+
+### Essential Commands
+
+```bash
+# View ready issues (open, unblocked, not deferred)
+br ready              # Unblocked, non-deferred work
+
+# List and search
+br list --status=open # All open issues
+br show <id>          # Full issue details with dependencies
+br search "keyword"   # Full-text search
+
+# Create and update
+br create --title="..." --description="..." --type=task --priority=2
+br update <id> --status=in_progress
+br close <id> --reason="Completed"
+br close <id1> <id2>  # Close multiple issues at once
+
+# Sync with git
+br sync --flush-only  # Export DB to JSONL
+br sync --status      # Check sync status
+```
+
+### Workflow Pattern
+
+1. **Start**: Run `br ready` to find actionable work
+2. **Claim**: Use `br update <id> --status=in_progress`
+3. **Work**: Implement the task
+4. **Complete**: Use `br close <id>`
+5. **Sync**: Always run `br sync --flush-only` at session end
+
+### Key Concepts
+
+- **Dependencies**: Issues can block other issues. `br ready` shows only open, unblocked work.
+- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
+- **Types**: task, bug, feature, epic, chore, docs, question
+- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
+
+### Session Protocol
+
+**Before ending any session, run this checklist:**
+
+```bash
+git status              # Check what changed
+br sync --flush-only    # Export beads changes to JSONL
+git add <files> .beads/ # Stage code changes and exported issue state
+git commit -m "..."     # Commit everything
+git push                # Push to remote
+```
+
+### Best Practices
+
+- Check `br ready` at session start to find available work
+- Update status as you work (in_progress → closed)
+- Create new issues with `br create` when you discover tasks
+- Use descriptive titles and set appropriate priority/type
+- Always sync before ending session
+
+<!-- end-br-agent-instructions -->