Docs

Add Breadcrumb to your repo

Breadcrumb asks your coding agent to leave a small structured trail next to the code, then walks a human through the change in the right order. Here is how to wire it up.

Install

Run it once with pnpm dlx, or add the CLI to the project as a dev dependency.

bash

# run it once without installing
pnpm dlx @adikuma/breadcrumb init

# or add it to the project
pnpm add -D @adikuma/breadcrumb

The loop

Three commands. init scaffolds the handoff and the agent skills, task new stamps a fresh review.yml, and check validates it against your real git changes.

bash

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

The agent fills in the trail. A good one is short and honest.

.breadcrumb/tasks/quote-add-ons/review.yml

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.
review_sequence:
  - src/pricing/tax.ts
files:
  - path: src/pricing/tax.ts
    why: Start here, it defines the pricing rule.
    risk: medium

The CI gate

The same check runs as a pull request gate. It finds the one handoff the PR touches, diffs against the base branch, and fails a changed file that has no why and risk.

.github/workflows/breadcrumb.yml

name: breadcrumb
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: corepack pnpm dlx @adikuma/breadcrumb@latest check --ci

Add it with breadcrumb init --workflow. Label a pull request breadcrumb-skip to wave through a dependency bump.

Packages

Two published packages. The CLI does the work, the protocol package holds the schema so your own tools can read a trail.

@adikuma/breadcrumb0.4.1

The CLI. init, task new, and check, plus the CI gate.

npm source

@adikuma/breadcrumb-protocol0.2.1

The review.yml schema and types, shared by the CLI and the app.

npm source