beacon-framework 0.21.0

Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery

BEACON

Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery.

"Would I proudly sign my name to this?"

BEACON owns the Product side of delivery — strategy, epics, ADRs, lifecycle discipline. It composes with SpecKit for the Engineering side — per-feature specs, plans, tasks. Each is independently installable; neither writes into the other's files. Active work is discovered from git, not stored — so parallel agents in worktrees never merge-conflict on a central state file.

quarter scope    Roadmap/README.md             ← strategy (BEACON)
weeks scope      Roadmap/epics/<slug>.md       ← initiative (BEACON)
days scope       specs/<NNN-slug>/             ← feature (SpecKit)
hours scope      specs/<NNN-slug>/tasks.md     ← tasks (SpecKit)
seconds scope    git branch + tasks.md state   ← active work (discovered)

---

Install

For humans

Install globally with uv tool (once per machine):

uv tool install beacon-framework

Then from any project:

beacon init --here

Idempotent — re-running is safe. User-seeded files are preserved. beacon init offers to install SpecKit interactively (highly recommended for the /beacon.{specify,plan,tasks,implement} wrappers; everything else works without it). Pass --speckit or --no-speckit to bypass the prompt in non-interactive contexts.

To upgrade later: uv tool upgrade beacon-framework, then beacon upgrade --here in each project. See Upgrading an existing installation for the full two-step flow.

For the full installation walkthrough (including brownfield install), see AGENTS.md. It works equally well as a human read.

Alternative install paths:

# Ephemeral, no global install
uvx --from beacon-framework beacon init --here

# Track main from git (pre-release builds)
uvx --from git+https://github.com/darth-veitcher/beacon beacon init --here

For LLM agents

Fetch the agent guide and follow it:

curl -s https://raw.githubusercontent.com/darth-veitcher/beacon/main/AGENTS.md

AGENTS.md is self-contained: vocabulary, install order (SpecKit then BEACON), workflow end-to-end, command reference, and what to do next on a fresh project.

---

Concepts

Five terms cover everything:

• Epic — a weeks-scope initiative at project-management/Roadmap/epics/<slug>.md. Groups one or more specs. Creating or editing an epic is a BEACON DESIGN-phase activity — produces cross-spec ADRs that no single feature spec.md can capture.
• Spec — a SpecKit feature folder at specs/<NNN-slug>/. SpecKit owns it. BEACON writes one file inside: .beacon.toml, the epic backlink.
• Bullet — the active piece of work in the current git worktree. Discovered live by resolving the current branch.
• ADR — a Markdown decision record at project-management/ADRs/ADR-NNN-<slug>.md (MADR format).
• Phase — SEED → DESIGN → BUILD → SHIP. Lifecycle gates surfaced as Claude Code skills.

---

Commands

Project lifecycle

beacon init [--here] [--language python|node] [--ai claude]   # install (idempotent)
beacon upgrade [--here]                                       # refresh framework files
beacon check [--here]                                         # files-present validation
beacon doctor [--here] [--strict]                             # semantic health check (15 checks)
beacon --version  /  beacon -V                                # show installed version

SEED phase (project bootstrap)

beacon seed                                  # status of the four SEED deliverables
beacon seed --strict                         # CI mode — WARN becomes FAIL
beacon seed scaffold                         # conversational fill-in from the terminal

Inside Claude Code, /beacon.seed runs an inferential scaffold — one or two broad questions, then Claude infers values for every template slot, presents them back plan-mode style, and writes the files on confirmation.

Epics (Product)

beacon epic new <slug> --title "<title>"          # create from template
beacon epic list [--detailed]                     # active epics + owned-spec rollup
beacon epic refresh <slug>                        # recompute spec rollup (read-only)
beacon epic finish <slug>                         # archive; refuses while specs in flight

Shipped state is inferred from git-merge history — a spec whose branch merged to the trunk reads as complete even if its tasks.md still carries a leftover [ ]. No "ship-it marker" checkbox required.

Specs (merge-time bookkeeping)

beacon spec finish <NNN-slug>                     # mark a merged spec shipped (optional tidy-up)

beacon spec finish flips any leftover [ ] to [x] # shipped, records status = "shipped" in the spec sidecar, and refreshes the parent epic. It's optional — the framework already infers shipped state from git — but it's the clean lifecycle command for clearing a leftover checkbox after a PR merges.

Bullets (Engineering, per worktree)

