# 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 create --title "..." [--body "..."] [--priority 5] [--status todo]
           [--type task] [--deps id1,id2] [--json]

nbd read <id> [--json]

nbd list [--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 |

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