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

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:

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.

cargo run -- create --title "Add partial ID matching" --type feature --priority 7 --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.
• 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:

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

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