beacon bullet start [<title>] [--epic <slug>]     # start current worktree's bullet
beacon bullet finish                              # mark done
beacon bullet status                              # show current bullet
beacon bullet list                                # all bullets across local branches, grouped by epic
beacon bullet sweep                               # prune bullets whose branch is gone

Spec ↔ epic link

beacon link-spec <NNN-slug> --epic <slug>         # backlink an existing spec to an epic

Integrations

beacon integration list
beacon integration add <name>          # claude (default), release
beacon integration remove <name>

---

Languages

Quality-gate placeholders render per-language at install time:

beacon init --language node       # → bun run lint; bunx tsc --noEmit; …
beacon init --language python     # → uv run ruff; uv run ty check; …  (default)

Add a language by dropping a TOML at src/beacon/resources/languages/<name>.toml.

---

Integrations

beacon integration list shows what's available.

claude (installed by default)

Slash commands (/init, /git:*, /design:*) and the marker-delimited block in .claude/CLAUDE.md that briefs the agent on the lifecycle. If SpecKit is detected at install time, four additional wrappers ship at .claude/commands/beacon/:

Wrapper	Inlines (via @)	Adds before	Adds after
/beacon.specify <epic-slug> <feature>	SpecKit's specify	Epic Success criteria, Non-goals, ADRs	beacon link-spec <NNN-slug> --epic <slug>
/beacon.plan	SpecKit's plan	(none)	Placeholder + ADR-reference sweep
/beacon.tasks	SpecKit's tasks	(none)	(hook in place; no-op today)
/beacon.implement	SpecKit's implement	(none)	beacon epic refresh <slug>; prompt to epic finish if all specs done

Wrappers compose with SpecKit's commands via Claude Code's @<path> inclusion — no prompt duplication, no maintenance burden when SpecKit updates. If SpecKit isn't installed, the wrappers are skipped (with a notice); installing SpecKit later and running beacon upgrade retro-wires them.

Two BEACON-native commands ship unconditionally (no SpecKit needed): /beacon.status reads the repo and reports which phase you're in, its health, and the single recommended next step; /beacon.continue runs that step for you — proposing-then-confirming by default, or dispatching the reversible build-loop steps unattended under --auto (pair it with /loop to keep work advancing while you're away).

release (opt-in)

beacon integration add release

Drops three things into the project:

File	What it is
.github/workflows/release.yml	Branch-based release: push to main → PyPI, push to develop → TestPyPI (pre-release). Framework-owned.
PUBLISHING.md	One-time PyPI/TestPyPI Trusted Publisher registration steps. User-seeded — never overwritten.
[tool.semantic_release] block in pyproject.toml	python-semantic-release config wrapped in # ──── BEACON release integration ──── sentinels. Refuses to clobber an existing hand-authored block.

beacon integration remove release cleanly reverses — deletes the workflow + the fenced PSR block; leaves PUBLISHING.md alone.

---

Health checks

beacon check     # files-present validation against the manifest
beacon doctor    # semantic — 15 checks across content health, active-work integrity, Product↔Engineering drift
beacon doctor --strict   # CI mode — every WARN becomes FAIL

Doctor's 15 checks group into three concerns:

• Content health — placeholder text in 00-problem-statement.md, stale Work/sessions/, ADR coverage, framework files modified on disk.
• Active-work integrity — current worktree has a discoverable bullet (resolved from the committed .beacon/bullets.toml, so it works on a fresh CI clone), no leftover legacy sidecars, spec branches have an active task in tasks.md.
• Product ↔ Engineering drift — every spec has an epic backlink, every backlink is reciprocated in the epic's ## Specs, active branches are tied to active epics, no ghost epics, no lifecycle mismatches, Roadmap reviewed in the last quarter.

Sample output on a project with one epic, one spec, and the problem statement still unfilled:

✗ problem-statement: Placeholder text still in problem statement: [Replace with
   your problem statement] …. Fill in 00-problem-statement.md before opening a
   feature branch.
✓ active-bullet: 001-oauth-login → T001 scaffold OAuth callback (owner: agent-A,
   source: spec)
✓ spec-task-alignment: Active task in 001-oauth-login: T001 — scaffold OAuth
   callback
