Skip to content

feat: surface quality/lifecycle commands in prime, template, and doctor#2664

Open
seanmartinsmith wants to merge 2 commits intosteveyegge:mainfrom
seanmartinsmith:feat/prime-template-improvements
Open

feat: surface quality/lifecycle commands in prime, template, and doctor#2664
seanmartinsmith wants to merge 2 commits intosteveyegge:mainfrom
seanmartinsmith:feat/prime-template-improvements

Conversation

@seanmartinsmith
Copy link
Contributor

@seanmartinsmith seanmartinsmith commented Mar 17, 2026

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:

  1. prime + template - adds Quality Tools, Lifecycle & Hygiene, Structured
    Workflows, and Close Reason Format sections to CLI prime output.
    beads-section.md gets a condensed version for non-hook agents.
  2. doctor --check=conventions - composite check using existing lint,
    stale (14-day threshold), and orphan detection. warns, never blocks.
    follows the existing doctorCheck pattern.

Test plan

  • bd prime --full shows new sections, bd prime --mcp unchanged
  • bd doctor --check=conventions runs without error (supports --json)
  • script test prime_content.txt, 3 unit tests for conventions check
  • beads-section-minimal.md unchanged

…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.
@seanmartinsmith
Copy link
Contributor Author

related: #2654 fixes --validate to check the --acceptance field and adds validation.on-close config

@steveyegge
Copy link
Owner

Most of this is good — surfacing existing commands in prime and the template is worthwhile, and doctor --check=conventions is a clean composition of existing checks.

However, the Close Reason Format section needs to come out:

## Close Reason Format
When closing non-trivial work, structure the reason:
Summary: [one line - what was done]
Change: [what changed and why]
Files: [key files modified]
Discovery: [what was learned that wasn't known at start]

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:

  1. Discuss the convention as a team
  2. Use validation.on-close from your other PR (fix: --validate checks --acceptance field, add validation.on-close config #2654) to nudge toward it
  3. Only add it to prime once it's an established convention, not to bootstrap one

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants