BEACON

"Would I proudly sign my name to 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 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

Install

You need uv, the Python tool manager from Astral. Install the beacon tool one time on each computer:

uv tool install beacon-framework

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

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.

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

For an AI agent: give the agent the agent guide. 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.

Install BEACON in a project

Go to the root of your project, and run:

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. For the list of files, read Files that BEACON installs.

Check the health of a project

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:

beacon seed scaffold

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

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.

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:

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.

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.

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:

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:

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, and it applies to README.md, docs/, AGENTS.md, ADRs, epics, specs and plans.

beacon docs check

The check shows each sentence of more than 25 words, and each planning label in README.md or docs/, as file:line: rule: message. To check one ADR, epic, spec or plan, add --file <path>. The doctor runs the same check as writing and writing-artefacts. 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.

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

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.

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.

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.

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.

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 and planning labels. 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. 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.
• Further reading. BEACON.md is the full framework specification. pragmatic-principles.md gives the operating principles for agents. The command reference lists each command and each Claude Code slash command.

Develop

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

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 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.

License

MIT. See LICENSE.