vibed/nbd/CLAUDE.md

@../CLAUDE.md

CLAUDE.md — nbd

All commands in this file are run from the `nbd/` directory.

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

CLI Interface

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.

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

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:

cargo run -- <subcommand> [flags]

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

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.

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

When starting a task: Update its status.

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

When done: Mark it complete.

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

To get the single best ticket to work on next:

cargo run -- next --json

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

cargo run -- ready --json

To see all tickets:

cargo run -- list --json

To read a specific ticket:

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.

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.