New plugin v0.2.0 — Beacon, now inside your Claude Code session → New in v0.4.1 AI rules now teach when to create docs, not just where they go →

Beacon

Trail markers for AI-collaborative codebases.

Opinionated documentation convention + CLI that scaffolds the structure, generates per-vendor AI rule files (Claude, Cursor, Codex, Gemini), lints the result, surfaces health signals, and lets you extend it via plugins.

$ npx beacon-docs init

Read the docs View on GitHub

10commands

11lint rules

5doctor checks

4AI vendors

3shell completions

312tests passing

New in v0.4.1

AI rules that tell agents when to write docs.

Other AI rule files describe structure. Beacon's tell your agent to act: "Decision made → write an ADR." "Multi-step work → write a plan." "Scope deferred → backlog item."

The problem

Stock AI rule files teach where docs go and how they're named — but never when to create them. So your agent faithfully follows your conventions for the few docs it writes, and quietly skips writing the rest.

The fix

v0.4.1 adds workflow triggers, document lifecycle rules, and self-checks to every generated file (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules). Conditional on enabled categories — no noise for things you don't use.

Source-of-truth lives in docs/_meta/convention.md; beacon sync regenerates every vendor file atomically.

CLAUDE.md (excerpt)

## Workflow triggers — when to create documents

- Design decision made → write an ADR before
  implementing. Run beacon new adr <slug>.
  Draft inline; don't ask permission.

- Multi-step work agreed (3+ actions) →
  write a plan with checkbox steps.
  Run beacon new plan <slug>.

- Scope deferred ("let's do that later",
  "out of scope for now") → run
  beacon new todo <slug> with why +
  acceptance criteria. Don't leave in chat only.

- Release shipped → write a dated
  retrospective via beacon new eval <slug>.

## Document lifecycle

- Plans must be checked off as you go.
- Plans must archive when shipped.
- ADRs that supersede must link both ways.
...

Persistence rule: chat memory is session-scoped. If you find yourself relying on it to track a decision or follow-up — write the document instead.

New: companion plugin v0.2.0

Beacon, now inside your Claude Code session.

The companion plugin adds an always-available workflow skill that nudges Claude to use beacon new when a decision, plan, or scope-defer happens in conversation — plus five slash-skills for explicit operations.

Conversational triggers, automatic

You say "decidimos Postgres sobre SQLite" and Claude responds with a draft ADR via beacon new adr — no nag, no prompt to confirm the convention. The skill body knows when to act.

Five slash-skills for explicit ops

/beacon:beacon-init, /beacon:beacon-new, /beacon:beacon-doctor, /beacon:beacon-explain, /beacon:beacon-archive — each one wraps the CLI with informed consent (reads context before destructive ops, asks before silent transforms, surfaces --force requirements explicitly instead of laundering them).

Authored via strict TDD per skill — 5 invocable skills, ~50 subagent pressure scenarios, ZERO refactors needed across the entire T4 build. 4/4 manual validation tests passed.

Example session

You: decidimos Postgres sobre SQLite por el JSON support.

Claude (beacon-workflow loaded):
  Esa es una decisión que necesita un ADR. Lo capturo
  antes de seguir.

$ beacon new adr using-postgres-over-sqlite
  ✔ Created docs/adr/ADR-014-using-postgres-...

  [Drafts ADR inline with Context / Decision /
  Consequences from session memory]

  Revisa el draft. Si está bien, marco accepted
  y seguimos con la migración.

## Install (two commands)

$ claude plugin marketplace add Juliocbm/beacon-docs
$ claude plugin install beacon@beacon-docs-plugins

Architecture: the 5 slash-skills carry disable-model-invocation: true — they only fire when you type the command. The always-available beacon-workflow is the only auto-loaded skill, so the invocables never preempt it on natural-language triggers. Read v0.2.0 release notes →

CLI

10 commands. One mental model.

Scaffold, create, validate, extend. Every command discoverable via beacon --help or TAB completion.

Core lifecycle

beacon init

Interactive scaffold wizard.

7 project types with smart detection from package.json
6 core + 6 opt-in category add-ons
Generates AI rule files for 4 vendors simultaneously
Non-interactive mode for CI with --yes --type=...

beacon new

Type-safe doc creation.

11 doc types: plan, adr, pattern, architecture, module, guide, roadmap, todo, eval, compliance, business
ADRs auto-numbered (ADR-001, ADR-002, ...)
Evaluations date-prefixed (YYYY-MM-DD-name.eval.md)
Frontmatter pre-populated; correct folder enforced

beacon archive

Move shipped work to _archive/.

Works for plans and roadmaps
Blocks on unchecked TODOs unless --force
Updates README references automatically
Status lives in folder, never in filename

beacon sync

Single source of truth.

Edit one convention.md, regenerate everything atomically
Outputs: CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .cursor/rules/beacon.mdc
Idempotent — safe in pre-commit hooks
Drift caught by beacon lint --strict

Validation

beacon lint

11 enforced rules.

Errors: suffix/location, kebab-case, missing READMEs, AI-file drift
Warnings: duplicate titles, oversized files, ADR gaps
--explain <rule> for verbose docs (severity, why, fix)
--strict for CI gate, --json for machine output

beacon doctor

5 health checks. Soft signals.

stale-plans, proposed-adrs, old-evaluations, orphan-readmes, backlog-balance
Exit 0 by default (informational); --strict for CI gating
--explain <check> for verbose docs
Per-project tunable thresholds in beacon.config.json

Add-ons & diagnostics

beacon enable / disable

Toggle add-on categories.

6 add-ons: compliance, business, modules, integrations, operations, roadmaps
No-arg invocation prints the available list
Typo-correction: `beacon enable opperations` → did you mean operations?
Disable refuses on non-empty folders unless --force

