Beacon — docs convention companion

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), and lints the result.

---

The problem

You're building with AI agents — Claude Code, Cursor, Codex, Gemini CLI. After a few weeks of vibing, your repo has:

• 47 markdown files in random folders
• PLAN_v2_FINAL.md, plan-v2.md, _2025_plan.md — three versions of the same plan
• ADRs duplicated across /docs, /notes, and /decisions
• No CLAUDE.md or .cursorrules telling agents where new docs should go
• A graveyard of "is this still relevant?" content nobody dares delete

The result: neither humans nor AI agents can answer where X lives, whether it's current, or why it exists.

The solution

Beacon ships one opinionated convention and a CLI that enforces it:

• 🗂️ Structure: 6 core folders every project needs + 6 opt-in add-ons (compliance/, business/, modules/, etc.)
• 🏷️ Naming: filename suffix encodes type (.plan.md, .adr.md, .pattern.md), folder encodes status (_archive/)
• 🤖 AI rule files: generates CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, and .cursor/rules/beacon.mdc from a single source — every AI agent gets the rules in its preferred format
• 🚨 Linter: 11 rules validate structure, naming, and AI-file sync (CI-friendly with --strict and --json)
• ⚡ Interactive wizard: project-type-aware defaults via @clack/prompts

Result: AI agents stop creating docs in random places. Humans stop hunting for "the latest version." Reviews stop devolving into "should this be here?"

---

Demo

$ npx beacon-docs init

◆ Project type?
│ ● Library / SDK / Package
│ ○ Web Application
│ ○ Backend Service / API
│ ○ CLI Tool
│ ○ ...

◆ Which categories to enable?
│ ◼ reference  ◼ architecture  ◼ adr  ◼ plans  ◼ backlog  ◼ evaluations
│ ◻ compliance  ◻ business  ◻ modules  ◻ integrations  ◻ operations  ◻ roadmaps

◆ Which AI agents do you use?
│ ◼ Claude Code  ◼ Cursor  ◻ Codex / Copilot  ◻ Gemini CLI

✔ Beacon docs scaffolded at /your/project/docs/

You now have a complete docs tree, AI rule files at the project root, and a docs:lint script added to your package.json. Your next AI session will read CLAUDE.md and know exactly where to put new docs.

---

What you get

your-project/
├── CLAUDE.md                         ← generated, read by Claude Code
├── .cursorrules                      ← generated, legacy Cursor
├── .cursor/rules/beacon.mdc          ← generated, modern Cursor
├── package.json                      ← gets a `docs:lint` script
└── docs/
    ├── README.md                     ← master index, "where do I find X?"
    ├── _meta/
    │   ├── convention.md             ← SINGLE SOURCE OF TRUTH (you edit this)
    │   └── beacon.config.json        ← project type + enabled categories
    ├── reference/                    ← replicable patterns (.pattern.md)
    │   └── README.md
    ├── architecture/                 ← system structure (.architecture.md)
    │   └── README.md
    ├── adr/                          ← decisions (ADR-NNN-*.md, auto-numbered)
    │   └── README.md
    ├── plans/                        ← active work (.plan.md)
    │   ├── README.md
    │   └── _archive/                 ← closed plans (status = folder, not filename)
    ├── backlog/                      ← future items (.todo.md)
    │   └── README.md
    └── evaluations/                  ← audits / snapshots (YYYY-MM-DD-*.eval.md)
        └── README.md

And the generated CLAUDE.md (only the categories your project enabled show up):

<!-- generated by beacon — do not edit. Edit docs/_meta/convention.md and run `beacon sync`. -->

# Documentation Convention

> Project type: **library**. Full convention: [`docs/_meta/convention.md`](docs/_meta/convention.md).

## Universal rules