@adikuma/breadcrumb

CLI for creating and checking Breadcrumb review handoffs.

Breadcrumb helps reviewers understand agent-written pull requests by asking the coding agent to leave a small structured trail next to the code. The trail lives in the repo at .breadcrumb/tasks/<task-id>/review.yml.

Install

Run it without installing:

pnpm dlx @adikuma/breadcrumb init

Or add it to a project:

pnpm add -D @adikuma/breadcrumb

Commands

breadcrumb init
breadcrumb init --agent claude,codex
breadcrumb task new <id>
breadcrumb check --task <id>
breadcrumb check --task <id> --json
breadcrumb check --task <id> --strict

Typical Flow

breadcrumb init
breadcrumb task new quote-add-ons
breadcrumb check --task quote-add-ons

breadcrumb init sets up the handoff and asks which agents should get the handoff skill. A developer sees an interactive picker; an agent or CI passes --agent (defaulting to claude,codex). It creates:

.breadcrumb/
  config.yml
  tasks/
  templates/review.yml
AGENTS.md                                  # the handoff contract
CLAUDE.md                                  # imports AGENTS.md
.claude/skills/breadcrumb-handoff/SKILL.md # claude
.codex/skills/breadcrumb-handoff/SKILL.md  # codex
.agents/skills/breadcrumb-handoff/SKILL.md # codex cross agent dir

AGENTS.md holds the contract; CLAUDE.md just imports it with @AGENTS.md. The skill carries the craft of writing a good handoff and loads only when an agent is writing one. Existing instruction files are updated in place inside a managed block, never replaced. Pass --agent none to skip the skill.

What Check Does

breadcrumb check validates the handoff and compares it with the real git changed files.

It checks that:

• review.yml has the expected schema
• changed files are covered by the review path
• risk values are valid
• paths are relative and safe
• generated folders like node_modules, dist, .next, and coverage are ignored

Example Handoff

version: 1
id: quote-add-ons
title: Add optional add-ons to the quote flow
user_goal: Let sales reps add optional services to a quote.
summary: Adds add-on selection and includes add-ons in quote totals.
review_sequence:
  - src/pricing/tax.ts
files:
  - path: src/pricing/tax.ts
    why: Start here because this file defines the pricing rule.
    risk: medium

Why This Exists

Normal pull request tools show what changed. Breadcrumb adds how to read it: the intent, risk, and recommended review order.

Releasing

Before bumping the version and publishing, run the packaging smoke test. It packs the tarball, installs it into a clean directory, and runs the installed binary, so a missing file fails here instead of after publish:

pnpm --filter @adikuma/breadcrumb check   # types + unit tests
pnpm --filter @adikuma/breadcrumb smoke   # packaged artifact runs end to end