feat: surface quality/lifecycle commands in prime, template, and doctor#2664
feat: surface quality/lifecycle commands in prime, template, and doctor#2664seanmartinsmith wants to merge 2 commits intosteveyegge:mainfrom
Conversation
…template Dogfooding on 85+ beads showed agents only see ~19 of 100+ commands via bd prime. 26% of close reasons were terse one-liners, --acceptance was never used, and --validate was unknown. This adds visibility for features that already exist but were invisible to agents. Prime output (CLI mode only) now includes: - Close reason format template (Summary/Change/Files/Discovery) - Quality tools section (--validate, --acceptance, --design, bd lint) - Lifecycle & hygiene commands (defer, supersede, stale, orphans, etc.) - Structured workflows (bd formula list, bd mol pour) beads-section.md template (full profile) gets matching condensed sections for non-hook agents (Codex, Factory, Mux, OpenCode). MCP mode and beads-section-minimal.md are unchanged.
Composite check that runs lint, stale, and orphan detection in one pass. Advisory only - warns but never blocks, consistent with the "quality is a choice" philosophy. Three sub-checks: - conventions.lint: open issues missing recommended template sections - conventions.stale: issues inactive for 14+ days - conventions.orphans: issues referenced in commits but still open Each sub-check returns a doctorCheck following the existing pattern. Supports both human-readable and --json output.
|
related: #2654 fixes --validate to check the --acceptance field and adds validation.on-close config |
|
Most of this is good — surfacing existing commands in prime and the template is worthwhile, and However, the Close Reason Format section needs to come out: This is a convention nobody follows yet — actual close reasons in our DB are mostly "Closed" or brief sentences. Injecting a prescriptive template into every agent's prime context burns tokens for a format with zero adoption. If we want structured close reasons, the path is:
Please remove the Close Reason Format block from prime.go and the "Structure close reasons: Summary + Change + Files + Discovery" line from beads-section.md, then this is ready for another look. |
Summary
Surfaces existing but undiscoverable commands in prime output (CLI mode) and
the beads-section.md template. Adds doctor --check=conventions as a composite
of existing checks (lint + stale + orphans). No new commands or behavior -
just visibility for what's already there.
MCP mode and beads-section-minimal.md are unchanged.
Context
#2611 and #2612 documented the discoverability gap from the command/flag
alias angle - agents trying intuitive names that don't match. #2639 and
#2638 address that by adding aliases so wrong guesses work.
this PR addresses the other side: agents that never try commands they don't
know exist. dogfooding on 100's of beads showed bd prime surfaces ~19 of 100+
commands. result: --acceptance never used, --validate unknown, bd human
reinvented manually, 26% of close reasons were terse one-liners.
this fix is adding bullet points to prime and the template - surfacing
features, not adding them. doctor --check=conventions wraps three existing
commands (bd lint, bd stale, bd orphans) into one pass, advisory only.
Changes
two commits, independently cherry-pickable:
Workflows, and Close Reason Format sections to CLI prime output.
beads-section.md gets a condensed version for non-hook agents.
stale (14-day threshold), and orphan detection. warns, never blocks.
follows the existing doctorCheck pattern.
Test plan