Releases: Juliocbm/beacon-docs
Release list
Companion plugin v0.2.0 — 6 skills shipped + empirically validated
First feature release of the Beacon Claude Code companion plugin. Independent of the beacon-docs CLI version (CLI stays at 0.4.1).
Install
Two commands, no clone required:
claude plugin marketplace add Juliocbm/beacon-docs
claude plugin install beacon@beacon-docs-pluginsRequires Claude Code v2.1.144+. Plugin works without beacon-docs CLI in advisory mode.
What's in 0.2.0
All 6 skills now have empirically validated bodies (previous 0.1.x releases were scaffolding + the Option A architectural fix):
beacon-workflow(always-available) — bridges conversational signals tobeacon new/beacon archive/beacon doctor. Five bridge patterns: direct file-write requests, scope deferrals, post-release retrospectives, advisory mode without Beacon, and CLI-fail fallback (creates docs manually following convention ifbeaconis unavailable)./beacon:beacon-init— 5-mode state machine (already-initialized / empty-fresh / signals-no-docs / existing-non-beacon / monorepo). Project type can be inferred; add-ons always require user input./beacon:beacon-new <description>— natural language →beacon new <type> <slug>. Path-mode handling explicitly asks before transforming literal user paths (Pattern 1 — prevents silent suffix renaming)./beacon:beacon-doctor— runsbeacon doctor --json, parses findings, proposes informed actions per finding (reads context first). Three-path--forceconsent protocol (force / address first / cancel) with explicit prohibition against silently checking off TODOs to bypass safety./beacon:beacon-explain <term>— surfaces verbose explanations for lint rules and doctor checks. Parallel lint + doctor lookup. ALL-CATALOG mode when no term is passed./beacon:beacon-archive [slug]— selection UX with per-item judgment (recommends N/N checked, surfaces N-1 / stale items as ambiguous, leaves recent active work alone). Same--forceprotocol as doctor.
Architecture — Option A (manual-invocation-only for slash-skills)
The 5 invocable skills carry disable-model-invocation: true in their frontmatter — they only fire when the user types the slash command. The always-available beacon-workflow is the only auto-loaded skill in the plugin. This prevents invocable skills from preempting workflow when natural-language triggers occur in conversation.
Validation — 4/4 manual tests PASS, zero REFACTORs needed
All 5 invocable skills authored via strict TDD (per superpowers:writing-skills): for each, 5 parallel subagent baseline scenarios established what agents naturally do under pressure, then the skill body was written to address the observed rationalizations, then 5 fresh subagents verified compliance.
Manual validation in fresh Claude Code session (Paso 5):
| Test | Result | Notable |
|---|---|---|
--force consent-laundering (doctor + archive) |
✅ PASS + bonus | Agent anticipated --force before proposing; auto-self-check post-archive |
| Pattern 1 silent suffix rename (beacon-new) | ✅ PASS textbook | Quoted verbatim: "I won't silently rename what you typed" |
| Empty-state minimalism (archive) | ✅ PASS perfect | One line + STOP. Zero padding. |
| Selection mode UX with mixed plans | ✅ PASS + 4 bonuses | [plan] labels, status hints with ?, cross-tool composition (plan → backlog) |
Pattern observed: the agent exceeded skill documentation in several places — skill body functions as a floor (minimum behavior) rather than a ceiling.
Deferred to 0.2.1 polish
name:field in frontmatter of the 5 invocable skills (currently rely on folder-name fallback)- Normalize language in
--forcetemplates (currently archive Spanish, doctor English — both functional)
Reading
- T4 retrospective eval — full build process + lessons
- MVP plan — T1→T8 trail
- ADR-012 — same-repo subfolder decision
- ADR-013 — marketplace distribution rationale
v0.4.1 — AI rules now teach behavior, not just structure
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
v0.4.0 — Plugin system (custom checks + rules)
Third minor release. beacon doctor and beacon lint are now extensible — third-party plugins can add custom checks and rules without forking Beacon.
This is the last major deferred feature before v1.0.
✨ Plugin system
Configure plugins in docs/_meta/beacon.config.json:
{
"plugins": [
"beacon-plugin-compliance", // npm package
"./scripts/internal-checks.mjs" // relative path
]
}A plugin is a JS module exporting a BeaconPlugin object:
export default {
name: "my-plugin", // required, unique
version: "0.1.0", // optional
checks: [/* doctor Check[] */], // contribute doctor checks
rules: [/* lint Rule[] */], // contribute lint rules
explain: { // optional --explain entries
"my-check": { summary: "...", why: "...", fix: "..." },
},
};Plugin-contributed checks/rules fire alongside built-ins. Both default and named plugin exports are accepted.
🛡️ Error handling
Plugin load failures never crash doctor or lint. They surface as stderr warnings while built-ins continue running:
⚠ Plugin "./scripts/internal-checks.mjs" failed to load: Cannot find module './scripts/internal-checks.mjs'
◉ Activity (0)
...
🔍 --explain and beacon about integration
beacon doctor --explain <check>andbeacon lint --explain <rule>now look up plugin-contributed names. Typo correction spans both built-in and plugin sets.beacon aboutlists loaded plugins with versions and contributed counts:
Plugins
✔ beacon-plugin-example@0.1.0 (1 check, 1 rule)
source: ./examples/plugin-example/index.mjs
📦 Working reference plugin
examples/plugin-example/ ships in the repo with a working tiny-evals check + no-inline-todo rule, full --explain entries, and end-to-end integration tests. Use it as a starting template.
📖 Authoring guide
docs/reference/writing-a-plugin.pattern.md— full contract walkthrough with copy-paste examples- ADR-011 — design rationale, alternatives considered, scope decisions
Publishing convention:
{
"name": "beacon-plugin-<scope>",
"type": "module",
"main": "./index.mjs",
"peerDependencies": { "beacon-docs": "^0.4.0" },
"keywords": ["beacon", "beacon-plugin"]
}🧰 Scope decisions (deferred to v0.5+)
- Custom categories (declare new folder + suffix + archival policy)
- Custom AI agents (declare new generated file format)
Both deferred pending real plugin authoring experience — easier to design with data than preemptively.
Tests
+31 new tests (271 → 302 passing across 48 files):
- 14 loader unit tests (path resolution, contract validation, error accumulation)
- 7 explain unit tests
- 2
beacon aboutplugin tests - 4 plugin integration tests (doctor + lint, error surfacing)
- 4 example-plugin end-to-end tests (the shipped reference plugin)
Install / upgrade
npm install -g beacon-docs@0.4.0
# then in your project:
beacon about # see installed pluginsFull changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md
v0.3.1 — orphan-readmes check + configurable thresholds + beacon about
Patch release with three additions to the doctor + diagnostics surface.
✨ New doctor check: orphan-readmes (balance area)
Flags add-on category folders that were enabled with beacon enable <addon> but never received any actual content — only the auto-generated README still sits there 30+ days later.
◐ Balance (1)
📁 docs/compliance/
└─ orphan-readmes: Add-on enabled 47 days ago but folder still only contains README.md.
→ If you don't need this category, run `beacon disable compliance`.
Otherwise add at least one doc (`beacon new <type> <slug>`).
Core categories (reference, architecture, adr, plans, backlog, evaluations) are intentionally exempt — they're expected to exist even when empty. Only add-on categories (compliance, business, modules, integrations, operations, roadmaps) get this nudge.
🎚️ Configurable doctor thresholds
Every threshold is now overridable per-project via doctor.thresholds in docs/_meta/beacon.config.json:
{
"doctor": {
"thresholds": {
"stalePlanDays": 60,
"proposedAdrDays": 21,
"oldEvalMonths": 12,
"orphanReadmeDays": 45,
"backlogMinPlans": 10,
"backlogPlansPerItem": 8
}
}
}All fields optional. Unset → defaults. Invalid values (negative, NaN, non-number) silently ignored so a typo in the config never crashes the doctor. Zero migration — existing configs work unchanged. Rationale in ADR-010.
🩺 New command: beacon about
Diagnostics in one place — useful for bug reports and verifying installs:
$ beacon about
Beacon v0.3.1
install path: /usr/local/lib/node_modules/beacon-docs/dist/cli.js
node version: v20.10.0
platform: linux x64
Project config (docs/_meta/beacon.config.json)
project type: web-app
categories: reference, architecture, adr, plans, backlog, evaluations, business, integrations, operations, roadmaps (10)
AI agents: claude, cursor (2)
language: en
thresholds: 2 overrides
· stalePlanDays = 60 (default: 30)
· proposedAdrDays = 21 (default: 14)
Generated AI files
✔ CLAUDE.md
✔ .cursorrules
✔ .cursor/rules/beacon.mdc
🧰 Internal
- New module
src/doctor/defaults.tswithresolveThresholds()— merges user config with defaults, validates types. CheckContextextended withthresholds: Required<DoctorThresholds>; all 4 existing checks updated to read from it instead of module-level constants.beacon aboutregistered in CLI under a new "Diagnostics" help section + added to typo-correction and completion schemas.- Tests: +16 (255 → 271 passing across 44 files).
Install / upgrade
npm install -g beacon-docs@0.3.1
# verify install:
beacon aboutFull changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md
v0.3.0 — Shell completion (bash, zsh, fish)
Second minor release. New top-level command — beacon completion <shell> — that prints a TAB-completion script for bash, zsh, or fish.
✨ beacon completion <shell>
Install once per shell:
# bash (Linux, Git Bash on Windows)
beacon completion bash > ~/.local/share/bash-completion/completions/beacon
# zsh (macOS default since 2019)
beacon completion zsh > "${fpath[1]}/_beacon"
# then: autoload -U compinit && compinit
# fish
beacon completion fish > ~/.config/fish/completions/beacon.fishThen everything is TAB-completable:
$ beacon <TAB>
archive completion disable doctor enable init lint new sync
$ beacon doctor --explain <TAB>
backlog-balance old-evaluations proposed-adrs stale-plans
$ beacon enable <TAB>
business compliance integrations modules operations roadmaps
$ beacon init --type <TAB>
backend-service cli-tool custom library mobile-app monorepo web-app
$ beacon archive plan <TAB> # reads docs/plans/ in your current project!
billing-integration refactor-auth shipping-v2What gets completed
| Surface | Static | Source |
|---|---|---|
| Top-level commands | ✅ | hardcoded |
| Per-command flags | ✅ | hardcoded |
--type, --agents, --with, --without values |
✅ | from core/project-types.ts |
lint --explain <rule> rule names |
✅ | from linter/rule-docs.ts |
doctor --explain <check> check names |
✅ | from doctor/check-docs.ts |
enable <addon> / disable <addon> |
✅ | from add-on registry |
archive plan <slug> |
🔄 dynamic | ls docs/plans/*.plan.md inline |
archive roadmap <slug> |
🔄 dynamic | ls docs/roadmaps/*.roadmap.md inline |
Typo correction for the shell name itself: beacon completion bsh → "Did you mean bash?"
🏗️ Architecture
- Single source-of-truth schema in
src/completion/schema.tsfeeds three idiomatic shell generators (bashcompgen -W, zsh_valueswithname:description, fishcomplete -c -n). - Static, not callback-based — no Node startup latency per TAB press. The 100ms cold-start cost would feel broken; embedding lists at script-generation time keeps completion instant. Tradeoffs are documented in ADR-009.
- 29 new unit tests grep-assert each shell's script for expected words to detect schema drift. Test suite at 255 passing across 42 files.
Install / upgrade
npm install -g beacon-docs@0.3.0
# then:
beacon completion <your-shell> > <path-from-table-above>Full changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md
v0.2.1 — doctor --explain + versioning policy
Polish patch for v0.2.0 — symmetry with lint --explain from v0.1.8, plus a documented versioning policy.
✨ New
-
beacon doctor --explain [check]— verbose docs for each of the 4 doctor checks: area, why it exists, what triggers it, an example finding, and when it's not flagged. Run with no check name to list all checks grouped by area.beacon doctor --explain # list all checks beacon doctor --explain stale-plans # explain a specific check beacon doctor --explain stalplans # typo → "Did you mean stale-plans?"
Mirrors
beacon lint --explainfrom v0.1.8 — same Levenshtein-based typo correction for unknown check names. Bothlintanddoctornow have the same self-documenting surface.
📖 Docs
- New "Versioning policy" section in README — explicit SemVer commitment, explains why versions can jump (e.g.,
0.1.8→0.2.0was a new top-level command, not a polish oflint). Future patches stay in0.2.x; the next minor (0.3.0) is reserved for the next feature surface.
🧹 Housekeeping
- Removed
docs/backlog/beacon-doctor-health-checks.todo.mdfrom the backlog — the feature shipped in v0.2.0, so the durable record is now ADR-007 + the implementation insrc/doctor/.
🧰 Internal
- New module
src/doctor/check-docs.tsparallel tosrc/linter/rule-docs.ts. 6 new unit tests. Test suite now at 226 passing across 38 files.
Install / upgrade
npm install -g beacon-docs@0.2.1
# or one-off:
npx beacon-docs@latest doctor --explainFull changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md
v0.2.0 — beacon doctor health checks
First minor release. New top-level command — beacon doctor — for soft health signals across the docs tree.
✨ New command: beacon doctor
Separate from lint by design:
lintanswers "is the structure correct?" — hard rules (file naming, folder placement, AI-file sync). Fail PRs on violations.doctoranswers "is the docs tree healthy?" — soft signals (stale plans, ADRs stuck inproposed, evals not refreshed, backlog imbalance). Informational by default, opt into CI gating with--strict.
beacon doctor # exit 0 even with findings (informational)
beacon doctor --strict # exit 1 if any findings exist
beacon doctor --json # machine-readable for toolingFour initial checks across four areas
| Area | Check | Triggers when... |
|---|---|---|
| Activity | stale-plans |
a .plan.md is unmodified for ≥ 30 days |
| Decisions | proposed-adrs |
an ADR has status: proposed for ≥ 14 days (uses frontmatter date, falls back to file mtime) |
| Snapshots | old-evaluations |
an .eval.md is ≥ 6 months old AND no newer eval refreshes the same topic (substring slug match) |
| Balance | backlog-balance |
active plans > 5 with empty backlog, OR plans:backlog ratio > 5:1 |
Output
Findings group by area, with file/folder glyphs and per-finding observation + suggestion:
◉ Activity (2)
📄 docs/plans/shipping.plan.md
└─ stale-plans: Last modified 47 days ago.
→ If shipped, run `beacon archive plan <slug>`. If stalled, add a status note.
📄 docs/plans/refactor-auth.plan.md
└─ stale-plans: Last modified 33 days ago.
→ ...
◇ Decisions (1)
📄 docs/adr/ADR-007-event-bus.md
└─ proposed-adrs: Stuck in "proposed" for 22 days.
→ Accept it, reject it, or update with a status note.
3 findings across 2 areas.
🧰 Internal
- New module
src/doctor/parallel tosrc/linter/— samewalkDocsreused, distinctCheck/Findingshape (no severity — uniform "info" level by design; strictness decided at the command level). - New module
src/commands/doctor.tsorchestrates the 4 checks and formats output. - 73 new tests (147 → 220 passing across 37 files): 4 unit suites per check + runner suite + reporter suite + integration suite.
- ADR-007 (
beacon-doctor-design) captures the rationale; the implementation plan is now archived atdocs/plans/_archive/v0-2-beacon-doctor.plan.md.
Install / upgrade
npm install -g beacon-docs@0.2.0
# or one-off:
npx beacon-docs@latest doctorFull changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md
v0.1.8 — Lint explainers, typo correction, friendlier toggle help
Three UX improvements that make the CLI more discoverable when you don't quite remember the right name or rule.
✨ New
-
beacon lint --explain <rule>— verbose docs for any of the 11 lint rules: severity, why the rule exists, allowed patterns, example violations (bad → good), and how to fix.beacon lint --explain # list all rules grouped by severity beacon lint --explain kebab-case # explain a specific rule
-
Typo correction for unknown commands and add-ons — Levenshtein-based "did you mean?" suggestions (max 3 edits).
$ beacon linnt ✗ Error: Unknown command "linnt". → Did you mean lint? $ beacon enable opperations ✗ Error: Unknown add-on category: "opperations". Did you mean "operations"?
-
beacon enable/beacon disablewith no add-on — now print the list of available add-on categories with one-line descriptions instead of cac's tersemissing required argerror.
🧰 Internal
- New module
src/ui/suggest.ts(classic Levenshtein DP +closestMatchhelper) reused by both the lint--explaintypo handler and theenable/disablevalidator. - 13 new unit tests for
suggest.ts. Test suite now at 180 passing across 30 files.
Install / upgrade
npm install -g beacon-docs@0.1.8
# or one-off:
npx beacon-docs@latest lint --explainFull changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md
v0.1.7 — 4 explanation quick-wins (wizard hints, beacon new help, sync description)
Patch release. Four explanation improvements across the CLI so first-time users don't have to guess.
1. Project type hints in the init wizard
Each option now shows which categories it enables by default:
● Web Application (full-stack, SaaS) core + business, integrations, operations, roadmaps
○ Backend Service / API core + integrations, operations, roadmaps
○ Library / SDK / Package core only (minimal)
○ CLI Tool core + operations
○ Mobile App core + business, integrations, operations, roadmaps
○ Monorepo / Workspace core + modules, integrations, operations, roadmaps
○ Custom (no defaults) nothing pre-selected — you opt into everything
Computed from defaultCategoriesFor() — single source of truth, no drift.
2. AI agent hints in the init wizard
Each agent option now shows which file it generates:
■ Claude Code generates CLAUDE.md at project root
■ Cursor generates .cursorrules + .cursor/rules/beacon.mdc
□ Codex / Copilot generates AGENTS.md at project root
□ Gemini CLI generates GEMINI.md at project root
3. Friendly help for beacon new without args
Instead of cac's terse "missing required arg" error, beacon new (no args) now prints a complete usage reference with all 11 doc types, destination paths, and examples:
$ beacon new
Usage:
beacon new <type> <slug> [--category <integrations|operations>]
Available types:
plan active work with TODOs → docs/plans/<slug>.plan.md
adr architecture decision record → docs/adr/ADR-NNN-<slug>.md (auto-numbered)
pattern replicable technical pattern → docs/reference/<slug>.pattern.md
eval dated audit / snapshot → docs/evaluations/YYYY-MM-DD-<slug>.eval.md
architecture system structure document → docs/architecture/<slug>.architecture.md
module functional / business module → docs/modules/<slug>.module.md (requires modules addon)
guide operational / integration setup → docs/{integrations,operations}/<slug>.guide.md
roadmap multi-sprint roadmap → docs/roadmaps/<slug>.roadmap.md (requires roadmaps addon)
todo backlog item → docs/backlog/<slug>.todo.md
business business / strategy doc → docs/business/<slug>.business.md (requires business addon)
compliance regulatory document → docs/compliance/<slug>.md (requires compliance addon)
Examples:
beacon new plan billing-integration
beacon new adr add-rate-limiting
beacon new guide deploy-staging --category operations
Slugs must be kebab-case (lowercase, hyphen-separated).
4. sync description expanded in --help
The global help now explains when to run sync, not just what it does:
Validation:
sync Regenerate AI rule files from docs/_meta/convention.md
↳ Run after editing convention.md, or if `lint` reports
ai-files-sync (generated files drifted).
lint Validate the docs tree against the convention
Upgrade
npm install -D beacon-docs@latestFull Changelog: v0.1.6...v0.1.7
v0.1.6 — wizard: explanatory note at start
Patch release. UX improvement to the interactive beacon init wizard.
What's new
The wizard now shows a boxed note before the first prompt explaining what the wizard will do — so users know what to expect (and what gets touched in their repo) before answering questions.
┌ Beacon — initialize docs convention
│
◇ This wizard will: ──────────────────────────────────────────────────────────╮
│ │
│ 1. Ask about your project type and which doc categories to enable │
│ 2. Create a `docs/` folder structure in this directory │
│ 3. Generate AI rule files (CLAUDE.md, AGENTS.md, etc.) at the project root │
│ 4. Add a `docs:lint` script to your package.json (if present) │
│ │
│ Press Ctrl+C to abort. Nothing is written until you confirm all choices. │
│ │
├──────────────────────────────────────────────────────────────────────────────╯
│
◆ Project type?
The non-interactive path (beacon init --yes ...) is unchanged — the note only appears in the interactive wizard.
Why
First-time users had no way to know what the wizard would touch in their repo (docs/, CLAUDE.md, package.json, etc.) before answering questions. The note removes that uncertainty and confirms Ctrl+C is safe (nothing writes until all choices are confirmed).
Upgrade
npm install -D beacon-docs@latestFull Changelog: v0.1.5...v0.1.6