vibed/nbd/CLAUDE.md

# CLAUDE.md — nbd

`nbd` is a CLI tool for managing work tickets, primarily targeted at agent workflows. It is an independent Rust crate within the `vibed` mono-repo.

## Project Structure

```
nbd/
├── CLAUDE.md
├── PLAN.md               # implementation plan and post-MVP roadmap
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── main.rs           # CLI entry point; clap subcommand dispatch
│   ├── ticket.rs         # Ticket struct, Status and TicketType enums
│   ├── store.rs          # file I/O, directory traversal, CRUD
│   ├── display.rs        # tabular and JSON output formatting
│   └── tests.rs          # unit tests
├── tests/
│   └── integration.rs    # integration tests using tempdir
├── docs/
│   ├── PLANNING.md       # development phases and work logs
│   └── ARCHITECTURE.md   # component overview and interactions
└── README.md
```

## Tech Stack

- **Language:** Rust (edition 2021)
- **Async runtime:** `async-std`
- **CLI parsing:** `clap` (derive feature)
- **Serialization:** `serde` + `serde_json`
- **Test utilities:** `tempfile` (dev-dependency)

## Data Model

Tickets are stored as `.json` files in `.nbd/tickets/{id}.json`, where `id` is a 6-character hex string (e.g. `a3f9c2`). The `.nbd/` root is found by traversing up from cwd, like `git` finds `.git/`.

```
Ticket {
    id: String                  // 6-char hex
    title: String
    body: String
    priority: u8                // 0..=10, default 5
    status: Status              // Todo | InProgress | Done, default Todo
    dependencies: Vec<String>   // Vec of ticket IDs, default []
    ticket_type: TicketType     // Project | Feature | Task | Bug, default Task
}
```

## CLI Interface

```sh
nbd init [--json]

nbd create --title "..." [--body "..."] [--priority 5] [--status todo]
           [--type task] [--deps id1,id2] [--json]

nbd read <id> [--json]

nbd list [--json]

nbd ready [--json]

nbd update <id> [--title "..."] [--body "..."] [--priority N]
               [--status ...] [--type ...] [--deps ...] [--json]
```

`--json` is available on all commands for machine-readable output.

## Module Responsibilities

| Module | Responsibility |
|---|---|
| `main.rs` | `clap` CLI definition and subcommand dispatch only |
| `ticket.rs` | `Ticket` struct, enums, ID generation, validation |
| `store.rs` | directory traversal, file read/write, CRUD operations |
| `display.rs` | tabular formatting and JSON output |
| `tests.rs` | unit tests for all modules |

## Task Tracking with nbd

Use `nbd` to track tasks for work on this project. Since the binary is not
installed, always invoke via `cargo run` from the `nbd/` directory:

```sh
cargo run -- <subcommand> [flags]
```

The `.nbd/` directory at the project root is the ticket store. If it does not
exist yet, initialise it first:

```sh
cargo run -- init
```

### Workflow

Always pass `--json` to every command.
Use `jq` to parse and transform the JSON output if necessary.

**Before starting work:** Create a ticket for the task. Use `--ftype md` so the body is stored as human-readable markdown.

```sh
cargo run -- create --title "Add partial ID matching" --type feature --priority 7 --ftype md --json
```

**When starting a task:** Update its status.

```sh
cargo run -- update <id> --status in_progress --json
```

**When done:** Mark it complete.

```sh
cargo run -- update <id> --status done --json
```

**To get the single best ticket to work on next:**

```sh
cargo run -- next --json
```

**To see all tickets that are unblocked and ready to start:**

```sh
cargo run -- ready --json
```

**To see all tickets:**

```sh
cargo run -- list --json
```

**To read a specific ticket:**

```sh
cargo run -- read <id> --json
```

### Guidelines

- **Always use `--json`.** It gives structured, unambiguous output on every command.
- **Always use `--ftype md`** when creating tickets. Markdown format keeps the body human-readable in the file browser.
- Create tickets *before* starting non-trivial tasks, not after.
- Use `--deps id1,id2` to express blockers — tickets that must be done first.
- `--priority` follows 0–10: use 7–9 for bugs, 5 for normal tasks, 3 for nice-to-haves.
- `--type` choices: `project`, `feature`, `task`, `bug`.

---

## Validation

Run in order from this directory before committing:

```sh
cargo fmt
cargo check
cargo clippy
cargo test
```

## Testing

- **Unit tests:** `src/tests.rs` — test each module in isolation; use `tempfile` for any file I/O
- **Integration tests:** `tests/integration.rs` — test full command flows (create → read → list → update) against a real temp directory; test directory traversal by running from a subdirectory

Target 80%+ code coverage.

## Git Conventions

Follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary). Use `nbd` as the scope:

```
feat(nbd): add list command
fix(nbd): handle missing .nbd directory gracefully
test(nbd): add roundtrip serialization test
```

## Code Style

- All public functions, structs, enums, and modules must have rustdoc comments.
- Include doc-examples where applicable — these double as doctests.
- Default `rustfmt` conventions; no custom `rustfmt.toml`.

## Release Builds

```toml
[profile.release]
opt-level = "z"
lto = true
strip = true
codegen-units = 1
```

## License

Dual-licensed under Apache-2.0 and MIT, consistent with the rest of the `vibed` mono-repo.