vibed/nbd/.beans/nbd-2i1e--nbd-claude-md-command.md

title	status	type	priority	created_at	updated_at
nbd claude-md command	completed	feature	normal	2026-03-10T23:30:31Z	2026-03-10T23:30:31Z

Add nbd claude-md subcommand that prints a ready-to-paste CLAUDE.md snippet for adopting nbd in any project. The snippet content is maintained as a source file and baked into the binary at compile time via include_str!.

Motivation

Every project that wants to use nbd needs the same boilerplate in its CLAUDE.md: what nbd is, how to invoke it, the create/update/done workflow, and the key guidelines. Without this command, that block has to be written by hand and tends to drift out of date as nbd evolves. By owning the canonical snippet in the nbd source tree and embedding it into the binary, the snippet stays in sync with the tool automatically — projects just run nbd claude-md >> CLAUDE.md when they adopt or upgrade nbd.

Snippet file

Create src/claude_md_snippet.md. This is a plain markdown file, checked into the repository, that contains the CLAUDE.md section any adopting project should paste in. It should cover:

• One-sentence description of nbd.
• Initialisation (nbd init).
• The four core commands with examples (create, list, read, update).
• The nbd ready command for finding unblocked tickets.
• The workflow (create before starting → set in_progress → set done).
• Guidelines: always --json, priority scale, type choices, dep usage.

The file is written for a project where nbd is installed in PATH (i.e. not via cargo run). It should be self-contained — no references to the nbd crate internals.

Binary embedding

In main.rs, embed the snippet at compile time:

const CLAUDE_MD_SNIPPET: &str = include_str!("claude_md_snippet.md");

include_str! resolves paths relative to the source file (src/), so this looks for src/claude_md_snippet.md. Cargo rebuilds the binary automatically when the file changes.

Command implementation

Add ClaudeMd variant to Commands in main.rs:

/// Print a CLAUDE.md snippet for adopting nbd in a project.
ClaudeMd,

The --json global flag applies:

• Without --json: print!("{CLAUDE_MD_SNIPPET}") — raw markdown, suitable for redirect (nbd claude-md >> CLAUDE.md).
• With --json: output {"snippet": "<escaped content>"} — for programmatic consumption.

No store access needed — this command is pure output from the embedded constant. It does not call find_nbd_root().

No display.rs changes needed

The output is a single print! call in the command handler. No tabular formatting.

Tests

Integration tests (tests/integration.rs):

• nbd claude-md exits zero and stdout is non-empty.
• stdout contains key strings ("nbd", "CLAUDE.md" or similar section header, "--json").
• nbd claude-md --json exits zero and stdout is valid JSON with a "snippet" key whose value is a non-empty string.
• nbd claude-md works even when run from a directory with no .nbd/ (no find_nbd_root call).

Files touched

• src/claude_md_snippet.md — new file; the canonical snippet content
• src/main.rs — include_str! constant, ClaudeMd command variant and handler
• tests/integration.rs — integration tests
• README.md — mention nbd claude-md in the Usage section