From ff67b88ea9bc6fe699b24c26a5c46a69c05b6d38 Mon Sep 17 00:00:00 2001
From: beads/crew/giles <steve.yegge@gmail.com>
Date: Tue, 13 Jan 2026 20:58:07 -0800
Subject: [PATCH] docs: Add agent warning about interactive bd edit command

The bd edit command opens an interactive editor ($EDITOR) which AI agents
cannot use. Added warnings to AGENTS.md, AGENT_INSTRUCTIONS.md, and
cmd/bd/AGENTS.md directing agents to use bd update with flags instead.

Fixes: bd-3ft33

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 AGENTS.md             | 13 +++++++++++++
 AGENT_INSTRUCTIONS.md |  9 +++++++++
 cmd/bd/AGENTS.md      | 13 +++++++++++++
 3 files changed, 35 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 2b6c6f1b..b3f9ec03 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,6 +20,19 @@ This file exists for compatibility with tools that look for AGENTS.md.
 
 See CLAUDE.md "Visual Design System" section for full guidance.
 
+## Agent Warning: Interactive Commands
+
+**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
+
+Use `bd update` with flags instead:
+```bash
+bd update <id> --description "new description"
+bd update <id> --title "new title"
+bd update <id> --design "design notes"
+bd update <id> --notes "additional notes"
+bd update <id> --acceptance "acceptance criteria"
+```
+
 ## Landing the Plane (Session Completion)
 
 **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
index 7d899913..0f501551 100644
--- a/AGENT_INSTRUCTIONS.md
+++ b/AGENT_INSTRUCTIONS.md
@@ -191,6 +191,15 @@ bd show bd-44 --json
 
 ## Agent Session Workflow
 
+**WARNING: DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. Use `bd update` with flags instead:
+```bash
+bd update <id> --description "new description"
+bd update <id> --title "new title"
+bd update <id> --design "design notes"
+bd update <id> --notes "additional notes"
+bd update <id> --acceptance "acceptance criteria"
+```
+
 **IMPORTANT for AI agents:** When you finish making issue changes, always run:
 
 ```bash
diff --git a/cmd/bd/AGENTS.md b/cmd/bd/AGENTS.md
index df7a4af9..61e75b69 100644
--- a/cmd/bd/AGENTS.md
+++ b/cmd/bd/AGENTS.md
@@ -12,6 +12,19 @@ bd close <id>         # Complete work
 bd sync               # Sync with git
 ```
 
+## Agent Warning: Interactive Commands
+
+**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
+
+Use `bd update` with flags instead:
+```bash
+bd update <id> --description "new description"
+bd update <id> --title "new title"
+bd update <id> --design "design notes"
+bd update <id> --notes "additional notes"
+bd update <id> --acceptance "acceptance criteria"
+```
+
 ## Landing the Plane (Session Completion)
 
 **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.