✓ spec-backlink-integrity: All 1 spec folder(s) backlink an epic.
✓ epic-spec-listed: All spec→epic backlinks are reciprocated in epic files.
✓ epic-coverage: 001-oauth-login → epic user-auth
✓ ghost-epic: All 1 Active epic(s) have current work.
✓ epic-spec-lifecycle: Epic statuses match their owned-spec state.
✓ epic-rollup: user-auth (Active): 1/2 shipped, 1 in flight
! epic-adr-coverage: Active epic(s) with no ADRs listed: user-auth. …
! roadmap-staleness: Roadmap/README.md has no `Last reviewed: YYYY-MM-DD` header.
✓ sessions: No stale session files.
✓ adr-coverage: 0 ADR(s) on file across 5 commits.
✓ drift: Framework files match shipped resources.

ok=11  warn=2  fail=1

A FAIL exits non-zero (--strict does the same for WARN), so it wires cleanly into a pre-commit hook or CI gate.

---

What gets installed

project-management/
├── .beacon/init-options.json              # manifest — pins version, lists framework vs seeded files
├── .beacon/bullets.toml                    # committed — active non-spec bullets, keyed by branch
├── Background/
│   ├── 00-problem-statement.md            # seeded
│   └── 01-final-architecture-document.md  # seeded
├── ADRs/
│   ├── README.md                          # framework
│   └── ADR-000-template.md                # framework (MADR)
├── Roadmap/
│   ├── README.md                          # seeded — STRATEGY only (quarter scope)
│   └── epics/
│       ├── EPIC-TEMPLATE.md               # framework
│       └── archive/.gitkeep
└── Work/
    ├── README.md                          # framework
    ├── branches/.gitkeep                  # legacy sidecars (superseded by .beacon/bullets.toml)
    └── sessions/                          # transient — delete after merge
beacon.md                                  # generated dashboard
.claude/
├── CLAUDE.md                              # BEACON-managed block between <!-- BEACON START/END -->
├── commands/
│   ├── init.md                            # /init (SEED phase)
│   ├── git/{feature,pr,release}.md
│   ├── design/{wardley,evaluate,diagram}.md
│   └── beacon/                            # only if SpecKit detected
│       ├── specify.md  plan.md  tasks.md  implement.md
└── skills/
    ├── beacon-seed/SKILL.md
    ├── beacon-design/SKILL.md
    ├── beacon-build/SKILL.md
    └── beacon-ship/SKILL.md

Framework files are overwritten on beacon upgrade. Seeded files are written only when absent. The manifest is the contract.

---

Adding BEACON to an existing project (brownfield)

BEACON is designed to drop into an existing repo without clobbering anything. From the project root:

beacon init --here

What you can rely on:

You already have	BEACON's behaviour
.claude/CLAUDE.md	Your content stays. A <!-- BEACON START --> … <!-- BEACON END --> block is appended at the bottom; only that block is refreshed on re-runs.
project-management/ directory with your own notes/ADRs	Sibling files preserved. BEACON adds its own subtree alongside. Files at BEACON paths are left alone if user-seeded; framework files overwrite.
src/, tests/, pyproject.toml, README.md	Untouched. BEACON writes only inside .claude/, project-management/, and beacon.md.
Existing git history + branches	Untouched. BEACON reads git state; it never commits or branches on your behalf.
Pre-existing SpecKit (.claude/skills/speckit-*/ or legacy .claude/commands/speckit.*.md)	Detected; the four /beacon.{specify,plan,tasks,implement} wrappers install on top via @-includes.
Legacy Prompts/ from BEACON ≤ 0.3	Auto-deleted; the v0.4+ phase guidance lives in .claude/skills/beacon-*/.
Legacy Roadmap/README.md with ## Active Bullet (≤ 0.5)	A Roadmap/MIGRATION_v0.6.md breadcrumb is dropped non-destructively; your content stays.

Verify before you commit:

git status                            # see exactly what BEACON added/modified
git diff .claude/CLAUDE.md            # confirm only the marker block changed

Try it ephemerally without the global install:

uvx --from beacon-framework beacon init --here
git status                            # decide whether to keep

---

Upgrading an existing installation

Upgrading a project that already has an earlier BEACON in place is two steps — and missing the second is the usual gotcha:

1. Upgrade the CLI tool — the beacon program on your machine.
2. Refresh the project's files — beacon upgrade --here rewrites the framework files inside this repo to match the new CLI. Upgrading the tool alone does not touch files already written into your project; the manifest stays pinned to the old version until you run this.

