vibed/nbd/src/claude_md_snippet.md

Task Tracking with nbd

nbd is a CLI tool for managing work tickets, designed for agent workflows.

Initialisation

nbd init

Run once in the project root. Creates .nbd/tickets/. Safe to run multiple times.

Core commands

# Create a new ticket (use --ftype md for a human-readable body)
nbd create --title "Add OAuth login" --type feature --priority 7 --ftype md --json

# List all open tickets (sorted by priority)
nbd list --json

# Read a specific ticket
nbd read <id> --json

# Update a ticket
nbd update <id> --status in_progress --json
nbd update <id> --status done --json

Finding what to work on

# All tickets that are unblocked and ready to start
nbd ready --json

# The single highest-priority unblocked ticket
nbd next --json

Workflow

1. Before starting — create a ticket: nbd create --title "..." --ftype md --json
2. When starting — mark it in progress: nbd update <id> --status in_progress --json
3. When done — mark it complete: nbd update <id> --status done --json

Guidelines

• Always pass --json to every command for structured, unambiguous output.
• Always pass --ftype md when creating tickets — markdown format keeps the body human-readable.
• Use jq to parse and transform JSON output when needed.
• Priority scale 0–10: use 7–9 for bugs, 5 for normal tasks, 3 for nice-to-haves.
• --type choices: project, feature, task, bug.
• Use --deps id1,id2 to express blockers — tickets that must be done first.
• Create tickets before starting non-trivial tasks, not after.