From 6f18e72272167e0159b68bc1bb4f9699608ad11e Mon Sep 17 00:00:00 2001
From: Alexander Miroshnichenko <alex@millerson.name>
Date: Wed, 27 May 2026 22:01:26 +0300
Subject: [PATCH] docs(AGENTS): add mandatory beads workflow section before any
 work

Make bd usage explicit with a "Before Starting Any Work" section,
updated example workflow, and strengthened quick reference rules.
This prevents agents from using TodoWrite or other non-bd tracking.
---
 AGENTS.md | 35 ++++++++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f129e90..9b5d4fe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,17 @@ This is a **Nix flake overlay** repository that provides additional packages for
 3. Touch only what you must. Clean up only your own mess.
 4. Define success criteria. Loop until verified.
 
+## Before Starting Any Work
+
+**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`.
+
+Violating this rule means the agent is working outside the project's workflow. Stop and re-claim via `bd` first.
+
 ### Required Skills
 
 Always use these skills when working with this repository:
@@ -316,6 +327,11 @@ This skill provides:
 ## Example Workflow: Adding a New Package
 
 ```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
+
 # 1. Create package directory
 mkdir -p packages/my-tool
 
@@ -327,6 +343,9 @@ cat > packages/my-tool/default.nix << 'EOF'
 pkgs.callPackage ./package.nix { }
 EOF
 
+# 3.5. Stage for Blueprint discovery
+git add packages/my-tool/
+
 # 4. Test build
 nix build .#my-tool
 
@@ -337,6 +356,9 @@ nix build .#my-tool
 # 7. Commit changes using conventional-commit skill
 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
 ```
 
 <!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
@@ -347,17 +369,20 @@ This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full
 ### 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
-bd close <id>         # Complete work
+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` for detailed command reference and session close protocol
-- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+- **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