breadcrumbs

# breadcrumbs

> Agent-operations machinery you copy into a repo you cannot afford to break:
> memory ledgers, retrieval measurement, CI guards, merge-gate workflows, and
> the pattern essays behind them. Everything is plain text, stdlib-only, and
> meant to be owned and edited after copying; there is deliberately no package.
> Machine-readable inventory with per-artifact assumptions and selftest
> commands, plus the cross-repository ownership and public-data boundary:
> kit.json → portfolio_contract.

Route by the problem you arrived with. Every artifact states its own
assumptions in its header, and every runnable tool ships an offline selftest.
Before sending work from another repository, resolve ownership through
`kit.json` → `portfolio_contract`; portable public intake and detailed appraisal
are separate evidence classes.

## Start here

- [README.md](README.md): the problem, the one-afternoon adoption path, the map.
- [templates/CLAUDE_TEMPLATE.md](templates/CLAUDE_TEMPLATE.md): the rules-file
  skeleton everything else hangs off. Copy this, not this repo's own CLAUDE.md.
- [kit.json](kit.json): the full inventory, problem-to-artifact routing, and
  selftest commands, for programmatic adoption.
- [docs/workflow-registry.json](docs/workflow-registry.json): versioned, evidence-bounded public workflow discovery records.
- [docs/jarvis-workflow-routing.json](docs/jarvis-workflow-routing.json): model-neutral public routing patterns for Jarvis consumers.

## Memory that survives the session

- [docs/cue-placement-ladder.md](docs/cue-placement-ladder.md): the rule is
  written down and still gets missed. Which of five rungs it belongs on, and
  what has to happen before it earns a promotion.
- [docs/skill-invocation-gap.md](docs/skill-invocation-gap.md): your skill
  library is healthy and unused. Making skills reachable, then measuring
  whether anyone reached.
- [docs/prospective-memory-watches.md](docs/prospective-memory-watches.md): the
  fact you needed was recorded and nobody looked. Standing watches that fire on
  a condition instead of waiting to be remembered. Pattern only, no code ships.
- [docs/governing-agents-that-act.md](docs/governing-agents-that-act.md): read this
  if your agent takes actions and someone will eventually audit them. What to
  log, what it may never decide alone, and a self-assessment.
- [docs/versioning-is-not-governance.md](docs/versioning-is-not-governance.md):
  read this first if you already store agent memory in git. What versioning
  answers, what it cannot, and which of the two problems you actually have.

- [templates/CONCLUSIONS_TEMPLATE.md](templates/CONCLUSIONS_TEMPLATE.md):
  the append-only, path-keyed conclusions ledger format with supersession.
- [templates/DECISIONS_TEMPLATE.md](templates/DECISIONS_TEMPLATE.md): the
  decisions ledger; [docs/decision-capture.md](docs/decision-capture.md) is why.
- [templates/SESSION_STATE_TEMPLATE.md](templates/SESSION_STATE_TEMPLATE.md):
  the living handoff between sessions.
- [templates/ledger-tools/memory_engine.py](templates/ledger-tools/memory_engine.py):
  runnable three-tier memory; asserted vs verified, with a distinct tool or
  human authority required for promotion.
- [templates/ledger-tools/capture_nudge.py](templates/ledger-tools/capture_nudge.py):
  the hook that makes capture happen the turn a ruling lands.

## Measuring whether memory works (most systems skip this)

- [docs/memory-measurement.md](docs/memory-measurement.md): the four
  instruments and why a memory entry nobody can reach is indistinguishable
  from one never written.
- [templates/ledger-tools/retrieval_exam.py](templates/ledger-tools/retrieval_exam.py):
  reachability, injection probe, use stamps, the forbidden-hit check, and a
  survey mode that runs against any repo with no adoption.
- [templates/ledger-tools/conclusions_audit.py](templates/ledger-tools/conclusions_audit.py):
  staleness verdicts against the live tree.
- [templates/ledger-tools/SEARCH_MISSES.md](templates/ledger-tools/SEARCH_MISSES.md):
  the ledger for the entry that was never written.
- [benchmarks/orientation/README.md](benchmarks/orientation/README.md): a public,
  synthetic matched evaluation of raw history versus Breadcrumbs cues across
  model tiers, with accuracy, tokens, and latency kept separate.

## Enforcement (rules as CI, not prose)

- [ci-kit/guards/](ci-kit/guards/): lint guards, each with fixtures proving it
  bites; [ci-kit/run_guards.sh](ci-kit/run_guards.sh) runs the set.
- [ci-kit/workflows/](ci-kit/workflows/): the fail-closed merge gate, automerge
  with an approval label, and the gotchas that cost real debugging time.
- [ci-kit/migrations/](ci-kit/migrations/): forward-only migration runner with
  an applied-state ledger.
- [ci-kit/preflight/preflight.py](ci-kit/preflight/preflight.py): catch the
  branch collision before you push; SKIPPED is never PASSED.

## Rules to paste into your own rules file

- [skills/](skills/): session efficiency, data truth, flag lifecycle,
  regression layering, reuse-first, delivery protocol, and more; each opens
  with the failure it prevents.
- [checklists/](checklists/): continuity sweep, PR discipline, pre-push.

## Running many sessions (fleet patterns)

- [docs/floating-memory.md](docs/floating-memory.md): the fleet memory
  architecture as a pattern essay; its header states what ships here and what
  does not.
- [playbook/](playbook/): the operating model, coordinator seats, scheduled
  agents, the unattended-agent contract.
- [templates/standing-agents/](templates/standing-agents/): the standing-agent
  fleet kit.

## Researching collaborative intelligence

- [docs/collaborative-intelligence-method-v2.md](docs/collaborative-intelligence-method-v2.md):
  claim-centered research method, confidence profiles, and promotion rules.
- [docs/collaborative-intelligence-repository-landscape.md](docs/collaborative-intelligence-repository-landscape.md):
  pinned first cohort of public runtimes, workflows, protocols, memory systems,
  and research frameworks.
- [docs/collaborative-intelligence-repository-landscape-method.md](docs/collaborative-intelligence-repository-landscape-method.md):
  reproduce or extend the repository appraisal without ranking products.
- [docs/collaborative-intelligence-repository-landscape.json](docs/collaborative-intelligence-repository-landscape.json):
  machine-readable 311-repository ledger with pinned mechanism appraisals,
  portable public assessment evidence, exclusion counts, and import counts.
- [scripts/repository_landscape.py](scripts/repository_landscape.py):
  deterministic public-only transfer importer and ledger validator.
- [scripts/repository_review_promotions.py](scripts/repository_review_promotions.py): deterministic promotion of portable identities into pinned detailed reviews.
- [scripts/repository_triage.py](scripts/repository_triage.py): closes the portable-only queue with explicit public relevance dispositions.
- [scripts/workflow_reproduction.py](scripts/workflow_reproduction.py): runs bounded synthetic reproductions without claiming external effectiveness.

## Optional

- [docs/](docs/): the full pattern-essay shelf, one reasoning essay per
  artifact class.
- [templates/commands/](templates/commands/): slash-command workflows (scout,
  retro, checkpoint, promote, model-check) for harnesses that support them.
- [templates/hooks/](templates/hooks/): harness hooks (pre-compact save,
  PII screen, batch cadence).
- [ci-kit/workflows/greenlight_tiers.py](ci-kit/workflows/greenlight_tiers.py):
  diff-tiered merge gate; docs-class merges on green, the rest waits for the label.
- [templates/ledger-tools/budget_loans.py](templates/ledger-tools/budget_loans.py):
  context-budget raises as loans; due loans go red, unrecorded raises fail the gate.