@../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 beans

Use `beans` to track tasks for work on this project.

```sh
beans init    # run once; creates .beans/
```

### Workflow

Always pass `--json` to every command. Use `jq` to parse output when needed.

**Before starting work:** Create a bean.

```sh
beans create --json "Add partial ID matching" --type feature --priority high --status todo
```

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

```sh
beans update --json <id> --status in-progress
```

**When done:** Mark it complete.

```sh
beans update --json <id> --status completed
```

**To see all beans ready to start:**

```sh
beans list --json --ready
```

**To see all beans:**

```sh
beans list --json
```

**To view a specific bean:**

```sh
beans show --json <id>
```

### Guidelines

- **Always use `--json`.** It gives structured, unambiguous output on every command.
- Create beans *before* starting non-trivial tasks, not after.
- Use `--blocked-by <id>` to express blockers — beans that must be done first.
- `--priority` choices: `critical`, `high`, `normal`, `low`, `deferred`.
- `--type` choices: `milestone`, `epic`, `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>