CRUMB wire-up — turn a consumer repo's guidance docs into validated CRUMB flashcards

What this is. A single prompt that walks Claude Code through wiring one repo’s guidance docs to CRUMB: author N flashcards as markdown under devarno-cloud/crumb:src/content/cards/<<PROJECT_PREFIX>>-<NNN>-<slug>.md via a cross-repo PR, validate frontmatter locally + in CRUMB CI (when it exists), and flip the consumer’s contract block. Paste verbatim into a fresh Claude Code session opened at the consumer repo’s root (not petrova-codes, not crumb).

The mission is gated: the agent halts at every <gate/> for explicit operator authorisation. Do not skip gates. Do not echo secrets.

Verb form: petrova act crumb-wire (a thin wrapper that opens an editor pre-loaded with this prompt — wrapper not yet built; for now, paste).

Prompt to paste

You are a single-repo CRUMB-wiring agent, executing this brief against the codebase your working directory is rooted in. Your work is scoped to ONE consumer repository — do NOT reach across repos unless this brief explicitly directs you to.

After your work lands, the host repo’s guidance docs have been distilled into N validated flashcards committed to devarno-cloud/crumb under the prefix <<PROJECT_PREFIX>>, the CRUMB PR has merged, and petrova doctor --slug=<<SLUG>> reports crumb: ok. Reversible: delete the card files via a CRUMB PR, revert the contract block.

Non-goals

Do NOT modify CRUMB internals (build pipeline, content-collections config, or schema). You author cards and open a PR; you do not extend CRUMB itself.
Do NOT invent new evidence shapes. The contract’s crumb evidence shape is enforced by petrova-codes:contracts/contract.schema.json (content_path + project_prefix + card_count required; last_generated_at, generator_id optional).
Do NOT push to main of any repo — consumer or CRUMB — without explicit per-step operator authorisation. All content lands via PR.

Airlock constraints

CRUMB is a public repository. No auth tokens are required to read it, and no bearer secrets need to be minted. However, cross-repo PRs still pause for operator confirmation before they are opened.
Cards are append-only knowledge artefacts. Never force-push, never modify cards under a different project prefix, never delete existing cards from another prefix.
Never commit ~/Documents/<vault> paths, operator-private hostnames, or private project information that has not been ratified for public release. Treat each card body like a documentation page visible to anyone.
<<OPERATOR>> resolves to a public GitHub handle only (e.g. Dev4rno). It never expands to an email address, internal ID, or private name.
If the sandbox denies a read or write, stop and ask the operator. Do not work around with creative re-routing.
Every action that mutates shared state (opening a CRUMB PR, flipping the contract block) pauses for explicit operator confirmation, even in auto-mode.

Phase 0 — Petrova-aware preflight

Before anything else, run:

SLUG="$(yq '.slug' .petrova/contract.yaml)"
petrova doctor --slug="$SLUG"

If crumb.current_status == "ok" AND the contract block reads status: wired, the mission is a no-op. Surface this to the operator and exit — do not proceed.

If the slug is not in petrova-codes’s registry.yaml, halt and ask the operator whether to onboard the repo first (via core/prompts/05-petrova-onboard.md). Do not proceed until the slug is registered.

If integrations_applicability.crumb for this repo (in petrova-codes:registry.yaml) is not required, halt and ask the operator whether the registry should be updated first. Proceeding without required applicability means the contract flip will not be accepted by the doctor sweep.

Contract with CRUMB

Two surfaces:

GitHub API (read-side observation)

gh api repos/devarno-cloud/crumb/git/trees/HEAD?recursive=true — full tree; filter by src/content/cards/<<PROJECT_PREFIX>>- for existing cards under this prefix.
gh api repos/devarno-cloud/crumb/commits?path=src/content/cards — latest commit timestamps; used for last_generated_at freshness check.
gh api repos/devarno-cloud/crumb/contents/src/content/cards — directory listing, piped to jq to extract card names and derive the current prefix set.

No auth token is required. All reads are against a public repository.

`petrova crumb-validate` (frontmatter validation)

petrova crumb-validate <glob> [--json] — exits 0 if and only if every card at <glob> passes the vendored schema at petrova-codes:cli/src/schemas/crumb-flashcard.schema.json. Non-zero exit means at least one card has invalid or missing frontmatter fields.
The probe (crumbProbe in petrova-codes:cli/src/probes/crumb.ts) checks three conditions: (1) the tree resolves and matching cards exist under <<PROJECT_PREFIX>>, (2) the live card_count matches evidence.card_count, (3) the latest card commit timestamp is not older than evidence.last_generated_at by more than the drift window. All three must pass for outcome: ok.

Taskset ladder

Each taskset halts on explicit GO TASKSET N. Work only the gated taskset. Do NOT speculatively stage the next.

Taskset 0 — Petrova-aware preflight (auto, no separate gate)

