|
|
# nbd
|
|
|
|
|
|
A CLI tool for managing work tickets, primarily targeted at agent workflows.
|
|
|
|
|
|
Tickets are stored as JSON files in `.nbd/tickets/` inside the nearest ancestor
|
|
|
directory that contains a `.nbd/` folder, discovered by traversing upward from
|
|
|
the current working directory — just like `git` finds `.git/`.
|
|
|
|
|
|
## How it works
|
|
|
|
|
|
Each ticket is a JSON file named `{id}.json`, where `id` is a unique
|
|
|
6-character lowercase hex string (e.g. `a3f9c2`). Tickets carry:
|
|
|
|
|
|
| Field | Type | Default |
|
|
|
|---|---|---|
|
|
|
| `id` | 6-char hex string | auto-generated |
|
|
|
| `title` | string | *(required)* |
|
|
|
| `body` | string | `""` |
|
|
|
| `priority` | integer 0–10 | `5` |
|
|
|
| `status` | `todo` \| `in_progress` \| `done` | `todo` |
|
|
|
| `ticket_type` | `project` \| `feature` \| `task` \| `bug` | `task` |
|
|
|
| `dependencies` | list of ticket IDs | `[]` |
|
|
|
|
|
|
All commands accept `--json` for machine-readable output.
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
### Initialise
|
|
|
|
|
|
Create the ticket store in your project root:
|
|
|
|
|
|
```sh
|
|
|
nbd init
|
|
|
```
|
|
|
|
|
|
Analogous to `git init` — safe to run multiple times.
|
|
|
|
|
|
### Create a ticket
|
|
|
|
|
|
```sh
|
|
|
nbd create --title "Fix login bug" --priority 8 --type bug
|
|
|
nbd create --title "Add rate limiting" --body "Protect public endpoints" --deps a3f9c2
|
|
|
```
|
|
|
|
|
|
### Read a ticket
|
|
|
|
|
|
```sh
|
|
|
nbd read a3f9c2
|
|
|
nbd read a3f9c2 --json
|
|
|
```
|
|
|
|
|
|
### List all tickets
|
|
|
|
|
|
By default, `done` tickets are excluded.
|
|
|
|
|
|
```sh
|
|
|
nbd list # todo + in_progress only (done excluded)
|
|
|
nbd list --filter status=* # all tickets including done
|
|
|
nbd list --filter status=done # only completed tickets
|
|
|
nbd list --filter type=bug # non-done bug tickets
|
|
|
nbd list --json
|
|
|
```
|
|
|
|
|
|
### Update a ticket
|
|
|
|
|
|
Only the flags you supply are changed; all other fields retain their current
|
|
|
values.
|
|
|
|
|
|
```sh
|
|
|
nbd update a3f9c2 --status in_progress
|
|
|
nbd update a3f9c2 --priority 9 --type bug
|
|
|
```
|
|
|
|
|
|
### Find actionable tickets
|
|
|
|
|
|
List tickets that are ready to work on — not done and with all dependencies
|
|
|
completed:
|
|
|
|
|
|
```sh
|
|
|
nbd ready
|
|
|
nbd ready --json
|
|
|
```
|
|
|
|
|
|
### Migrate ticket files
|
|
|
|
|
|
Re-serialise all ticket files through the current schema. Use this after
|
|
|
upgrading `nbd` to remove stale fields, add new fields with defaults, and
|
|
|
normalise formatting.
|
|
|
|
|
|
```sh
|
|
|
nbd migrate
|
|
|
nbd migrate --dry-run # preview changes without writing
|
|
|
nbd migrate --json # machine-readable summary
|
|
|
```
|
|
|
|
|
|
## Running
|
|
|
|
|
|
```sh
|
|
|
# From the nbd/ directory
|
|
|
cargo run -- init
|
|
|
cargo run -- create --title "Test ticket" --priority 7 --type bug
|
|
|
cargo run -- list
|
|
|
cargo run -- ready
|
|
|
cargo run -- read <id>
|
|
|
cargo run -- update <id> --status in_progress
|
|
|
cargo run -- list --json
|
|
|
```
|
|
|
|
|
|
## Testing
|
|
|
|
|
|
```sh
|
|
|
cargo test
|
|
|
```
|
|
|
|
|
|
Unit tests live in `src/tests.rs`. Integration tests (full command flows against
|
|
|
a temporary directory) live in `tests/integration.rs`.
|
|
|
|
|
|
## Development
|
|
|
|
|
|
Run these commands in order before committing:
|
|
|
|
|
|
```sh
|
|
|
cargo fmt
|
|
|
cargo check
|
|
|
cargo clippy
|
|
|
cargo test
|
|
|
```
|
|
|
|
|
|
## License
|
|
|
|
|
|
Dual-licensed under [Apache License, Version 2.0](../LICENSE-APACHE) and
|
|
|
[MIT License](../LICENSE-MIT), consistent with the rest of the `vibed` mono-repo.
|
|
|
|
|
|
---
|
|
|
|
|
|
*This software was written with [Claude Code](https://claude.com/claude-code)
|
|
|
using the claude-sonnet-4-6 model.*
|