By Juliocbm
Conversational companion for beacon-docs. Wraps the CLI with slash-skills (init, new, doctor, explain, archive) and an always-available workflow skill that nudges Claude to create the right Beacon documents at the right conversational moments.
Manual slash command (invoke explicitly as /beacon:beacon-new <description>). Translates a natural-language description into a beacon new <type> <slug> invocation. For auto-detected doc creation triggers, beacon-workflow handles them instead.
Use when the user wants to create, organize, or maintain documentation in a project that has beacon-docs installed (look for docs/_meta/beacon.config.json), or when the user mentions design decisions, multi-step work, deferred scope, or release retrospectives in any project.
Manual slash command (invoke explicitly as /beacon:beacon-archive [slug]). Lists active plans (or roadmaps) and helps archive shipped ones with a selection UX, or accepts an optional slug to propose a specific item directly. For auto-detected post-shipping moments where a specific plan should be archived, beacon-workflow handles them instead.
Manual slash command (invoke explicitly as /beacon:beacon-doctor). Runs beacon doctor, parses findings, and proposes specific actions per finding (archive a stale plan, accept a stuck ADR, etc.). For auto-detected pre-release moments, beacon-workflow handles them instead.
Manual slash command (invoke explicitly as /beacon:beacon-explain <term>). Looks up a Beacon lint rule, doctor check, or plugin-contributed item and surfaces the verbose explanation. For auto-detected "what does X do" questions about Beacon internals, beacon-workflow handles them instead.
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
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.
You're building with AI agents — Claude Code, Cursor, Codex, Gemini CLI. After a few weeks of vibing, your repo has:
PLAN_v2_FINAL.md, plan-v2.md, _2025_plan.md — three versions of the same plan/docs, /notes, and /decisionsCLAUDE.md or .cursorrules telling agents where new docs should goThe result: neither humans nor AI agents can answer where X lives, whether it's current, or why it exists.
Beacon ships one opinionated convention and a CLI that enforces it:
compliance/, business/, modules/, etc.).plan.md, .adr.md, .pattern.md), folder encodes status (_archive/)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--strict and --json)@clack/promptsResult: AI agents stop creating docs in random places. Humans stop hunting for "the latest version." Reviews stop devolving into "should this be here?"
$ 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.
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
npx claudepluginhub juliocbm/beacon-docs --plugin beaconComprehensive C4 architecture documentation workflow with bottom-up code analysis, component synthesis, container mapping, and context diagram generation
Plugin-safe Claude Code distribution of Antigravity Awesome Skills with 1,561 supported skills.
Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).
Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
Harness-native ECC operator layer - 67 agents, 271 skills, 92 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses