beacon

Universal rules

1. One doc = one category. Never duplicate across folders.
2. Status via folder, never filename. Closed plan → _archive/, never *_DONE.md or *_v2.md.
3. kebab-case for all filenames. No camelCase, no snake_case, no spaces.
4. README required in every category folder.
5. ADRs are append-only. Supersede with a new ADR; never edit an accepted one.
6. Evaluations are immutable snapshots. To revise, create a new dated file.
7. Plans archive to _archive/ when done. Move them, never rename.
8. Generated AI files (this one) must match docs/_meta/convention.md. Run beacon sync after editing the convention.
9. Don't create folders outside the convention. Run beacon enable <addon> or propose an ADR.

Persistence rule: 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.

Project-specific rules

• operations/*.guide.md — deploy guides, admin runbooks, troubleshooting. Post-mortems go in evaluations/.

Workflow triggers — when to create documents

These are the conversational signals that should prompt you to create or update Beacon documents. Treat them as imperatives, not suggestions.

• Design decision made → write an ADR before implementing. Decisions about architecture, dependencies, naming conventions, or future flexibility belong in adr/. Run beacon new adr <slug>. Draft the ADR inline; don't ask permission to write it.
• Multi-step work agreed (3+ distinct actions) → write a plan with checkbox steps. Run beacon new plan <slug> and write bite-sized steps. Check off each step in the same commit that completes it. Don't keep multi-step work only in chat memory.
• Scope deferred → capture it as a backlog item immediately. When the user says "let's do that later", "out of scope for now", "maybe v0.5", or similar, run beacon new todo <slug> and write the why plus acceptance criteria. Don't let deferred work live only in conversation.
• Release shipped or milestone reached → write a dated retrospective eval. Run beacon new eval <slug>-retrospective and capture what worked, what didn't, what you'd do differently. Even a 10-line eval is better than zero.
• Approach explained twice → write a pattern doc. If you find yourself explaining the same technical approach across multiple files or sessions, run beacon new pattern <slug> and capture it in reference/.
• System structure changed → update or add an architecture doc. New module, new layer, new external dependency that affects how the system is shaped — that goes in architecture/.