From e6cfcc346b411db57939d92bfa7be0c3bd437618 Mon Sep 17 00:00:00 2001
From: m3tm3re <p@m3ta.dev>
Date: Sun, 26 Apr 2026 14:12:30 +0200
Subject: [PATCH] docs(agents): expand Beads workflow documentation

- Add 6-step core workflow with examples
- Document slash commands for agent integration
- Add 'Why Beads?' section emphasizing persistence
- Note to avoid bd edit in agent contexts
- Include dependency linking examples
---
 AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 90 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 77acb08..8e3b0bc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -42,15 +42,99 @@ cp -rf source dest          # NOT: cp -r source dest
 
 ## Beads Issue Tracker
 
-This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+This project uses **bd (beads)** for persistent task tracking. Run `bd prime` for full workflow context.
 
-### Quick Reference
+### Why Beads?
+
+- **Prefer Beads over ad-hoc markdown TODO lists** — Beads provides structured, queryable, shareable issue tracking with dependency management
+- **Never use `bd edit`** — it opens an interactive editor which blocks agent workflows
+- **Use flags and stdin instead** — `bd update <id> --claim`, `bd create --title "..." --estimate 2`
+
+### Slash Commands (Agent Workflow)
+
+| Command | Purpose |
+|---------|---------|
+| `/beads:ready` | Find unblocked issues |
+| `/beads:create` | Create a new issue |
+| `/beads:update` | Update an issue (claim, status) |
+| `/beads:close` | Close completed work |
+| `/beads:stats` | Project-level snapshot |
+
+### Core Workflow (6 Steps)
+
+#### 1. Find Unblocked Work
+```bash
+bd ready --json
+```
+Lists issues with no blocking dependencies that are ready to work on.
+
+#### 2. Claim Work
+```bash
+bd update <id> --claim
+```
+Atomically assigns the issue to you (sets status to "in-progress").
+
+#### 3. Inspect Details
+```bash
+bd show <id>
+```
+View full issue details including:
+- Description and acceptance criteria
+- Blocking/blocked-by dependencies
+- Time estimates
+- Status history
+
+#### 4. Create Newly Discovered Work
+```bash
+# Create a new issue
+bd create \
+  --title "Fix audio on m3-helios" \
+  --estimate 2 \
+  --priority high \
+  --labels nixos,audio
+
+# Link dependencies
+bd dep <id> --blocks <blocked-id>      # This issue blocks another
+bd dep <id> --after <after-id>         # This issue after another completes
+bd dep <id> --requires <requires-id>  # This issue requires another
+```
+
+#### 5. Complete Work
+```bash
+bd close <id> --reason "Added PulseAudio fallback to configuration.nix"
+```
+Provide a concise summary of what was done. The `--reason` is mandatory.
+
+#### 6. Project Snapshot
+```bash
+bd status --json    # Current state of all issues
+bd stats            # Metrics: velocity, cycle time, bottlenecks
+```
+
+### Example Complete Workflow
 
 ```bash
-bd ready              # Find available work
-bd show <id>          # View issue details
-bd update <id> --claim  # Claim work
-bd close <id>         # Complete work
+# Start session - find work
+bd ready --json
+
+# Claim available issue
+bd update 42 --claim
+
+# Do the work...
+
+# Discover something else needed
+bd create --title "Document hermes-agent setup" --estimate 1
+# Link as related
+bd dep 43 --after 42
+
+# Complete original
+bd close 42 --reason "Added Hyprland idle timeout config"
+
+# Close related
+bd close 43 --reason "Added setup docs to AGENTS.md"
+
+# Push state to remote
+bd dolt push
 ```
 
 ### Rules