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 beans

Use beans to track tasks for work on this project.

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.

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

When starting a task: Update its status.

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

When done: Mark it complete.

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

To see all beans ready to start:

beans list --json --ready

To see all beans:

beans list --json

To view a specific bean:

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.

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.