Metadata-Version: 2.4
Name: beacon-framework
Version: 0.8.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 owns the **Product** side of delivery — strategy, epics, ADRs, lifecycle discipline. It composes with [SpecKit](https://github.com/github/spec-kit) for the **Engineering** side — per-feature specs, plans, tasks. Each is independently installable; neither writes into the other's files. Active work is **discovered** from git, not stored — so parallel agents in worktrees never merge-conflict on a central state file.

```
quarter scope    Roadmap/README.md             ← strategy (BEACON)
weeks scope      Roadmap/epics/<slug>.md       ← initiative (BEACON)
days scope       specs/<NNN-slug>/             ← feature (SpecKit)
hours scope      specs/<NNN-slug>/tasks.md     ← tasks (SpecKit)
seconds scope    git branch + tasks.md state   ← active work (discovered)
```

---

## Install

### For humans

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

Idempotent — re-running is safe. User-seeded files are preserved.

For the full installation walkthrough (including SpecKit setup), see [AGENTS.md](./AGENTS.md). It works equally well as a human read.

### For LLM agents

Fetch the agent guide and follow it:

```bash
curl -s https://raw.githubusercontent.com/darth-veitcher/beacon/main/AGENTS.md
```

`AGENTS.md` is self-contained: vocabulary, install order (SpecKit then BEACON), workflow end-to-end, command reference, and what to do next on a fresh project.

---

## Concepts

Five terms cover everything:

- **Epic** — a weeks-scope initiative at `project-management/Roadmap/epics/<slug>.md`. Groups one or more specs. Creating or editing an epic is a BEACON DESIGN-phase activity — produces cross-spec ADRs that no single feature `spec.md` can capture.
- **Spec** — a SpecKit feature folder at `specs/<NNN-slug>/`. SpecKit owns it. BEACON writes one file inside: `.beacon.toml`, the epic backlink.
- **Bullet** — the active piece of work in the current git worktree. Discovered live by resolving the current branch.
- **ADR** — a Markdown decision record at `project-management/ADRs/ADR-NNN-<slug>.md` (MADR format).
- **Phase** — SEED → DESIGN → BUILD → SHIP. Lifecycle gates surfaced as Claude Code skills.

---

## Commands

### Project lifecycle

```bash
beacon init [--here] [--language python|node] [--ai claude]   # install (idempotent)
beacon upgrade [--here]                                       # refresh framework files
beacon check [--here]                                         # files-present validation
beacon doctor [--here] [--strict]                             # semantic health check (15 checks)
beacon --version  /  beacon -V                                # show installed version
```

### SEED phase (project bootstrap)

```bash
beacon seed                                  # status of the four SEED deliverables
beacon seed --strict                         # CI mode — WARN becomes FAIL
beacon seed scaffold                         # conversational fill-in from the terminal
```

Inside Claude Code, `/beacon.seed` runs an inferential scaffold — one or two broad questions, then Claude infers values for every template slot, presents them back plan-mode style, and writes the files on confirmation.

### Epics (Product)

```bash
beacon epic new <slug> --title "<title>"          # create from template
beacon epic list [--detailed]                     # active epics + owned-spec rollup
beacon epic refresh <slug>                        # recompute spec rollup (read-only)
beacon epic finish <slug>                         # archive; refuses while specs in flight
```

### Bullets (Engineering, per worktree)

```bash
beacon bullet start [<title>] [--epic <slug>]     # start current worktree's bullet
beacon bullet finish                              # mark done
beacon bullet status                              # show current bullet
beacon bullet list                                # all bullets across local branches, grouped by epic
beacon bullet sweep                               # delete orphan sidecars
```

### Spec ↔ epic link

```bash
beacon link-spec <NNN-slug> --epic <slug>         # backlink an existing spec to an epic
```

### Integrations

```bash
beacon integration list
beacon integration add <name>          # claude (default), release
beacon integration remove <name>
```

---

## Languages

Quality-gate placeholders render per-language at install time:

```bash
beacon init --language node       # → bun run lint; bunx tsc --noEmit; …
beacon init --language python     # → uv run ruff; uv run ty check; …  (default)
```

Add a language by dropping a TOML at `src/beacon/resources/languages/<name>.toml`.

---

## Integrations

`beacon integration list` shows what's available.

### `claude` (installed by default)

Slash commands (`/init`, `/git:*`, `/design:*`) and the marker-delimited block in `.claude/CLAUDE.md` that briefs the agent on the lifecycle. If SpecKit is detected at install time, four additional wrappers ship at `.claude/commands/beacon/`:

| Wrapper | Inlines (via `@`) | Adds before | Adds after |
|---|---|---|---|
| `/beacon.specify <epic-slug> <feature>` | SpecKit's specify | Epic Success criteria, Non-goals, ADRs | `beacon link-spec <NNN-slug> --epic <slug>` |
| `/beacon.plan` | SpecKit's plan | (none) | Placeholder + ADR-reference sweep |
| `/beacon.tasks` | SpecKit's tasks | (none) | (hook in place; no-op today) |
| `/beacon.implement` | SpecKit's implement | (none) | `beacon epic refresh <slug>`; prompt to `epic finish` if all specs done |

Wrappers compose with SpecKit's commands via Claude Code's `@<path>` inclusion — no prompt duplication, no maintenance burden when SpecKit updates. If SpecKit isn't installed, the wrappers are skipped (with a notice); installing SpecKit later and running `beacon upgrade` retro-wires them.

### `release` (opt-in)

```bash
beacon integration add release
```

Drops three things into the project:

| File | What it is |
|---|---|
| `.github/workflows/release.yml` | Branch-based release: push to `main` → PyPI, push to `develop` → TestPyPI (pre-release). Framework-owned. |
| `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. Refuses to clobber an existing hand-authored block. |

`beacon integration remove release` cleanly reverses — deletes the workflow + the fenced PSR block; leaves `PUBLISHING.md` alone.

---

## Health checks

```bash
beacon check     # files-present validation against the manifest
beacon doctor    # semantic — 15 checks across content health, active-work integrity, Product↔Engineering drift
beacon doctor --strict   # CI mode — every WARN becomes FAIL
```

Doctor's 15 checks group into three concerns:

- **Content health** — placeholder text in `00-problem-statement.md`, stale `Work/sessions/`, ADR coverage, framework files modified on disk.
- **Active-work integrity** — current worktree has a discoverable bullet, no orphan sidecars, spec branches have an active task in `tasks.md`.
- **Product ↔ Engineering drift** — every spec has an epic backlink, every backlink is reciprocated in the epic's `## Specs`, active branches are tied to active epics, no ghost epics, no lifecycle mismatches, Roadmap reviewed in the last quarter.

Sample output on a project with one epic, one spec, and the problem statement still unfilled:

```
✗ problem-statement: Placeholder text still in problem statement: [Replace with
   your problem statement] …. Fill in 00-problem-statement.md before opening a
   feature branch.
✓ active-bullet: 001-oauth-login → T001 scaffold OAuth callback (owner: agent-A,
   source: spec)
✓ spec-task-alignment: Active task in 001-oauth-login: T001 — scaffold OAuth
   callback
✓ spec-backlink-integrity: All 1 spec folder(s) backlink an epic.
✓ epic-spec-listed: All spec→epic backlinks are reciprocated in epic files.
✓ epic-coverage: 001-oauth-login → epic user-auth
✓ ghost-epic: All 1 Active epic(s) have current work.
✓ epic-spec-lifecycle: Epic statuses match their owned-spec state.
! epic-adr-coverage: Active epic(s) with no ADRs listed: user-auth. …
! roadmap-staleness: Roadmap/README.md has no `Last reviewed: YYYY-MM-DD` header.
✓ sessions: No stale session files.
✓ adr-coverage: 0 ADR(s) on file across 5 commits.
✓ drift: Framework files match shipped resources.

ok=10  warn=2  fail=1
```

A FAIL exits non-zero (`--strict` does the same for WARN), so it wires cleanly into a pre-commit hook or CI gate.

---

## What gets installed

```
project-management/
├── .beacon/init-options.json              # manifest — pins version, lists framework vs seeded files
├── Background/
│   ├── 00-problem-statement.md            # seeded
│   └── 01-final-architecture-document.md  # seeded
├── ADRs/
│   ├── README.md                          # framework
│   └── ADR-000-template.md                # framework (MADR)
├── Roadmap/
│   ├── README.md                          # seeded — STRATEGY only (quarter scope)
│   └── epics/
│       ├── EPIC-TEMPLATE.md               # framework
│       └── archive/.gitkeep
└── Work/
    ├── README.md                          # framework
    ├── branches/.gitkeep                  # per-branch sidecars live here
    └── sessions/                          # transient — delete after merge
beacon.md                                  # generated dashboard
.claude/
├── CLAUDE.md                              # BEACON-managed block between <!-- BEACON START/END -->
├── commands/
│   ├── init.md                            # /init (SEED phase)
│   ├── git/{feature,pr,release}.md
│   ├── design/{wardley,evaluate,diagram}.md
│   └── beacon/                            # only if SpecKit detected
│       ├── specify.md  plan.md  tasks.md  implement.md
└── skills/
    ├── beacon-seed/SKILL.md
    ├── beacon-design/SKILL.md
    ├── beacon-build/SKILL.md
    └── beacon-ship/SKILL.md
```

Framework files are overwritten on `beacon upgrade`. Seeded files are written only when absent. The manifest is the contract.

---

## Atomicity

- BEACON imports nothing from SpecKit. No build-time dependency.
- `beacon init` succeeds on projects with no SpecKit installed; the four `/beacon.*` wrappers are skipped with a notice. `beacon upgrade` retro-wires them once SpecKit appears.
- `beacon bullet *`, `beacon epic *`, `beacon link-spec`, `beacon doctor` all work without SpecKit anywhere on the system. Doctor's spec-aware checks no-op when no spec folders exist.
- BEACON writes nothing into `.specify/`. SpecKit writes nothing into `project-management/`. The only file inside `specs/<slug>/` BEACON owns is `.beacon.toml` — SpecKit ignores it.
- Install, upgrade, and remove either framework independently.

---

## Migration from BEACON ≤ 0.5

The previous "single Roadmap god-file" model (one `Roadmap/README.md` with `## Active Bullet` lines) doesn't scale to parallel agents. v0.6 replaces it with:

- `Roadmap/README.md` — strategy only (quarter scope)
- `Roadmap/epics/<slug>.md` — per-initiative files (weeks scope)
- Per-worktree branches — active state discovered live, not stored

`beacon upgrade` detects the legacy shape and drops a `Roadmap/MIGRATION_v0.6.md` breadcrumb non-destructively. Your previous content stays in place; the new template is installed alongside. Follow the migration note to slot in-flight work into the new model.

Phase guides also migrated: `project-management/Prompts/0N-PHASE.md` (≤ 0.3) → `.claude/skills/beacon-*/SKILL.md`. `beacon upgrade` removes the legacy directory automatically.

---

## Documentation

- [`AGENTS.md`](AGENTS.md) — install + use, self-contained, agent-readable
- [`BEACON.md`](BEACON.md) — full framework specification
- [`pragmatic-principles.md`](pragmatic-principles.md) — agent operating principles applied universally by BEACON

## License

MIT — see [LICENSE](LICENSE).
