Metadata-Version: 2.4
Name: beacon-framework
Version: 0.4.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 (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

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

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

```bash
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](https://github.com/darth-veitcher/beacon/issues/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`](BEACON.md) — full framework specification
- [`pragmatic-principles.md`](pragmatic-principles.md) — agent operating system applied universally by BEACON

## License

MIT — see [LICENSE](LICENSE).
