beacon-framework 0.1.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
beacon integration list                 # list AI integrations
beacon integration add <name>           # wire up an AI tool
beacon integration remove <name>        # remove an AI tool
beacon version

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.