# 1. Upgrade the installed CLI (global tool install)
uv tool upgrade beacon-framework

# 2. Confirm the new version
beacon --version

# 3. Refresh this project's framework files (run from the project root)
beacon upgrade --here

# 4. Verify the result
beacon doctor --here

You should see:

✓ BEACON upgraded to <version>
  files refreshed: <N>
  integrations: claude

No global install? Re-run through uvx, forcing a fresh fetch of the latest release (--refresh bypasses the cache), or pin to a version / git ref:

uvx --refresh --from beacon-framework beacon upgrade --here          # latest published
uvx --from beacon-framework==<version> beacon upgrade --here          # a specific release
uvx --from git+https://github.com/darth-veitcher/beacon beacon upgrade --here   # main (pre-release)

What beacon upgrade changes — and what it leaves alone

Touched	Behaviour
Framework files — templates, skills (.claude/skills/beacon-*/), slash commands (.claude/commands/), the <!-- BEACON START/END --> block in .claude/CLAUDE.md	Overwritten with the new version. Don't hand-edit these; your changes are replaced on upgrade.
User-seeded files — Background/00-problem-statement.md, Roadmap/README.md, your epics, ADRs you authored, anything outside BEACON's paths	Untouched. Written only when absent at init; upgrade never overwrites them.
Manifest (project-management/.beacon/init-options.json)	beacon_version and installed_at are bumped; files reclassified between framework/seeded across versions are moved to the right list.
SpecKit wrappers (/beacon.{specify,plan,tasks,implement})	SpecKit detection is re-run. If SpecKit was added since your last install, the wrappers are retro-wired. Pass --speckit / --no-speckit to decide non-interactively.
Legacy layouts	Migrations run automatically — e.g. Prompts/ (≤ 0.3) is removed and a Roadmap/MIGRATION_v0.6.md breadcrumb is dropped for ≤ 0.5 roadmaps. See Migration from BEACON ≤ 0.5.

Optional flags persist your preferences into the manifest for future upgrades:

beacon upgrade --here --hooks            # (re-)install Claude Code hooks
beacon upgrade --here --no-hooks         # skip hooks on this and later upgrades
beacon upgrade --here --git-flow trunk   # switch branching model (trunk | gitflow); re-renders /git:* commands

Review and commit

beacon upgrade only writes files — it never commits. Review the diff, then commit so the version bump is recorded:

git status                # framework files refreshed; seeded files unchanged
git diff                  # eyeball what moved — should be framework files + the manifest
git add -A && git commit -m "chore: upgrade BEACON to $(beacon --version)"

If beacon doctor --here flags missing framework files after an upgrade (rare — usually a deleted file), beacon upgrade is also the fix: re-running restores anything in the manifest's framework list.

---

Atomicity

• BEACON imports nothing from SpecKit. No build-time dependency.
• beacon init succeeds on projects with no SpecKit installed; the four /beacon.* wrappers are skipped with a notice. beacon upgrade retro-wires them once SpecKit appears.
• beacon bullet *, beacon epic *, beacon link-spec, beacon doctor all work without SpecKit anywhere on the system. Doctor's spec-aware checks no-op when no spec folders exist.
• BEACON writes nothing into .specify/. SpecKit writes nothing into project-management/. The only file inside specs/<slug>/ BEACON owns is .beacon.toml — SpecKit ignores it.
• Install, upgrade, and remove either framework independently.

---

Migration from BEACON ≤ 0.5

The previous "single Roadmap god-file" model (one Roadmap/README.md with ## Active Bullet lines) doesn't scale to parallel agents. v0.6 replaces it with:

• Roadmap/README.md — strategy only (quarter scope)
• Roadmap/epics/<slug>.md — per-initiative files (weeks scope)
• Per-worktree branches — active state discovered live, not stored

beacon upgrade detects the legacy shape and drops a Roadmap/MIGRATION_v0.6.md breadcrumb non-destructively. Your previous content stays in place; the new template is installed alongside. Follow the migration note to slot in-flight work into the new model.

Phase guides also migrated: project-management/Prompts/0N-PHASE.md (≤ 0.3) → .claude/skills/beacon-*/SKILL.md. beacon upgrade removes the legacy directory automatically.

---

Documentation

• AGENTS.md — install + use, self-contained, agent-readable
• BEACON.md — full framework specification
• pragmatic-principles.md — agent operating principles applied universally by BEACON

License

MIT — see LICENSE.