diff --git a/.gitignore b/.gitignore index c1c8c2a..6dff15f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target +pi-extension/node_modules .bmo .docket docs/tdd diff --git a/README.md b/README.md index 773d530..2fbb23d 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ For an example of agents and skills that have been instructed to use `bmo` check ## Attribution -`bmo` was inspired by and adapted from [docket](https://github.com/ALT-F4-LLC/docket), an issue tracker for AI agents written by **ALT-F4-LLC**. The design, data model, and command structure of BMO all owe a direct debt to that project, and all credit for the underlying ideas belongs there. +`bmo` was inspired by and adapted from [docket](https://github.com/ALT-F4-LLC/docket), an issue tracker for AI agents written by **ALT-F4-LLC**. -In addition, the code in this repository was written by [Claude Code](https://claude.ai/claude-code), Anthropic's AI coding assistant. The repo owner directed this work. +In addition, the code in this repository was written by [Claude Code](https://claude.ai/claude-code). The repo owner directed this work. ## Installation @@ -44,10 +44,31 @@ bmo board bmo web ``` +## pi-code Integration + +If you use [pi-code](https://pi.dev), the `pi-bmo` extension integrates bmo natively +into pi. This extension adds typed `bmo_*` tools that the LLM calls directly, in addition to a live board status widget, board +state injected into every agent turn's context, and `/board` `/next` `/plan` slash commands. + +```bash +pi install git:github.com/erewok/pi-bmo +``` + +A companion pi-code extension, [bmo-dev-team](https://github.com/erewok/bmo-agent-setup), adds a +full software development team of agents (staff-engineer, project-manager, senior-engineer, +qa-engineer, ux-designer) that plans and executes work through `bmo`. + +```bash +pi install git:github.com/erewok/bmo-agent-setup +``` + +See [docs/pi-extension.md](docs/pi-extension.md) for the full integration guide. + ## Documentation - [docs/commands.md](docs/commands.md) — Complete command reference - [docs/agents.md](docs/agents.md) — Integration guide for AI agents +- [docs/pi-extension.md](docs/pi-extension.md) — pi-code extension and dev-team suite - [docs/web.md](docs/web.md) — Web interface - [docs/data.md](docs/data.md) — Data storage and database location - [docs/migration-from-docket.md](docs/migration-from-docket.md) — Migrating from docket diff --git a/docs/index.md b/docs/index.md index e4fa5b2..fbf6f07 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,7 @@ |------|-------------| | [commands.md](commands.md) | Complete command reference — all commands, flags, and JSON output shapes | | [agents.md](agents.md) | Integration guide for AI agents — session setup, finding work, tracking progress | +| [pi-extension.md](pi-extension.md) | pi-code extension — native bmo tools, context injection, and the dev-team agent suite | | [web.md](web.md) | Web interface — starting the server, flags, live updates | | [data.md](data.md) | Data storage — SQLite location, directory walk behavior, `BMO_DB` env var | | [migration-from-docket.md](migration-from-docket.md) | Migrating from docket to bmo | diff --git a/docs/pi-extension.md b/docs/pi-extension.md new file mode 100644 index 0000000..32a27ca --- /dev/null +++ b/docs/pi-extension.md @@ -0,0 +1,128 @@ +# bmo + pi-code Integration + +[pi-code](https://pi.dev) is an AI coding agent that runs in the terminal. The `pi-bmo` +extension integrates bmo natively into pi, replacing raw shell commands with typed tools +the LLM can call directly and adding board-state awareness to every session. + +## What the Extension Provides + +| Feature | Description | +|---------|-------------| +| **`bmo_*` tools** | Typed wrappers for every bmo command — the LLM calls structured tools instead of constructing shell strings | +| **Context injection** | On every agent turn, the current board summary and next work-ready issues are silently injected into context — no extra tool call needed | +| **Status widget** | Compact board counts (`○3 ●2 ◐1 ◎0 ✔5`) displayed above the pi editor, updated after every turn | +| **Slash commands** | `/bmo-board`, `/bmo-ls`, `/bmo-show`, `/bmo-next`, `/bmo-plan`, `/bmo-stats`, `/bmo-init`, `/bmo-widget` | + +### Available Tools + +| Tool | Equivalent bmo command | +|------|------------------------| +| `bmo_init` | `bmo init` | +| `bmo_agent_init` | `bmo agent-init` | +| `bmo_board` | `bmo board --json` | +| `bmo_plan` | `bmo plan --json [--phase N]` | +| `bmo_next` | `bmo next --json` | +| `bmo_show` | `bmo show --json` | +| `bmo_list` | `bmo list --json [--status] [--assignee]` | +| `bmo_create` | `bmo create -t ...` | +| `bmo_edit` | `bmo edit ...` | +| `bmo_move` | `bmo move -s ...` | +| `bmo_claim` | `bmo claim --assignee ...` | +| `bmo_close` | `bmo close ` | +| `bmo_reopen` | `bmo reopen ` | +| `bmo_comment` | `bmo comment add/list` | +| `bmo_link` | `bmo link add ` | +| `bmo_file` | `bmo file add ` | +| `bmo_stats` | `bmo stats` | + +The extension discovers the bmo project the same way the CLI does — by walking up from the +current working directory looking for `.bmo/issues.db`. No configuration needed. + +## Installation + +> **Prerequisite:** The `bmo` binary must already be installed and on your PATH before +> the extension will work. See [Requirements](#requirements) below. + +Install the extension into pi's global configuration: + +```bash +pi install git:github.com/erewok/pi-bmo +``` + +To try it without making it permanent: + +```bash +pi -e git:github.com/erewok/pi-bmo +``` + +See the [pi-bmo repo](https://github.com/erewok/pi-bmo) for full installation, +update, and local development instructions. + + +## Dev-Team Extension + +A companion extension, [pi-bmo-agents](https://github.com/erewok/bmo-agent-setup), +builds on `pi-bmo` to provide a full AI software development team that plans and +executes work through bmo. Install both: + +```bash +pi install git:github.com/erewok/pi-bmo +pi install git:github.com/erewok/bmo-agent-setup +``` + +### How the dev-team uses bmo + +The dev-team workflow is built around bmo's dependency graph and parallel execution +model. A typical Medium-complexity feature looks like this: + +1. **Staff engineer** explores the codebase and writes a TDD in `docs/tdd/` +2. **Project manager** decomposes the TDD into bmo issues with phases, dependencies, + and file attachments — calling `bmo_create`, `bmo_link`, and `bmo_file` for each +3. **Senior engineers** run in parallel within each phase, each claiming their issue + with `bmo_claim` and moving it to `review` with `bmo_move` on completion +4. **Staff engineer** reviews all changes and posts structured feedback as `bmo_comment` + calls — blockers prevent the issue from closing +5. **QA engineer** verifies acceptance criteria and posts results via `bmo_comment` +6. **Orchestrator** closes each issue with `bmo_close` once review passes + +Because bmo file attachments scope each issue to specific files, the orchestrator can +detect collisions before spawning parallel agents and serialize any conflicting work. + +## Requirements + +- **[bmo](https://github.com/erewok/bmo) binary** installed and available on your shell's `$PATH` +- **[pi-code](https://pi.dev)** installed + +The extension has no additional TypeScript/npm runtime dependencies. + +### Installing the bmo binary + +`pi install` only installs the TypeScript extension — it does **not** install the `bmo` +binary for you. The extension calls `bmo` directly using Node's `execFile`, so the binary +must be on the PATH that pi inherits when it starts. + +```bash +# From source (inside the bmo repo) +cargo install --path . --locked + +# Or from crates.io once published +cargo install bmo +``` + +Verify with `which bmo`. If that prints nothing, the binary is not on PATH. + +### PATH and shell environments + +On macOS, `~/.cargo/bin` is added to `$PATH` by Cargo's installer and is available in +terminal shells. However, if you launch pi from a GUI launcher (Spotlight, Alfred, a +menu-bar app, etc.), the process may inherit a minimal `PATH` that does not include +`~/.cargo/bin`. The safest fix is to start pi from a terminal session where `which bmo` +works. If you must launch pi another way, add `~/.cargo/bin` to `/etc/paths` or to your +shell's login profile (`~/.zprofile` for zsh, `~/.bash_profile` for bash). + +### What happens if bmo is missing + +The extension will show a warning notification at session start if `bmo` cannot be found. +Every `bmo_*` tool call will also return a descriptive error rather than failing silently, +but the LLM will not be able to perform any issue-tracking operations until the binary is +installed and accessible.