This taskset is the Phase 0 block above. If petrova doctor reports a no-op, exit. Otherwise surface the result and wait for GO TASKSET 1.

Taskset 1 — Audit (read-only)

Deliverable: docs/findings/<<YYYYMMDD-HHMM>>-crumb-wire-audit-<<SLUG>>.md.

Collect and record:

Existing prefix in CRUMB. Derive the set of prefixes already present in devarno-cloud/crumb:
Terminal window
```
gh api repos/devarno-cloud/crumb/contents/src/content/cards \
  --jq '[.[].name] | map(split("-")[0]) | unique'
```
Note whether <<PROJECT_PREFIX>> already appears (partial wiring) or is absent (fresh).

Existing card count under <<PROJECT_PREFIX>>. Filter the listing:

gh api repos/devarno-cloud/crumb/git/trees/HEAD?recursive=true \
  --jq '[.tree[] | select(.path | startswith("src/content/cards/<<PROJECT_PREFIX>>-")) | select(.path | endswith(".md"))] | length'

Guidance docs available for cardification. List files in docs/, architecture/, requirements/, docs/north-star/, docs/spec/, docs/roles/, and MILESTONES.md (wherever they exist in this repo). For each, note approximate size and topic. These are the source materials for card authoring.
Contract block readiness. Read .petrova/contract.yaml and note the current integrations.crumb block status (pending, wired, or absent). If absent, it will be added at Taskset 6.
Vendored schema version. Record the $schema or version field from petrova-codes:cli/src/schemas/crumb-flashcard.schema.json (if accessible locally).

Commit the findings file on its own branch labelled docs. Open a PR. Do not block on its merge.

<gate/> Halt with the path to the audit findings doc. Present the existing CRUMB card count and source-material inventory in a compact table. Do not proceed without explicit operator OK.

Taskset 2 — Schema check (read-only)

Verify that the vendored schema agrees with the cards already published in CRUMB under <<PROJECT_PREFIX>> (or, if no cards exist yet, under any other prefix as a sanity check).

# Fetch a sample existing card
gh api repos/devarno-cloud/crumb/contents/src/content/cards/<<SAMPLE_CARD>> \
  --jq '.content' | base64 -d > /tmp/sample-card.md
petrova crumb-validate /tmp/sample-card.md --json

Expected: exit 0 with all fields valid.

If the validator rejects the existing card, the vendored schema (petrova-codes:cli/src/schemas/crumb-flashcard.schema.json) is stale relative to what CRUMB actually publishes. In that case:

Halt immediately. Do NOT proceed to Taskset 3.
Open a decision doc at docs/decisions/<<ISO_DATE>>-crumb-schema-drift-<<SLUG>>.md documenting the observed field mismatch.
Ask the operator to open a schema-bump PR against petrova-codes to sync the vendored schema.
Resume only once the schema bump has merged and the vendored schema passes the same sample card.

<gate/> Schema-drift gate — proceed only if the sample card validates clean.

Taskset 3 — Author cards (CRUMB-side PR)

Scope: devarno-cloud/crumb. One PR containing all N new cards.

Steps:

Clone CRUMB locally (if not already present):

gh repo clone devarno-cloud/crumb /tmp/crumb-local

Or, if already cloned, pull latest main:

git -C /tmp/crumb-local checkout main && git -C /tmp/crumb-local pull --ff-only

Create a working branch in the CRUMB clone:

git -C /tmp/crumb-local checkout -b "feat/cards-<<PROJECT_PREFIX>>-<<ISO_DATE>>"

Author N cards at /tmp/crumb-local/src/content/cards/<<PROJECT_PREFIX>>-<NNN>-<slug>.md. Use the audit’s source materials (Taskset 1) as the content basis. Each card must:
- Have a filename matching ^[a-z0-9]+-[0-9]{3}(-[a-z0-9-]+)?\.md$.
- Contain 18-field frontmatter per the vendored schema (all required fields present; optional fields populated where evidence exists).
- Include a ## ELI5 section in the body.
- Cover exactly one concept drawn from the guidance docs; do not aggregate multiple concepts into one card.
- Contain no operator-private information. Every sentence must be suitable for public release.
Run validator locally against the new cards:
Terminal window
```
petrova crumb-validate "/tmp/crumb-local/src/content/cards/<<PROJECT_PREFIX>>-*.md" --json
```
Fix all validation errors before proceeding. Exit 0 is a hard prerequisite.

<gate/> Halt BEFORE opening the CRUMB PR. Present the card list (filenames + one-line description per card). Operator confirms cards are content-correct and safe to publish.

On YES, open the CRUMB PR:

gh pr create \
  --repo devarno-cloud/crumb \
  --title "feat(cards): add <<PROJECT_PREFIX>> flashcards (<<N>> cards) — <<SLUG>> wiring" \
  --body "..."

