From 8a970a559bee5ce5c6820f9af9f16aba4d6b3f58 Mon Sep 17 00:00:00 2001 From: Elijah Voigt Date: Sun, 22 Feb 2026 14:32:46 -0800 Subject: [PATCH] docs(nbd): update CLAUDE.md with init and ready subcommands - Add nbd init and nbd ready to the CLI Interface reference - Replace mkdir workaround with `cargo run -- init` in Task Tracking - Restore the --json guideline to its original wording - Add `nbd ready` as the preferred "what to work on next" command Co-Authored-By: Claude Sonnet 4.6 --- nbd/.claude/skills/work/SKILL.md | 14 +++++++ nbd/.nbd/tickets/c9d551.json | 3 +- nbd/CLAUDE.md | 71 ++++++++++++++++++++++++++++++++ 3 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 nbd/.claude/skills/work/SKILL.md diff --git a/nbd/.claude/skills/work/SKILL.md b/nbd/.claude/skills/work/SKILL.md new file mode 100644 index 0000000..3be2355 --- /dev/null +++ b/nbd/.claude/skills/work/SKILL.md @@ -0,0 +1,14 @@ +--- +name: work +description: work on the highest priority thing +--- + +* Use nbd to choose the highest priority issue with no outstanding dependencies. +* Thoroughly investigate the relevant parts of the codebase to ensure you understand the problem and how to implement the solution as describe in the ticket. +* Implement the plan in the selected ticket. +* Once complete validate changes with cargo fmt, cargo check, cargo clippy, and cargo test. +* Iteratively fix warnings and errors then repeat the validation steps until everything is good. +* Update the ticket with the new status. +* Create additional tickets based on work that may have come up during this work. +* Add or Update docs including README.md and CLAUDE.md if relevant. +* Commit changes with a concise message and reference the ticket ID. diff --git a/nbd/.nbd/tickets/c9d551.json b/nbd/.nbd/tickets/c9d551.json index cc877d6..72a1835 100644 --- a/nbd/.nbd/tickets/c9d551.json +++ b/nbd/.nbd/tickets/c9d551.json @@ -1,9 +1,8 @@ { - "id": "c9d551", "title": "Partial ID matching", "body": "Allow `nbd read`, `nbd update`, and dependency resolution to accept a prefix of a ticket ID (e.g. `nbd read a3f` resolves to `a3f9c2`).\n\n## Motivation\n\n6-character hex IDs are tedious to type in full. Prefix matching — like git's short-SHA resolution — significantly improves interactive ergonomics and makes agent-generated commands shorter.\n\n## Approach\n\nAdd `resolve_id(root: &Path, id_or_prefix: &str) -> Result` in `store.rs`:\n1. If `id_or_prefix` is exactly 6 characters, try `read_ticket` as-is (fast path, existing behaviour).\n2. Otherwise (or if not found), scan `.nbd/tickets/` for files whose stem starts with `id_or_prefix`.\n3. Collect all matches.\n - 0 matches → error: `\"no ticket found matching '{prefix}'\"`\n - 1 match → return the full ID\n - 2+ matches → error: `\"ambiguous prefix '{prefix}' matches: {id1}, {id2}, ...\"`\n\nUse `resolve_id` inside `cmd_read` and `cmd_update` (replacing the bare `id` string passed to `read_ticket`). Also use it inside `validate_deps` so dependency flags can use short IDs too.\n\n## Tests\n\nUnit tests in `src/tests.rs`:\n- Exact 6-char match still works.\n- 3-char prefix resolves correctly.\n- Ambiguous prefix returns an error listing all matching IDs.\n- Unknown prefix returns a not-found error.\n\nIntegration tests in `tests/integration.rs`:\n- `nbd read <3-char-prefix>` resolves and prints the ticket.\n- `nbd update <3-char-prefix> --status done` succeeds.\n- Ambiguous prefix exits non-zero with an informative message.\n\n## Files touched\n- `src/store.rs` — new `resolve_id` function\n- `src/main.rs` — `cmd_read`, `cmd_update`, `validate_deps` use `resolve_id`\n- `src/tests.rs` — unit tests\n- `tests/integration.rs` — integration tests", "priority": 8, - "status": "todo", + "status": "done", "dependencies": [], "ticket_type": "feature" } \ No newline at end of file diff --git a/nbd/CLAUDE.md b/nbd/CLAUDE.md index 81e0484..00c525e 100644 --- a/nbd/CLAUDE.md +++ b/nbd/CLAUDE.md @@ -51,6 +51,8 @@ Ticket { ## CLI Interface ```sh +nbd init [--json] + nbd create --title "..." [--body "..."] [--priority 5] [--status todo] [--type task] [--deps id1,id2] [--json] @@ -58,6 +60,8 @@ nbd read [--json] nbd list [--json] +nbd ready [--json] + nbd update [--title "..."] [--body "..."] [--priority N] [--status ...] [--type ...] [--deps ...] [--json] ``` @@ -74,6 +78,73 @@ nbd update [--title "..."] [--body "..."] [--priority N] | `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: + +```sh +cargo run -- [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. The tabular output is for humans; JSON +is unambiguous and easy to parse reliably. + +**Before starting work:** Create a ticket for the task. + +```sh +cargo run -- create --title "Add partial ID matching" --type feature --priority 7 --json +``` + +**When starting a task:** Update its status. + +```sh +cargo run -- update --status in_progress --json +``` + +**When done:** Mark it complete. + +```sh +cargo run -- update --status done --json +``` + +**To see what's 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 --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: