beacon-framework 0.4.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 pairs a lifecycle discipline (SEED → DESIGN → BUILD → SHIP) with a permanent decision record (ADRs), a single roadmap, and a deliberately transient workspace. It complements Spec Kit — Spec Kit owns spec mechanics; BEACON owns the lifecycle around them. Each is installable and upgradeable independently.

Install

uvx --from git+https://github.com/darth-veitcher/beacon beacon init --here

That writes the BEACON skeleton into the current directory and wires up Claude Code integration. Re-running is safe — your edited files are preserved.

Commands

beacon init [--here] [--ai claude]        # install into a project (idempotent)
beacon upgrade [--here]                   # refresh framework files only
beacon check [--here]                     # validate the install (files-present)
beacon doctor [--here] [--strict]         # semantic health check (placeholders, stale notes, ADR gaps, drift)
beacon integration list                   # list available integrations
beacon integration add <name> [--here]    # add an integration (e.g. `claude`, `release`)
beacon integration remove <name> [--here] # remove an integration
beacon --version  /  beacon -V            # show installed version

Integrations

beacon integration list shows what's available.

claude (installed by default)

Claude Code slash commands (/init, /git:*, /design:*) and the <!-- BEACON --> block in .claude/CLAUDE.md that briefs the agent on the lifecycle and on when to run beacon doctor. Re-run beacon integration add claude or beacon upgrade to refresh.

release — opt-in, production-ready release pipeline

beacon integration add release

Drops three things into your project:

File	What it is
.github/workflows/release.yml	Branch-based release: push to main → PyPI, push to develop → TestPyPI (pre-release). Framework-owned — overwritten on re-install.
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. If you already have a hand-authored PSR config, install warns and skips rather than clobber.

Worked example on a fresh project:

mkdir my-cli && cd my-cli
git init && git checkout -b main
# Minimal pyproject.toml so beacon can read project.name
cat > pyproject.toml <<'EOF'
[project]
name = "my-cli"
version = "0.1.0"
EOF

uvx --from beacon-framework beacon init --here
uvx --from beacon-framework beacon integration add release

# Result:
ls -la .github/workflows/release.yml PUBLISHING.md
grep -c "BEACON release integration" pyproject.toml   # → 2 (start + end sentinels)

After install you still need to do the one-time PyPI side (creating pending publishers + GitHub environments named pypi and testpypi); the installed PUBLISHING.md walks through it. Every push to main then ships a Conventional-Commit-derived version to PyPI; every push to develop ships an X.Y.Z-dev.N pre-release to TestPyPI.

beacon integration remove release cleanly reverses the install — deletes the workflow + the fenced PSR block, leaves PUBLISHING.md alone in case you've edited it.

Health checks

beacon check     # files-present validation (fast; matches the install manifest)
beacon doctor    # semantic health — placeholders, stale Work/sessions, ADR gaps, framework drift
beacon doctor --strict   # CI mode: promotes warnings to failures

Sample doctor output on a fresh install (problem statement not yet written):

✓ manifest: BEACON 0.3.0 installed.
✗ problem-statement: Placeholder text still in problem statement: [Replace with
   your problem statement], [Specific person, role, or team, … . Fill in
   00-problem-statement.md before opening a feature branch.
! roadmap: No Active Bullet line matching '**#N — title**' in Roadmap. Set one
   when starting a bullet.
✓ sessions: No stale session files.
✓ adr-coverage: No ADRs yet (no git history to weigh against).
✓ drift: Framework files match shipped resources.

ok=4  warn=1  fail=1

A FAIL exits non-zero (--strict does the same for warnings) so you can wire it into a pre-commit hook or CI gate.

What gets installed

project-management/
├── Background/
│   ├── 00-problem-statement.md           # seeded (you fill it in)
│   └── 01-final-architecture-document.md # seeded
├── ADRs/
│   ├── README.md                         # framework
│   └── ADR-000-template.md               # framework
├── Roadmap/
│   ├── README.md                         # seeded
│   └── archive/.gitkeep
├── Work/
│   ├── README.md                         # framework
│   └── sessions/  planning/  analysis/   # transient — delete after merge
└── .beacon/init-options.json             # manifest (pins version, lists files)
beacon.md                                 # seeded — 5-line progress dashboard
.claude/
├── CLAUDE.md                             # framework block delimited by <!-- BEACON ... --> markers
├── commands/
│   ├── init.md                           # framework — /init (SEED phase)
│   ├── git/{feature,pr,release}.md       # framework
│   └── design/{wardley,evaluate,diagram}.md   # framework
└── skills/                               # framework — phase guides (auto-activate on entry triggers)
    ├── beacon-seed/SKILL.md   beacon-design/SKILL.md
    └── beacon-build/SKILL.md  beacon-ship/SKILL.md

Migration from BEACON ≤ 0.3: phase prompts used to live in project-management/Prompts/0N-PHASE.md. They are now Claude Code skills under .claude/skills/beacon-*/. beacon upgrade removes the legacy directory automatically — see #9.

Framework files are overwritten on upgrade. Seeded files are written only if absent. The manifest in .beacon/init-options.json is the contract.

Atomicity

BEACON does not write to .specify/ and does not depend on Spec Kit being installed. Spec Kit does not write to project-management/. You can install, upgrade, or remove either framework without touching the other.

The only place where BEACON acknowledges Spec Kit is the /init slash command, which suggests /speckit.specify as the next step if .specify/ is present.

Documentation

• BEACON.md — full framework specification
• pragmatic-principles.md — agent operating system applied universally by BEACON

License

MIT — see LICENSE.