Metadata-Version: 2.5
Name: beacon-framework
Version: 1.18.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

> "Would I proudly sign my name to this?"

## What is this

BEACON is a command-line tool and a set of agent instructions for software that you build with AI coding agents. It puts a light, file-based process into your repository: a problem statement, epics, decision records and a health check. It is for a team or a single developer who wants agents to plan, build and ship work with the same discipline every time. BEACON controls the product side of the work: strategy, epics, ADRs and the phases. [SpecKit](https://github.com/github/spec-kit) controls the engineering side of each feature: the spec, the plan and the tasks. You can install each one without the other.

## What you can do

| Task | Command | Section |
|---|---|---|
| Install BEACON in a project | `beacon init --here` | [Install BEACON in a project](#install-beacon-in-a-project) |
| Check the health of a project | `beacon doctor` | [Check the health of a project](#check-the-health-of-a-project) |
| Write the problem statement | `beacon seed scaffold` | [Write the problem statement](#write-the-problem-statement) |
| Plan an initiative as an epic | `beacon epic new user-auth --title "User sign-in"` | [Plan an initiative as an epic](#plan-an-initiative-as-an-epic) |
| Start and finish a piece of work | `beacon bullet start "Fix the login timeout"` | [Start and finish a piece of work](#start-and-finish-a-piece-of-work) |
| Connect a spec to its epic | `beacon link-spec 001-oauth-login --epic user-auth` | [Connect a spec to its epic](#connect-a-spec-to-its-epic) |
| Check the documentation | `beacon docs check` | [Check the documentation](#check-the-documentation) |
| Share the roadmap | `beacon roadmap export` | [Share the roadmap](#share-the-roadmap) |
| Upgrade BEACON in a project | `beacon upgrade --here` | [Upgrade BEACON in a project](#upgrade-beacon-in-a-project) |
| Add an agent harness or a release pipeline | `beacon integration add opencode` | [Add an agent harness or a release pipeline](#add-an-agent-harness-or-a-release-pipeline) |

## Install

You need [uv](https://docs.astral.sh/uv/), the Python tool manager from Astral. Install the `beacon` tool one time on each computer:

```bash
uv tool install beacon-framework
```

To use BEACON with no permanent install, run it through `uvx`:

```bash
uvx --from beacon-framework beacon init --here
```

To use the newest code from the `main` branch, run this command. That code can be ahead of the latest release.

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

**For an AI agent:** give the agent the [agent guide](docs/agent-guide.md). It has the full procedure to install and use BEACON. The agent can read it at `https://raw.githubusercontent.com/darth-veitcher/beacon/main/docs/agent-guide.md`.

## Quickstart

Install the tool, add BEACON to a git repository, and check the health of the project:

```bash
uv tool install beacon-framework
cd my-project
beacon init --here --no-speckit
beacon doctor
```

The doctor shows one line for each check, and a count at the end. In a new install, the `problem-statement` check fails until you write the problem statement. The next step is [Write the problem statement](#write-the-problem-statement).

## Install BEACON in a project

Go to the root of your project, and run:

```bash
beacon init --here
```

BEACON writes the `project-management/` directory, `docs/WRITING.md`, and the agent instructions in `.claude/`. Then it offers to install SpecKit. SpecKit is not necessary, but the SpecKit wrappers (`/beacon.specify`, `/beacon.plan`, `/beacon.tasks` and `/beacon.implement`) need it. To answer before BEACON asks, add `--speckit` or `--no-speckit`.

You can run `beacon init` again safely. It does not replace the files that you write, such as the problem statement.

To set the language of the quality gates, add `--language python`, `--language node` or `--language rust`. Python is the default.

The result ends with lines like these:

```
✓ BEACON <version> installed at <path>
  language: python
  framework files written: <N>
  user-seeded files written: <N> (existing left intact)
  integrations: claude
```

A **framework file** belongs to BEACON, and `beacon upgrade` replaces it. A **user-seeded file** is a start for you to edit, and BEACON never replaces it. To add BEACON to a repository that has code and history, read [Add BEACON to an existing project](docs/existing-project.md). For the list of files, read [Files that BEACON installs](docs/installed-files.md).

## Check the health of a project

```bash
beacon doctor
```

The doctor reads the files and the git history of the project and runs 38 checks. Each line shows one check:

```
✗ problem-statement: Placeholder text still in problem statement: … Fill in 00-problem-statement.md before opening a feature branch.
✓ spec-backlink-integrity: All 1 spec folder(s) backlink an epic.
! roadmap-staleness: Roadmap/README.md has no `Last reviewed: YYYY-MM-DD` header.

ok=11  warn=2  fail=1
```

- `✓` (OK) means that the check found nothing to do.
- `!` (WARN) means that something is incomplete or old. Fix it before the work is done.
- `✗` (FAIL) means that a gate is broken. The command exits with code 1.

A new install always fails `problem-statement`, until you write the problem statement. Use `beacon doctor --strict` in CI and before a pull request. It changes each WARN to a FAIL, except a few WARNs that only record known technical debt.

To learn what one check does, run `beacon doctor --explain <check>`. To see every finding behind a short line, run `beacon doctor --verbose`. To see all the checks, run `beacon help doctor`. To turn off a check, add its name to `disabled_checks` in `project-management/.beacon/doctor.toml`.

## Write the problem statement

The first phase, SEED, gives the project one problem, one user, success criteria and non-goals. Start the conversation in the terminal:

```bash
beacon seed scaffold
```

It asks one question for each part of the template, in plain language. Then check the result:

```bash
beacon seed
```

The result shows four lines: the problem statement, the architecture, the roadmap vision and the date of the last roadmap review. The command exits with code 0 when no line is a FAIL. In Claude Code, `/beacon.seed` does the same work: it asks one or two broad questions, and then it suggests a value for each part.

## Plan an initiative as an epic

An **epic** is an initiative that takes some weeks. It collects one or more specs and the decisions that cross them.

```bash
beacon epic new user-auth --title "User sign-in"
```

This makes `project-management/Roadmap/epics/user-auth.md`. Write its sections: Status, Why now, Dependencies, ADRs, Success criteria and Non-goals. BEACON fills in the Specs section. Then use these commands:

```bash
beacon epic list --detailed      # active epics, with their specs and ADRs
beacon epic refresh user-auth    # count the specs that are shipped, in progress and missing
beacon epic stub user-auth "Password reset"   # add a placeholder spec for planned work
beacon epic finish user-auth     # move the epic to the archive
```

`beacon epic finish` refuses while a spec of the epic is in progress. BEACON reads the git history to find shipped specs: a spec is shipped when its branch is merged into the trunk. A box that is still open in its `tasks.md` does not change that.

## Start and finish a piece of work

A **bullet** is the piece of work on the current git branch. BEACON finds it from the branch, so agents in different worktrees never edit the same file.

```bash
git checkout -b fix/login-timeout
beacon bullet start "Fix the login timeout" --epic user-auth
```

On a spec branch (`NNN-slug`), the bullet is the first open task in `specs/NNN-slug/tasks.md`, and it needs no title. On other branches, BEACON records the bullet in `project-management/.beacon/bullets.toml`, which you commit. Use `--no-epic` for a quick fix that belongs to no epic.

```bash
beacon bullet status    # show the bullet of this branch
beacon bullet list      # show all bullets on local branches, by epic
beacon bullet finish    # mark it done (on a spec branch: beacon bullet finish <task-id>)
beacon bullet sweep     # remove bullets whose branch is merged or deleted
```

After the pull request of a spec merges, `beacon spec finish NNN-slug` closes the boxes that are still open and refreshes its epic. This step is optional, because BEACON already reads shipped state from git.

## Connect a spec to its epic

A **spec** is a SpecKit feature directory, `specs/NNN-slug/`. In Claude Code, `/beacon.specify <epic> <feature>` makes the spec and connects it. If you made the spec with `/speckit-specify`, connect it yourself:

```bash
beacon link-spec 001-oauth-login --epic user-auth
```

This writes the file `.beacon.toml` in the spec directory, and adds the spec to the Specs section of the epic. Two commands find unfinished text before you build:

```bash
beacon spec validate 001-oauth-login   # placeholders and open questions in spec.md
beacon plan validate 001-oauth-login   # placeholders and missing ADRs in plan.md
```

Each command shows each problem as `file:line` and exits with code 1 if it finds one.

## Check the documentation

Each project has the writing standard in `docs/WRITING.md`. It uses ASD-STE100 Simplified Technical English. It applies to `README.md`, `docs/`, `AGENTS.md`, the `--help` text of a command, and the ADRs, epics, specs and plans.

```bash
beacon docs check
```

The check shows each finding as `file:line: rule: message`. It finds each sentence of more than 25 words, and each planning label in `README.md` or `docs/`. It also finds a fixed heading of `README.md` that is missing or in the wrong order, and a missing `README.md` or `AGENTS.md`. The command exits with code 1 on a finding, and with code 2 on a wrong option. The doctor runs the same rules as the checks `writing` and `writing-artefacts`, but it does not report a missing file.

To check one ADR, epic, spec or plan, add `--file <path>`. A path to a directory checks each Markdown file in it. To convert old pages in stages, leave out each page that you did not convert yet:

```bash
beacon docs check --exclude docs/old-guide.md
```

To check the `--help` text of a command, give each help text as one record on standard input. The first line of a record is its source name, which each finding shows in place of a file name. A NUL character ends the record:

```bash
printf 'tool fetch --help\nDownload a pinned model.\0' | beacon docs check --text - --null
```

A script cannot read the STE dictionary. Thus in Claude Code, run `/beacon.docs`: it writes the change with the `beacon-docs` skill, and the `beacon-docs-reviewer` agent checks the words and the facts.

To make an example run as a test, put `# beacon:test` in its Python code block. `beacon docs verify` runs each of these blocks in `README.md` and `docs/`.

## Share the roadmap

```bash
beacon roadmap export    # write ROADMAP.md, to commit
beacon roadmap render    # write ROADMAP.html, to open in a browser
```

`ROADMAP.md` starts with the horizon from `Roadmap/README.md`: the vision, and Now, Next and Later. Then it gives the sequence of the epics from their dependencies, the status of each epic, the active bullets and the ADRs. It has no calendar dates, because the order of the work is more useful than estimated durations. For the HTML views and a CI example, read [Share the roadmap](docs/roadmap.md).

## Upgrade BEACON in a project

An upgrade has two steps. If you do only the first step, the files in the project stay at the old version.

```bash
uv tool upgrade beacon-framework    # 1. upgrade the tool on this computer
beacon upgrade --here               # 2. refresh the framework files in this project
beacon doctor --here                # 3. check the result
```

`beacon upgrade` replaces the framework files and does not touch the user-seeded files. It never commits. Read the diff. Then commit it. For the full procedure, read [Upgrade BEACON](docs/upgrade.md).

## Add an agent harness or a release pipeline

An **agent harness** is the program that runs the AI agent. BEACON installs for Claude Code by default. It can also install for opencode and for DeepSeek Harness (DSH). For what each harness gets, read [Files that BEACON installs](docs/installed-files.md#find-the-files-of-each-agent-harness).

```bash
beacon integration list
beacon integration add opencode    # or: dsh, claude, release
beacon integration remove opencode
```

The `release` integration adds a pipeline that publishes a Python package to PyPI from the trunk. It adds `.github/workflows/release.yml`, `PUBLISHING.md` and a `[tool.semantic_release]` table in `pyproject.toml`. `beacon integration remove release` removes the workflow and the table, and keeps `PUBLISHING.md`.

## Limits

- BEACON does not write specs, plans or tasks. SpecKit does that, and BEACON only adds one file, `.beacon.toml`, in each spec directory.
- BEACON never commits, creates branches or pushes. You or your agent do that.
- The `writing` checks find only long sentences, planning labels and the fixed headings of `README.md`. They cannot find words that ASD-STE100 does not approve.
- The DSH harness gets the skills and the instructions only. Its commands and subagents need a Cordis plugin, which BEACON does not have yet.
- The `release` integration is for Python packages on PyPI only.

## Technical notes

- **Independence from SpecKit.** BEACON imports nothing from SpecKit. All `beacon` commands work without SpecKit, and the checks for specs do nothing when there are no specs. BEACON writes nothing in `.specify/`, and SpecKit writes nothing in `project-management/`.
- **SpecKit version.** `beacon init` installs `specify-cli` 1.0.9 from PyPI. The pin is `SPECKIT_CLI_VERSION` in `src/beacon/integrations/claude_code.py`.
- **The manifest.** `project-management/.beacon/init-options.json` records the BEACON version, the integrations, and which files are framework files and which are user-seeded files.
- **Languages.** Each language is a TOML file in `src/beacon/resources/languages/`. To add a language, add a file there. `python` uses `uv run ruff` and `uv run ty check`. `node` uses `bun run lint` and `bunx tsc --noEmit`. `rust` uses `cargo fmt`, `cargo clippy -- -D warnings` and `cargo test`. The `language-consistency` check warns if the marker file of the language (`pyproject.toml`, `package.json` or `Cargo.toml`) is missing.
- **Versions.** BEACON uses [semantic versioning](https://semver.org). Each commit on `main` of the type `feat`, `fix` or `perf` makes a release.
- **SpecKit wrappers.** Each SpecKit wrapper, such as `/beacon.plan`, includes the SpecKit skill with `@<path>`. Thus a SpecKit update needs no change in BEACON.
- **License.** MIT. See [LICENSE](LICENSE).
- **Further reading.** [BEACON.md](BEACON.md) is the full framework specification. [pragmatic-principles.md](pragmatic-principles.md) gives the operating principles for agents. [The command reference](docs/commands.md) lists each command and each Claude Code slash command.

## Develop

To work on BEACON itself, read [AGENTS.md](AGENTS.md). It gives the commands, the rules and the map of the code. In short:

```bash
uv sync
uv run pytest -q
uv run ruff check && uv run ruff format --check
uv run beacon docs check
```

## Glossary

- **ADR**: an architecture decision record, a file in `project-management/ADRs/` in the [MADR](https://adr.github.io/madr/) format. It records one decision and its reasons.
- **Agent harness**: the program that runs an AI coding agent, for example Claude Code or opencode.
- **ASD-STE100**: Simplified Technical English, a controlled language with approved words and short sentences.
- **Bullet**: the piece of work on the current git branch. BEACON finds it from the branch name.
- **Constitution**: the rules of a project that the SpecKit plan gate checks, in `.specify/memory/constitution.md`.
- **Epic**: an initiative of some weeks, in `project-management/Roadmap/epics/`. It collects specs and the ADRs that cross them.
- **Framework file**: a file that BEACON owns. `beacon upgrade` replaces it, and the doctor warns if you edit it.
- **Manifest**: the file `project-management/.beacon/init-options.json`, which records what BEACON installed.
- **Phase**: one of the four stages of the work: SEED, DESIGN, BUILD and SHIP.
- **Slug**: a short name in lowercase words with hyphens, for example `user-auth`. A spec directory puts a number before it: `NNN-slug`.
- **SpecKit**: the GitHub tool that writes a spec, a plan and tasks for each feature.
- **SpecKit wrapper**: a BEACON command, such as `/beacon.plan`, that includes a SpecKit skill and adds BEACON steps.
- **Spec**: a SpecKit feature directory, `specs/NNN-slug/`.
- **Tracer bullet**: a small piece of work that goes through all the layers of the system. You can show its result to a user.
- **Trunk**: the main branch. Each branch starts from it, and each pull request goes back to it.
- **User-seeded file**: a file that BEACON writes once as a start. You own it, and BEACON never replaces it.
- **Worktree**: a second working directory of the same git repository, with its own branch.
