chore: update beads issue tracking state
Sync beads database with current issue status. Includes history snapshot rotation and updated issue metadata from triage session.
This commit is contained in:
teernisse
66
AGENTS.md
66
AGENTS.md
@@ -20,6 +20,28 @@ If I tell you to do something, even if it goes against what follows below, YOU M
|
||||
|
||||
See `~/.claude/rules/jj-vcs/` for the full command reference, translation table, revsets, patterns, and recovery recipes.
|
||||
|
||||
### Multi-Agent VCS Protocol (CRITICAL)
|
||||
|
||||
**In a multi-agent session, ONLY THE TEAM LEAD performs jj/git operations.** Worker agents MUST NEVER run `jj` or `git` commands.
|
||||
|
||||
**Why:** jj has a single working copy (`@`) per workspace. Every `jj` command — even read-only ones like `jj status` — triggers a working copy snapshot recorded as an operation. When two agents run `jj` commands concurrently, both operations fork from the same parent operation and both rewrite `@`. jj detects this as a **divergent change**: same change ID, two different commits. Resolving divergences requires manual intervention and risks losing work.
|
||||
|
||||
**Rules for worker agents:**
|
||||
|
||||
- Edit files only via Edit/Write tools — NEVER run `jj`, `git`, or any shell command that triggers jj
|
||||
- If you need VCS info (status, diff, log), message the team lead
|
||||
- Do NOT run "Landing the Plane" — the lead handles all VCS for the team
|
||||
- Treat all file changes on disk as your own (other agents' edits are normal)
|
||||
|
||||
**Rules for the team lead:**
|
||||
|
||||
- You are the sole VCS operator — all commits, pushes, and rebases go through you
|
||||
- Run `jj status` / `jj diff` to review all agents' work before committing
|
||||
- Use `jj split` to separate different agents' work into distinct commits if needed
|
||||
- Follow "Landing the Plane" when ending the session
|
||||
|
||||
**Solo sessions:** When you are the only agent, you handle VCS yourself normally.
|
||||
|
||||
---
|
||||
|
||||
## Irreversible Git & Filesystem Actions — DO NOT EVER BREAK GLASS
|
||||
@@ -324,7 +346,7 @@ bv --robot-insights | jq '.Cycles' # Circular deps (must
|
||||
|
||||
```bash
|
||||
ubs file.rs file2.rs # Specific files (< 1s) — USE THIS
|
||||
ubs $(git diff --name-only --cached) # Staged files — before commit
|
||||
ubs $(jj diff --name-only) # Changed files — before commit
|
||||
ubs --only=rust,toml src/ # Language filter (3-5x faster)
|
||||
ubs --ci --fail-on-warning . # CI mode — before PR
|
||||
ubs . # Whole project (ignores target/, Cargo.lock)
|
||||
@@ -436,9 +458,9 @@ Returns structured results with file paths, line ranges, and extracted code snip
|
||||
|
||||
## Beads Workflow Integration
|
||||
|
||||
This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
|
||||
This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in version control.
|
||||
|
||||
**Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`.
|
||||
**Note:** `br` is non-invasive—it never executes VCS commands directly. You must commit manually after `br sync --flush-only`.
|
||||
|
||||
### Essential Commands
|
||||
|
||||
@@ -454,7 +476,7 @@ br create --title="..." --type=task --priority=2
|
||||
br update <id> --status=in_progress
|
||||
br close <id> --reason="Completed"
|
||||
br close <id1> <id2> # Close multiple issues at once
|
||||
br sync --flush-only # Export to JSONL (then manually: git add .beads/ && git commit)
|
||||
br sync --flush-only # Export to JSONL (then: jj commit -m "Update beads")
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
@@ -474,15 +496,14 @@ br sync --flush-only # Export to JSONL (then manually: git add .beads/ && git c
|
||||
|
||||
### Session Protocol
|
||||
|
||||
**Before ending any session, run this checklist:**
|
||||
**Before ending any session, run this checklist (solo/lead only — workers skip VCS):**
|
||||
|
||||
```bash
|
||||
git status # Check what changed
|
||||
git add <files> # Stage code changes
|
||||
br sync --flush-only # Export beads to JSONL
|
||||
git add .beads/ # Stage beads changes
|
||||
git commit -m "..." # Commit code and beads
|
||||
git push # Push to remote
|
||||
jj status # Check what changed
|
||||
br sync --flush-only # Export beads to JSONL
|
||||
jj commit -m "..." # Commit code and beads (jj auto-tracks all changes)
|
||||
jj bookmark set <name> -r @- # Point bookmark at committed work
|
||||
jj git push -b <name> # Push to remote
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
@@ -491,13 +512,15 @@ git push # Push to remote
|
||||
- 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 run `br sync --flush-only` then commit .beads/ before ending session
|
||||
- Always run `br sync --flush-only` then commit before ending session (jj auto-tracks .beads/)
|
||||
|
||||
<!-- end-bv-agent-instructions -->
|
||||
|
||||
## Landing the Plane (Session Completion)
|
||||
|
||||
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
|
||||
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until push succeeds.
|
||||
|
||||
**WHO RUNS THIS:** Solo agents run it themselves. In multi-agent sessions, ONLY the team lead runs this. Workers skip VCS entirely.
|
||||
|
||||
**MANDATORY WORKFLOW:**
|
||||
|
||||
@@ -506,19 +529,20 @@ git push # Push to remote
|
||||
3. **Update issue status** - Close finished work, update in-progress items
|
||||
4. **PUSH TO REMOTE** - This is MANDATORY:
|
||||
```bash
|
||||
git pull --rebase
|
||||
br sync --flush-only
|
||||
git add .beads/
|
||||
git commit -m "Update beads"
|
||||
git push
|
||||
git status # MUST show "up to date with origin"
|
||||
jj git fetch # Get latest remote state
|
||||
jj rebase -d trunk() # Rebase onto latest trunk if needed
|
||||
br sync --flush-only # Export beads to JSONL
|
||||
jj commit -m "Update beads" # Commit (jj auto-tracks .beads/ changes)
|
||||
jj bookmark set <name> -r @- # Point bookmark at committed work
|
||||
jj git push -b <name> # Push to remote
|
||||
jj log -r '<name>' # Verify bookmark position
|
||||
```
|
||||
5. **Clean up** - Clear stashes, prune remote branches
|
||||
5. **Clean up** - Abandon empty orphan changes if any (`jj abandon <rev>`)
|
||||
6. **Verify** - All changes committed AND pushed
|
||||
7. **Hand off** - Provide context for next session
|
||||
|
||||
**CRITICAL RULES:**
|
||||
- Work is NOT complete until `git push` succeeds
|
||||
- Work is NOT complete until `jj 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
|
||||
|
||||
Reference in New Issue
Block a user