beacon-framework 0.3.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

• claude — Claude Code slash commands and the <!-- BEACON --> block in .claude/CLAUDE.md. Installed by default.
• release — Production-ready release pipeline: a GitHub Actions workflow that uses python-semantic-release + PyPI Trusted Publishing to ship main pushes to PyPI and develop pushes to TestPyPI. Drops PUBLISHING.md with the one-time setup instructions and injects a fenced [tool.semantic_release] block into your pyproject.toml.

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
├── Prompts/
│   ├── 01-SEED.md  02-DESIGN.md  03-BUILD.md  04-SHIP.md   # framework (refreshed on upgrade)
├── 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

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.