Operational guidance for AI coding agents—not setup docs, but best practices for using tools well.
Most agent documentation answers "how do I install this?" This repo answers "how do I use it thoughtfully?"
An agent can learn commands from --help but can't infer why certain patterns exist or when to apply them. These docs fill that gap.
Reference docs for agents. Link to these from your AGENTS.md or CLAUDE.md so agents understand why certain patterns exist and when to apply them.
Operational guidance for br (beads_rust). Covers issue design, field semantics, and agent workflows.
| Document | Purpose |
|---|---|
| README | Operational differences, hierarchical IDs, claim workflow |
| Issue Design | Why fields exist and how to use them |
| Field Semantics | Description vs design vs acceptance vs notes |
| When to Create Issues | Recognizing and filing discovered work |
| Issues vs Planning Docs | Why issues should be self-contained |
| Code in Issues | When to include code snippets |
| Examples | Before/after issue creation patterns |
| Safety | Sync guards, history, data protection |
Copyable skill files for Claude, Codex, and other agents. Drop a skill into your agent's skill directory and it becomes available as a slash command.
Agent skill for tracking multi-session work with br (beads_rust). Covers session startup, claiming and closing issues, keeping resumable notes, syncing JSONL/DB, configuring prefixes, migrating from bd, and troubleshooting.
| Document | Purpose |
|---|---|
| SKILL.md | Full skill: session workflow, core commands, sync protocol, config, migration, troubleshooting |
Key concepts: explicit sync (never automatic git), --claim for atomic assignment, resumable notes structure (COMPLETED / IN_PROGRESS / NEXT / BLOCKERS), safety guards against data loss.
Cross-agent negotiation protocol for planning documents. Gives multiple reasoning agents (human or software) a shared format for proposing, reviewing, disputing, and closing plans without drift or rewrite loops.
| Document | Purpose |
|---|---|
| SKILL.md | Canonical protocol: storage, naming, frontmatter, dispute tracking, review protocol, activation policy |
| Plan Template | Starter template for .plan.md files with Inspiration section and decision log examples |
| ADR Template | Starter template for architecture decision records |
| Critique Template | Starter template for plan critiques |
Key concepts: Decision Register (current negotiated position), Decision Log (append-only negotiation history), Inspiration section (accountability anchor for every plan cycle), explicit activation policy (human invokes, agents don't self-activate).
Operational guides — reference from your AGENTS.md or CLAUDE.md:
## Issue Tracking
This project uses beads_rust (`br`). Follow the guidance at:
https://raw.githubusercontent.com/TheEditor/misc_coding_agent_tips_and_scripts/main/agent-operational-guides/beads-rust/README.mdAgent skills — copy into your agent's skill directory:
# br-issue-tracking (for Claude)
cp -r agent-scripts/br-issue-tracking/ .claude/skills/br-issue-tracking/
# plan-pact (for Claude)
cp -r agent-scripts/plan-pact/ .claude/skills/plan-pact/
# For Codex, use .codex/skills/ instead- Jeffrey Emanuel's misc_coding_agent_tips_and_scripts - Setup/configuration focused
- beads_rust repo - Official br documentation and source
MIT