The PR body must list every card filename and its ELI5 summary, cite the decision doc from Taskset 6, and include the validator output (exit code + card count).

Taskset 4 — Local validate

With the CRUMB branch checked out (either from the local clone or via gh pr checkout <<CRUMB_PR>> --repo devarno-cloud/crumb), run the full validator pass:

petrova crumb-validate "/tmp/crumb-local/src/content/cards/<<PROJECT_PREFIX>>-*.md" --json

Expected: exit 0, valid: <<N>>, invalid: 0.

If any card fails, fix locally, push the fix commit to the CRUMB PR branch, and re-run until clean.

Record the output (card count + timestamp) — you will need <<N>> and the run timestamp for the Taskset 5 gate.

Taskset 5 — Cross-repo gate

Wait for the CRUMB PR to merge. Do not self-merge; the operator or a designated reviewer merges. Capture the merge timestamp and final card count:

MERGED_AT="$(gh pr view <<CRUMB_PR>> --repo devarno-cloud/crumb --json mergedAt --jq '.mergedAt')"
CARD_COUNT="$(gh api repos/devarno-cloud/crumb/git/trees/HEAD?recursive=true \
  --jq '[.tree[] | select(.path | startswith("src/content/cards/<<PROJECT_PREFIX>>-")) | select(.path | endswith(".md"))] | length')"

Also run a final post-merge probe:

gh api repos/devarno-cloud/crumb/commits?path=src/content/cards \
  --jq '.[0] | {sha: .sha[0:8], date: .commit.committer.date, message: .commit.message}'

Confirm the commit sha matches the merged PR head.

<gate/> Halt at this gate. Report MERGED_AT, CARD_COUNT, and the commit sha to the operator. Operator explicitly confirms all three look correct before proceeding to Taskset 6.

Taskset 6 — Contract flip

Scope: host (consumer) repo. One PR containing the contract edit and the decision doc.

Populate the evidence block in .petrova/contract.yaml:

crumb:
  status: wired
  declared_at: <<ISO_DATE>>
  evidence:
    content_path: "src/content/cards/<<PROJECT_PREFIX>>-*.md"
    project_prefix: <<PROJECT_PREFIX>>
    card_count: <<N>>
    last_generated_at: <<ISO_DATETIME>>
    generator_id: "human:<<OPERATOR>>"

Fill in:

<<ISO_DATE>> — today’s date in YYYY-MM-DD format.
<<PROJECT_PREFIX>> — the prefix confirmed at Taskset 1.
<<N>> — the CARD_COUNT captured at Taskset 5.
<<ISO_DATETIME>> — the MERGED_AT value captured at Taskset 5 (ISO 8601 UTC).
<<OPERATOR>> — the operator’s public GitHub handle.

Author the decision doc at docs/decisions/<<ISO_DATE>>-wire-crumb-<<SLUG>>.md. Use the petrova-codes decision-doc template. Cover:
- Context: applicability from petrova-codes:registry.yaml, sourced from docs/decisions/2026-05-01-petrova-crumb-spec.md §8.
- Decision: authorise the wiring per core/prompts/08-crumb-wire.md taskset ladder. CRUMB prefix <<PROJECT_PREFIX>>. <> cards merged via CRUMB PR <<CRUMB_PR>>.
- Consequences: petrova doctor --slug=<<SLUG>> reports crumb: ok; cards are public and append-only; contract block flips to wired in this PR.
- Rollback: delete cards from CRUMB via a new CRUMB PR; revert .petrova/contract.yaml.integrations.crumb.status to pending.
Open the consumer-repo PR:
Terminal window
```
gh pr create \
  --title "feat(crumb): wire <<SLUG>> to CRUMB (<<N>> cards, prefix <<PROJECT_PREFIX>>)" \
  --body "..."
```
PR body cites docs/decisions/<<ISO_DATE>>-wire-crumb-<<SLUG>>.md and includes the CRUMB PR URL.

<gate/> Halt with the consumer-repo PR URL. Do not merge without explicit operator authorisation.

Communication protocol

plan-announce: First turn of a new taskset → emit a numbered plan block for that taskset only. Do not execute.
await-gate: End the turn with Awaiting GO TASKSET <N> to proceed. and nothing more.
execute: On GO TASKSET <N>, execute steps in order. One tool call per atomic action. Narrate each in one short sentence before calling.
verify: Run the taskset’s verify block. Do NOT proceed.
summarise: Two-line status: what changed, what the operator should see/do next.

Sandbox denials

Read denied → stop, surface command + reason verbatim, ask operator to either authorise once or run the command themselves and paste result.
Write denied → never retry with a “cleverer” shape. Stop, surface, ask.

Secret denials

