@../CLAUDE.md

# CLAUDE.md — nbd

<working-directory>
All commands in this file are run from the `nbd/` directory.
</working-directory>

<project-overview>

`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-overview>

<project-structure>

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

</project-structure>

<tech-stack>

## Tech Stack

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

</tech-stack>

<data-model>

## 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 | Closed | Archived | Backlog, default Todo
    dependencies: Vec<String>   // Vec of ticket IDs, default []
    ticket_type: TicketType     // Project | Feature | Task | Bug, default Task
}
```

</data-model>

<cli-interface>

## CLI Interface

```sh
nbd init [--json]

nbd create --title "..." [--body "..."] [--priority 5] [--status todo|in_progress|done|closed|archived|backlog]
           [--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]

nbd graph [<id>] [--filter KEY=VALUE ...] [--json]
```

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

</cli-interface>

<module-responsibilities>

## 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, JSON output, ASCII graph rendering |
| `graph.rs` | dependency graph computation (`TicketGraph`, edges, subtrees) |
| `filter.rs` | glob-pattern ticket filtering |
| `tests.rs` | unit tests for all modules |

</module-responsibilities>

<task-tracking>

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

</task-tracking>

<testing>

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

</testing>