beacon completion

TAB-completion for bash / zsh / fish.

Install once: beacon completion bash > /path
Autocompletes commands, flags, addons, doc types, lint rules, check names
Dynamic slug completion for archive plan/roadmap (reads docs/)
Static script — zero Node startup latency per TAB

beacon about

Diagnostics in one place.

Version, install path, Node version, platform
Project type, enabled categories, AI agents, language
Doctor threshold overrides vs defaults
Loaded plugins with version + check/rule counts

Health checks

`beacon doctor` tells you when the tree is drifting.

Lint validates structure. Doctor surfaces health signals — soft observations across four areas, with actionable suggestions. Informational by default; gate CI with --strict.

◉ Activity

stale-plans

Plan files unmodified for ≥ 30 days. Archive or add a status note.

◇ Decisions

proposed-adrs

ADRs stuck in status: proposed for ≥ 14 days. Accept, reject, or supersede.

◈ Snapshots

old-evaluations

Evals ≥ 6 months old with no newer refresh on the same topic.

◐ Balance

orphan-readmes

Add-on folders enabled but containing only their auto-generated README.

◐ Balance

backlog-balance

>5 active plans with empty backlog, or plans:backlog > 5:1.

$ beacon doctor

◉ Activity (2)
  📄 docs/plans/shipping.plan.md
    └─ stale-plans: Last modified 47 days ago.
       → If shipped, run beacon archive plan <slug>.

  📄 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.

Run beacon doctor --explain <check> for verbose docs on any check. Tune thresholds per-project in beacon.config.json under doctor.thresholds.

Extensibility

Plugin system — custom checks and rules without forking.

Beacon ships strong defaults. When your project needs something specific (corporate compliance checks, monorepo shape rules, custom naming), drop in a plugin instead of patching the core.

Configure once

docs/_meta/beacon.config.json


  "projectType": "library",
  "plugins": [
    "beacon-plugin-compliance",
    "./scripts/internal-checks.mjs"
  ]

npm packages or relative paths. Both work.

Write once

my-plugin/index.mjs

export default 
  name: "my-plugin",
  version: "0.1.0",
  checks: [/* doctor Check[] */],
  rules:  [/* lint Rule[]  */],
  explain: 
    "my-check": 
      summary: "...",
      why: "...",
      fix: "...",
    ,
  ,
;

Reuses Beacon's Check and Rule types.

Fire alongside built-ins. Plugin checks and rules run together with Beacon's defaults. --explain works for both.

Failures are non-fatal. A misconfigured plugin warns to stderr; built-in checks keep running. Never bricks doctor or lint.

Discoverable. beacon about lists loaded plugins with versions and contributed counts.

Working reference shipped. See examples/plugin-example/ in the repo. Naming convention: beacon-plugin-<scope>.

Comparison

What's different about Beacon?

No other tool combines convention + enforcement + AI rule generation + plugin extensibility in one place.

Feature	Beacon (this)	Diátaxis framework	adr-tools ADRs only	Hand-written CLAUDE.md	Docusaurus docs site
Opinionated structure
Convention enforcement (linter)
AI rule files generation
Multi-vendor support (Claude/Cursor/Codex/Gemini)
Per-vendor format (.md / .mdc / .cursorrules)
Auto-sync (single source of truth)
Per-doc-type naming convention
Status via folder (not filename)
ADR auto-numbering
Date-prefixed evaluations
Configurable add-ons (compliance, business, modules…)
CI-ready out of the box
Zero config required (sensible defaults)

Yes Partial No

Architecture

Five AI agents. One convention. Zero drift.

Edit the source once. Beacon regenerates every vendor-specific file automatically.

docs/_meta/convention.md

# Documentation Convention
> Project type: library

## Universal rules
1. One doc = one category.
2. Status via folder, never filename.
3. kebab-case for all filenames.
...
## Workflow triggers
- Design decision → beacon new adr
- Multi-step work → beacon new plan
- Scope deferred → beacon new todo
...

beacon sync

→

CLAUDE.md

AGENTS.md

GEMINI.md

.cursorrules

.cursor/rules/beacon.mdc

Edit the convention once. beacon sync regenerates everything. beacon lint --strict catches drift in CI.

Init wizard

7 project types. Smart defaults.

The wizard reads your package.json and suggests the right categories automatically.

web-app

Frontend or fullstack web application.

reference architecture adr plans backlog

backend-service

API, microservice, or server-side application.

reference architecture adr plans operations

library

SDK, npm package, or shared module.

reference architecture adr evaluations

cli-tool

Command-line tool or developer utility.

reference adr plans backlog

mobile-app

iOS, Android, or cross-platform mobile app.

reference architecture adr plans

monorepo

Multi-package or multi-app workspace.

reference architecture adr modules plans

custom

Pick exactly what you need. Fully manual.

your choice

CI / CD

Drop into your existing CI.

Beacon's linter exits with code 1 on errors, making it a first-class CI gate. Add the workflow once and let it catch drift automatically.

Runs only when docs or AI files change (paths filter)
--strict escalates warnings to errors in CI
--json for structured output in tooling
Pair with beacon doctor --strict for health gating

.github/workflows/docs-lint.yml

name: Beacon docs lint
on:
  pull_request:
    paths: ["docs/**", "CLAUDE.md", "AGENTS.md",
             "GEMINI.md", ".cursorrules", ".cursor/**"]
  push:
    branches: [main]
jobs:
  beacon-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx beacon-docs lint --strict
      - run: npx beacon-docs doctor --strict

Start in 30 seconds.

One command. Complete docs structure. AI rules that tell agents when to write.