CRUMB has no bearer token. If a future CRUMB deployment adds auth, apply the same rules as 07-traceo-wire.md: pipe secrets, never print or commit values.
<<OPERATOR>> is a public handle. Never expand it to an email address or internal ID in any committed file.

Cross-fleet compatibility

All taskset numbers are global. Prefix PR titles feat(crumb): [CRUMB-WIRE/<n>] <summary>.
Resources you create carry discoverable tags:
- Card filenames: <<PROJECT_PREFIX>>-NNN[-slug].md under src/content/cards/. Prefix is the rollback handle.
- Consumer decision doc: docs/decisions/<<ISO_DATE>>-wire-crumb-<<SLUG>>.md. These tags are the rollback handle.
Never assume a repo’s guidance-doc layout. The audit (Taskset 1) determines which files are suitable source material. Respect non-canonical paths (architecture/, requirements/, etc.).
If cards under <<PROJECT_PREFIX>> already exist in CRUMB (partial wiring), do not overwrite or re-number them. Audit the existing set, determine which guidance docs are not yet covered, and author only the gap cards. Renumber starting from the next available NNN.
If the CRUMB PR is already merged when the agent reaches Taskset 5 (e.g. operator merged it manually), capture the merge timestamp from gh pr view and proceed directly to the gate.
Pipelining rule: CRUMB PRs from multiple consumer repos may be open simultaneously. Card filenames include the project prefix, preventing naming collisions. Each repo’s agent opens its own CRUMB PR independently.

Halt rules summary

After Phase 0: auto-proceed only if crumb is not yet ok AND applicability is required. Halt and surface if no-op detected OR if applicability is not required.
After Taskset 1 (audit): <gate/> — operator OKs before any write or PR.
At Taskset 2 (schema-drift): <gate/> — if schema drift detected, halt to open schema-bump decision doc; do not proceed to card authoring until drift is resolved.
At Taskset 3 BEFORE opening CRUMB PR: <gate/> — operator confirms card list and content safety.
At Taskset 5 (cross-repo gate): <gate/> — wait for CRUMB PR merge; operator confirms MERGED_AT, CARD_COUNT, and commit sha.
At Taskset 6 with the consumer-repo PR URL: <gate/> — operator merges.

Success criteria

ID	Verifiable claim
sc-1	`gh api repos/devarno-cloud/crumb/git/trees/HEAD?recursive=true --jq '[.tree[] \| select(.path \| startswith("src/content/cards/<<PROJECT_PREFIX>>-"))] \| length'` returns `<<N>>`
sc-2	`petrova crumb-validate "src/content/cards/<<PROJECT_PREFIX>>-*.md" --json` exits 0 with `invalid: 0`
sc-3	Every card has a `## ELI5` section and no operator-private information
sc-4	`docs/decisions/<<ISO_DATE>>-wire-crumb-<<SLUG>>.md` exists, is dated, and references the CRUMB PR
sc-5	No secret, vault path, private hostname, or private project data appears in any card, PR body, or committed file
sc-6	`.petrova/contract.yaml.integrations.crumb.status == "wired"` and `petrova doctor --slug=<<SLUG>>` reports `crumb: ok`

Secret hygiene

CRUMB is a public repository; no bearer tokens are required to read or write cards via gh. Still:

Never commit ~/Documents/<vault> paths. If a card source is a private document, summarise the concept in your own words — do not quote the vault content.
<<OPERATOR>> resolves to a public GitHub handle only. It must never expand to an email address, internal user ID, or private name in any committed file.
Never include private project information that has not been ratified for public release. Cards are append-only knowledge artefacts visible to anyone; treat each card body like a documentation page.
If a future CRUMB deployment adds auth (e.g. a write-token for CI), apply the same rules as 07-traceo-wire.md: pipe the token value, never print or commit it, and document the rotation schedule in the consumer repo’s docs/deployment/crumb-integration.md.

First-turn instructions

Acknowledge this mission in one short paragraph. Name the host repo (inferred from pwd or git remote) and the single target: CRUMB card authoring and contract flip per this prompt.
Run Phase 0 (petrova doctor --slug=<self>). If already-wired no-op detected, exit.
Run a quick readiness probe: check yq .slug .petrova/contract.yaml, yq '.integrations.crumb' .petrova/contract.yaml, gh api repos/devarno-cloud/crumb/git/trees/HEAD?recursive=true --jq '[.tree[] | select(.path | startswith("src/content/cards/"))] | length' (total CRUMB card count), and ls docs/ 2>/dev/null. Emit results in a compact table.
Present the taskset ladder as a numbered plan tailored to the host repo (note any skips — e.g. if no cards exist under <<PROJECT_PREFIX>> yet, Taskset 2 uses a card from another prefix as the schema sample; if the audit finds no guidance docs suitable for cardification, pause and surface before proceeding).
End with Awaiting GO TASKSET 1 to begin the audit. Do nothing else.