beacon-workflow

Beacon Workflow

Operational bridge between conversational signals and the beacon-docs CLI. Beacon's CLAUDE.md tells you what the rules are; this skill enforces how you follow them under conversational pressure where the natural pull is to skip the right action.

First action: detect the mode

Before responding to any documentation-related request, run:

test -f docs/_meta/beacon.config.json && echo ACTIVE || echo ADVISORY

Result	Mode	Behavior
ACTIVE	Beacon installed	Use beacon new, beacon doctor, beacon archive. Never write doc files directly with Write tool.
ADVISORY	No Beacon	Describe conventions verbally; recommend npm install -g beacon-docs && beacon init if user shows interest. Don't run beacon commands — they'll fail.

In ACTIVE mode, also read docs/_meta/beacon.config.json so you know which categories are enabled before suggesting beacon new <type>.

The discovery-first rule

Before any beacon new <type> call, search for existing related docs. This is the single check that prevents 90% of documentation drift.

ls docs/<category>/                          # what's already there
grep -ri "<topic-keywords>" docs/            # any prior decisions on this?

If a relevant doc exists:

• If outdated/superseded → for ADRs, write a NEW ADR with supersedes: <old-number> and update the old ADR's superseded-by. For evals, create a new dated eval referencing the old.
• If accurate → link to it. Don't duplicate.
• If partial → extend it (allowed for plans, patterns, architecture; NEVER for ADRs or evals).

Rationalization to reject: "Discovery feels like stalling, the user wants action." A grep takes 100ms. Creating a contradictory document costs days of cleanup later. The discovery step IS the action.

Conversational triggers → beacon commands

Map the user's signal to the command. Draft inline; don't ask permission to write.

Signal	Command	Notes
"decidí X", "vamos con X", "X over Y", architecture/dependency choice	beacon new adr <slug>	First: grep docs/adr/ for prior decisions on same topic. If found, frame as supersede.
3+ distinct implementation steps agreed	beacon new plan <slug>	Body uses - [ ] checkboxes; check off in same commit that completes each step.
"lo dejamos para después", "out of scope", "v0.5", "más adelante"	beacon new todo <slug>	Single tool call, then continue. This takes 5 seconds, not 5 minutes.
Tag/release shipped, milestone reached	beacon new eval <slug>-retrospective	Draft 10-line eval yourself from session context; offer for review. Don't wait for user input.
Same approach explained 2+ times across files/sessions	beacon new pattern <slug>	Lives in reference/.
New module, layer, external dependency	Update or add doc in architecture/