Skip to content

Companion plugin v0.2.0 — 6 skills shipped + empirically validated

Choose a tag to compare

View all tags
@Juliocbm Juliocbm released this 26 May 01:43
claude-plugin-v0.2.0
472630e

First feature release of the Beacon Claude Code companion plugin. Independent of the beacon-docs CLI version (CLI stays at 0.4.1).

Install

Two commands, no clone required:

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

Requires Claude Code v2.1.144+. Plugin works without beacon-docs CLI in advisory mode.

What's in 0.2.0

All 6 skills now have empirically validated bodies (previous 0.1.x releases were scaffolding + the Option A architectural fix):

  • beacon-workflow (always-available) — bridges conversational signals to beacon new / beacon archive / beacon doctor. Five bridge patterns: direct file-write requests, scope deferrals, post-release retrospectives, advisory mode without Beacon, and CLI-fail fallback (creates docs manually following convention if beacon is unavailable).
  • /beacon:beacon-init — 5-mode state machine (already-initialized / empty-fresh / signals-no-docs / existing-non-beacon / monorepo). Project type can be inferred; add-ons always require user input.
  • /beacon:beacon-new <description> — natural language → beacon new <type> <slug>. Path-mode handling explicitly asks before transforming literal user paths (Pattern 1 — prevents silent suffix renaming).
  • /beacon:beacon-doctor — runs beacon doctor --json, parses findings, proposes informed actions per finding (reads context first). Three-path --force consent protocol (force / address first / cancel) with explicit prohibition against silently checking off TODOs to bypass safety.
  • /beacon:beacon-explain <term> — surfaces verbose explanations for lint rules and doctor checks. Parallel lint + doctor lookup. ALL-CATALOG mode when no term is passed.
  • /beacon:beacon-archive [slug] — selection UX with per-item judgment (recommends N/N checked, surfaces N-1 / stale items as ambiguous, leaves recent active work alone). Same --force protocol as doctor.

Architecture — Option A (manual-invocation-only for slash-skills)

The 5 invocable skills carry disable-model-invocation: true in their frontmatter — they only fire when the user types the slash command. The always-available beacon-workflow is the only auto-loaded skill in the plugin. This prevents invocable skills from preempting workflow when natural-language triggers occur in conversation.

Validation — 4/4 manual tests PASS, zero REFACTORs needed

All 5 invocable skills authored via strict TDD (per superpowers:writing-skills): for each, 5 parallel subagent baseline scenarios established what agents naturally do under pressure, then the skill body was written to address the observed rationalizations, then 5 fresh subagents verified compliance.

Manual validation in fresh Claude Code session (Paso 5):

Test Result Notable
--force consent-laundering (doctor + archive) ✅ PASS + bonus Agent anticipated --force before proposing; auto-self-check post-archive
Pattern 1 silent suffix rename (beacon-new) ✅ PASS textbook Quoted verbatim: "I won't silently rename what you typed"
Empty-state minimalism (archive) ✅ PASS perfect One line + STOP. Zero padding.
Selection mode UX with mixed plans ✅ PASS + 4 bonuses [plan] labels, status hints with ?, cross-tool composition (plan → backlog)

Pattern observed: the agent exceeded skill documentation in several places — skill body functions as a floor (minimum behavior) rather than a ceiling.

Deferred to 0.2.1 polish

  • name: field in frontmatter of the 5 invocable skills (currently rely on folder-name fallback)
  • Normalize language in --force templates (currently archive Spanish, doctor English — both functional)

Reading

Assets 2
Loading