Metadata-Version: 2.4
Name: beacon-framework
Version: 0.2.0
Summary: Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery
Project-URL: Repository, https://github.com/darth-veitcher/beacon
Author: darth-veitcher
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude-code,framework,spec-driven,tracer-bullets
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# 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](https://github.com/github/spec-kit) — Spec Kit owns spec mechanics; BEACON owns the lifecycle around them. Each is installable and upgradeable independently.

## Install

```bash
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

```bash
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`](BEACON.md) — full framework specification
- [`pragmatic-principles.md`](pragmatic-principles.md) — agent operating system applied universally by BEACON

## License

MIT — see [LICENSE](LICENSE).
