From 09e79fdae7e9b2e450b4d3240cead09ae6ae152c Mon Sep 17 00:00:00 2001
From: actae0n <19864268+xpcmdshell@users.noreply.github.com>
Date: Fri, 2 Jan 2026 11:37:51 -0800
Subject: [PATCH] docs: add agent-managed beads workflow preference

---
 AGENTS.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index fb761f2..87117fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,30 @@
 # Agent Instructions
 
+## Agent-Managed Beads (User Preference)
+
+**The user does NOT interact with bd directly.** Agent handles all issue tracking automatically.
+
+### On session start:
+1. Run `bd ready` to check available tasks
+2. Present options to user in plain language
+3. If no tasks exist, ask what to work on and create issues
+
+### During work:
+- Create parent issues for features: `bd create "Feature: X" -p 0`
+- Create sub-tasks: `bd create "Subtask" -p 1 --parent <id>`
+- Link blockers: `bd dep add <blocked-id> <blocker-id>`
+- Claim work: `bd update <id> --status in_progress`
+
+### On task completion:
+- Close finished work: `bd close <id>`
+- Run `bd ready` to suggest next task
+- Present next options to user
+
+### Key principle:
+User says what they want in plain English. Agent translates to bd commands, executes them, and reports back in plain English.
+
+---
+
 ## Branch Policy
 
 **The `main` branch is protected.** You cannot push directly to main.