How are you enforcing bead quality and DAG consistency when AI agents create work?

[bath-tub]

We adopted beads last week and are running it with AI agents (Claude/Cursor). One persistent problem: agents create shallow, context-dependent beads that a sub-agent cannot pick up cold.

They tend to omit --design and --acceptance entirely, skip wiring dependencies, and write descriptions that assume session context ("as discussed", "per the spec") rather than being self-contained. The result is a DAG that looks populated but is not actually executable by a fresh agent.

We have added cursor rules enforcing the three dedicated fields and a post-creation gate, which helps when agents follow them. But it surfaces a second problem: the health check surface is fragmented and none of it is composed.

Running bd doctor gives a reassuring ✓ 61 passed while silently skipping ~9 checks with Skipped: requires CGO, and never touching content quality or DAG structure at all. A conscientious agent runs it, sees green, and moves on — having missed 96 issues with no ## Acceptance Criteria and several disconnected subgraphs.

Here is what we are running manually to get a full picture:

Command	Covers
bd doctor	Infrastructure, hooks, sync
bd lint	Missing Acceptance Criteria, Steps to Reproduce, Success Criteria
bd swarm validate <epic>	DAG cycles, orphans, disconnected subgraphs (per epic)
bd stale	Forgotten in-progress issues

None of these call each other.

Stopgap we built: a shell script at .beads/bd-health.sh that composes all four into a single no-argument command. It enumerates all open epics automatically, runs bd doctor + bd lint + bd swarm validate + bd stale across each, and exits non-zero only on cycles or infrastructure errors (lint warnings and cross-epic dependency warnings surface but do not fail). If anyone wants to check out the stopgap: https://gist.github.com/bath-tub/53f29bbe35f393e10429e2ac9967942c

Questions for the community:

1. Is there already a composite health command (bd health or similar) that I have missed?
2. Has anyone wired bd lint or bd swarm validate into a git hook or CI so structural problems are caught before push?
3. Is .beads/PRIME.md the right place to inject creation standards so agents receive them at session start — or does that make bd prime too noisy?
4. How are you actually getting agents to fill in bead content properly? Cursor rules, hook injection, post-creation review — what is working?

Happy to be corrected — we are new to this and may be missing obvious answers.

Looks like similar discussions happened a while back: #366

[peterkc]

Following up from my comment in #2601. I hit the same "shallow beads" problem and landed on a layered approach.

Q3: PRIME.md for creation standards — separate them

I split workflow context from quality standards into different layers:

PRIME.md              → HOW to use beads (commands, session protocol)
Rules / AGENTS.md     → WHAT quality standards apply (field requirements)
bd lint               → WHEN to validate (post-creation, pre-push)

PRIME.md loads at session start and tells the agent how beads works. Creation standards ("always include --design", "descriptions must be self-contained") belong in rules or AGENTS.md because those are behavioral constraints, not workflow reference.

When I mixed both into PRIME.md, the agent treated creation standards as optional context rather than hard constraints. Separating them made enforcement reliable.

Q4: Getting agents to fill fields — three layers

Layer 1: PRIME.md (workflow context)

bd prime loads this automatically. I override the default with a custom .beads/PRIME.md focused on session protocol and command reference. No creation rules in here — keeps it under ~50 lines.

Here's the shape of mine (stripped to the universal parts):

# Beads Workflow Context

> Run `bd prime` after compaction or new session to reload this.

## Session Protocol

1. `bd ready` — find unblocked work
2. `bd show <id>` — read full context before coding
3. `bd update <id> --claim` — claim work atomically
4. Work, appending notes: `bd update <id> --append-notes="session log"`
5. `bd close <id> --reason="what changed + commit ref"`

## Session Close

Before saying "done", complete ALL steps:
- [ ] git add <files>
- [ ] git commit -m "..."
- [ ] git push
- [ ] bd close <id> --reason="..."

Work is NOT done until `git push` succeeds.

## Field Reference

| Field | Purpose |
|-------|---------|
| `--description` | Requirements (what + why) |
| `--design` | Technical approach (how) |
| `--acceptance` | Definition of done |
| `--append-notes` | Session log (append-only — never `--notes`) |

Drop this in .beads/PRIME.md and bd prime picks it up automatically. The default built-in is longer; this is the minimum I've found effective.

Layer 2: Rules or AGENTS.md (behavioral constraints)

For Claude Code (.claude/rules/beads-quality.md):

# Beads Quality

- Descriptions must be self-contained — no "as discussed", "per the spec",
  or session-dependent references. A fresh agent must be able to work the
  bead from `bd show` alone.
- Always include --design for features and tasks
- Always include acceptance criteria for bugs and features
- Use --append-notes (never --notes) for session context
- Close with --reason including commit ref

Claude Code note: Claude Code reads CLAUDE.md, not AGENTS.md. Add @AGENTS.md to your CLAUDE.md to import it. Cursor reads .cursorrules directly.

Layer 3: Validation (catch what slips through)

bd lint catches missing template sections by type. I also use semantic code search to verify implementations match the bead intent — details in my comment on #2601.

The "as discussed" fix

This was my worst offender. One rule killed it:

Descriptions must be self-contained — a fresh agent with no session context must be able to work the bead from bd show alone.

That sentence ended "as discussed" and "per the spec" references. The agent now writes descriptions that stand on their own because the constraint is explicit.

Something you may have missed

Beads ships with ISSUE_CREATION.md in the claude-plugin. It covers when to ask before creating, field usage (design vs acceptance criteria), and making issues resumable across sessions. If your agents aren't loading this resource, the skill may not be wired up.

Your bd-health.sh

I read your gist. Two design choices worth calling out:

• Error vs warning distinction — cycles and doctor failures exit non-zero, lint and stale warnings don't. That's the right call. A missing "Acceptance Criteria" heading shouldn't block work; a cycle in the DAG should.
• Truncation at 10/5 items — keeps output scannable for agents. Agents that see 96 lint warnings in a wall of text tend to ignore all of them.

I don't have an equivalent. My quality comes from upstream enforcement (rules prevent bad beads at creation) rather than downstream validation (lint catches them after). Both approaches complement each other — upstream catches more, downstream catches what slips through. Your composition is a real contribution; a built-in bd health that composes these four would fill an obvious gap.

Connection to #366

You referenced #366 — it's the same root cause seen from two angles. Steve found 17.5% of beads had empty descriptions and shipped a bd-side fix (v0.24+). You're discovering that the bd-side fix isn't enough when agents create dozens of beads in a session. The other half of the fix is agent-side enforcement: rules that make "self-contained descriptions" a hard constraint rather than a suggestion the agent optimizes away under context pressure.

[bath-tub]

@peterkc can you upload your process into a repo or individual gists along with a header comments as to what each item aims to solve for(as specified in your layered approach)?

[peterkc]

Here you go: beads-quality-layers

Three files in one gist:

• README.md — overview of the three layers, why each exists, and how to wire them up (includes the SessionStart hook one-liner)
• PRIME.md — drop in .beads/PRIME.md. Workflow context only — commands, session protocol, field reference.
• beads-quality.md — drop in .claude/rules/ (Claude Code) or add to AGENTS.md / .cursorrules (other tools). Behavioral constraints — self-contained descriptions, required fields, dependency wiring.

Each file has a header comment explaining what layer it serves and where it goes.