Metadata-Version: 2.5
Name: beacon-board
Version: 0.1.0
Summary: A markdown-backed kanban board with a CLI, for humans and coding agents sharing one backlog.
Project-URL: Homepage, https://github.com/bojan-gasparovic/beacon-board
Project-URL: Repository, https://github.com/bojan-gasparovic/beacon-board
Project-URL: Issues, https://github.com/bojan-gasparovic/beacon-board/issues
Project-URL: Changelog, https://github.com/bojan-gasparovic/beacon-board/blob/main/CHANGELOG.md
Author-email: Bojan Gasparovic <bojan@zeroemdashes.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,backlog,board,cli,issue-tracker,kanban,markdown,tickets
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# beacon-board

A kanban board backed by markdown files, with a CLI that people and coding
agents can both drive. Tickets are files in a directory. The board is a single
static HTML page. There is no server and no database.

![The board](https://raw.githubusercontent.com/bojan-gasparovic/beacon-board/main/docs/board.png)

## Install

```bash
uvx beacon-board --help        # run without installing
pipx install beacon-board      # or install it
```

## Quickstart

```bash
beacon-board init
beacon-board new --app AB --title "First ticket" --type Task
beacon-board build --open
```

That writes `beacon.toml`, a `tickets/` directory and `board.html`.

## Why the CLI matters

Coding agents are good at writing markdown and bad at remembering which ID comes
next. The CLI closes that gap: it allocates IDs atomically, refuses malformed
tickets at creation, and reports problems instead of silently dropping files.

Give an agent access to the commands and it can read and update the same backlog
you do:

```bash
beacon-board list --status Next --json
beacon-board set AB-07 --status Now
beacon-board comment AB-07 "Reproduced on a clean install."
```

`beacon-board agent-docs` prints an instruction block to paste into whatever
your assistant reads. Nothing here is specific to one tool.

## Tickets

One markdown file per ticket, in `tickets/`.

```markdown
# AB-07: [Bug] Search drops the last result

**Epic:** [AB-03 Search overhaul](AB-03-epic-search-overhaul.md)
**Assignee:** rae
**Depends on:** None
**Related:** AB-04
**Estimate:** S
**Type:** Bug
**Status:** Next

## Objective

The final match is missing from every result page.

## Acceptance Criteria

- [ ] Searching a mailbox with exactly one match shows it.
```

`## Acceptance Criteria` renders as a checklist, so write items as `- [ ]` and
tick them to `- [x]`. Plain bullets render as prose instead, which is why the
section is worth writing consistently. `## Comments` holds dated entries,
oldest first: `- **2026-08-14:** text`.

Three levels: the ID prefix groups tickets into apps, `**Epic:**` groups them
within an app, and everything else is a ticket. A ticket whose `**Epic:**` reads
`Self` is an epic container. With only one prefix in play, the app level
disappears from the board.

## Configuration

`beacon.toml`, found by walking up from the working directory. Every key has a
default, so the file is optional.

```toml
[meta]
name = "My Board"

[[apps]]
prefix = "AB"
label = "My Project"

[statuses]
columns   = ["Later", "Next", "Now", "Done"]
protected = ["Done"]

[assignees.rae]
label = "rae"
color = "#ffffff"
```

`protected` statuses are the ones the CLI refuses to set without `--force`.
Useful when you want an agent to do the work but not to declare it finished.

## Commands

| Command | What it does |
|---|---|
| `init` | Scaffold a board here |
| `new` | Create a ticket, allocating the ID |
| `set` | Change fields on a ticket |
| `comment` | Append a dated comment |
| `list` | List tickets, with filters and `--json` |
| `show` | Print one ticket |
| `next-id` | The next free ID for a prefix |
| `validate` | Report every problem |
| `build` | Write the board HTML |
| `doctor` | Print resolved config and paths |
| `agent-docs` | Print instructions for a coding agent |

Every command takes `--help`. `beacon-board --version` prints the version.

Exit codes: `0` ok, `1` usage or runtime error, `2` validation failed, `3`
refused by rule. Branch on these rather than on the message text.

## Requirements

Python 3.11 or newer. No runtime dependencies.

## Contributing

Bug reports and pull requests are welcome on
[GitHub](https://github.com/bojan-gasparovic/beacon-board/issues). To work on it:

```bash
python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
```

See [CONTRIBUTING.md](https://github.com/bojan-gasparovic/beacon-board/blob/main/CONTRIBUTING.md)
for the house rules.

## Author

Built by Bojan Gasparovic. More work and writing at
[zeroemdashes.com](https://zeroemdashes.com).

## License

MIT.

Generated boards embed Poppins, DM Sans and Fira Code, all licensed under
the SIL Open Font License 1.1. The licence text ships with the package at
`beacon_board/templates/fonts/OFL.txt`.
