The most important patch since v1.0. Until now, the AI rule files generated by beacon sync told AI agents where docs go and how they're named — but never when to create them. This patch closes that gap.
The problem
Our own v0.4.0 dogfooding audit (retrospective, behavioral audit) showed that in 12 releases across 3 days, the AI faithfully followed convention for every doc it created — but under-created plans, retrospectives, and backlog items because no rule said "you should be writing one right now."
The 9 universal rules were all defensive ("ADRs are append-only", "don't rename, archive"). Zero were proactive triggers.
What's new in every generated AI rule file
Three new sections, plus a persistence reminder in the universal block:
1. Workflow triggers — conversational signal → beacon command mapping:
- Design decision made → write an ADR before implementing. Run `beacon new adr <slug>`.
Draft inline; don't ask permission.
- Multi-step work agreed (3+ distinct actions) → write a plan with checkbox steps.
Run `beacon new plan <slug>`. Check off steps in the same commit.
- Scope deferred ("let's do that later") → run `beacon new todo <slug>` with why
+ acceptance criteria. Don't leave deferred work in chat only.
- Release shipped → write a dated retrospective. Run `beacon new eval <slug>-retrospective`.
- Approach explained twice → write a pattern doc.
- System structure changed → update architecture/.2. Document lifecycle — maintenance rules for existing docs:
- Plans must be checked off as you go.
- Plans must archive when shipped (`beacon archive plan <slug>`).
- ADRs that supersede must link both ways (update old ADR's `superseded-by`).
- Backlog items graduate to plans (delete the .todo, create the .plan).
- Retrospective evals belong to a moment in time — never edit.3. Self-checks — Beacon's own tools as forcing functions:
- Before committing to docs/: run `beacon lint`.
- Before tagging a release: run `beacon doctor`.
- When uncertain: `beacon lint --explain <rule>` / `beacon doctor --explain <check>`.
- When in a new directory: `beacon about` shows project type, categories, AI-file status.4. Persistence rule (universal section):
"Decisions live in ADRs, multi-step work lives in plans, deferred work lives in backlog, retrospection lives in evals. Chat memory is session-scoped and lost when the conversation ends. If you find yourself relying on chat memory to track a decision, plan, or follow-up — write the document instead."
Per-category conditional rendering
Content is conditional on enabled categories. Projects without backlog/ don't get backlog triggers. Projects without evaluations/ don't get eval rules. Projects with only adr/ enabled get the ADR triggers and nothing else — no empty headings, no irrelevant noise.
Upgrading
npm install -g beacon-docs@0.4.1
beacon sync # regenerate AI files with new sectionsYour docs/_meta/convention.md is not auto-updated — if you want the new behavioral sections in your own convention source, copy them from a fresh beacon init or from the updated template.
Validation
Test suite at 312 passing (+10) across 48 files. New tests cover:
- Persistence-rule presence in universal block
- Per-category trigger inclusion/omission
- Lifecycle returning empty string when no relevant categories enabled
- All 4 vendor files (CLAUDE/AGENTS/GEMINI/Cursor) include the 3 new sections
Effect size
- CLAUDE.md on a typical
cli-toolproject: 35 → 61 lines (+~25 lines of behavioral guidance) - Same delta in AGENTS.md, GEMINI.md, .cursorrules, .cursor/rules/beacon.mdc
Why this is the highest-leverage patch we've shipped
The whole point of Beacon is "AI agents stop creating docs in random places." That claim is only half-true if the rules never tell the AI to create the right docs in the first place. This patch makes the claim whole.
Full design rationale and audit: 2026-05-24-ai-rules-behavioral-effectiveness.eval.md
Full changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md