Context Bridge

context-bridge

A skill that stops cross-session amnesia in Claude Code projects. Each project gets a small .claude/wiki/ (markdown, append-only) plus a save+sync protocol that produces a paste-and-resume handoff prompt for the next session.

What this skill does

• Scaffolds a .claude/wiki/ with 4 root files (_hot, _log, _findings, _schema) plus decisions/ and gotchas/ as they accrue.
• Captures non-obvious learnings into the wiki during a session (/cb-ingest).
• Closes a session via an 11-step save+sync that updates the wiki, commits, and prints a handoff prompt (/cb-save-sync → /cb-handoff).
• Embeds two honesty rules (never-fabricate, 95% confidence) into the project's CLAUDE.md so the discipline travels with the wiki.

What this skill does NOT do

• ❌ Mid-session bloat. Use /strategic-compact, /aside, or native compaction.
• ❌ Multi-user / team-shared wikis. Single-developer, single-machine.
• ❌ Code-aware retrieval / embeddings. Wiki is plain markdown; grep is the search.
• ❌ Auto-summarization of past sessions. The author decides what's durable.
• ❌ IDE-level context (Cursor / Aider / Codex). Claude Code only in v0.1.

If your need is in that list, this is the wrong skill — and that's fine. Skill body is intentionally narrow.

When to use

• Project lifespan > ~3 days, multi-session.
• Solo dev using Claude Code as the primary loop.
• You catch yourself re-deriving the same context every Monday.

When NOT to use

• Single-session weekend script. Overkill.
• Throwaway prototype.
• Team already on Confluence + ADRs — coexists but adds little.
• Workflow where Claude Code is secondary.

Commands

All five commands are implemented in v0.1. Eight deep references are shipped in references/: protocol canon, handoff template, wiki structure, honesty rules, findings register, secret-scan guidance, migration playbook, and the Karpathy schema delta.

Wiki shape

Bootstrapped by /cb-init. All filenames lowercase, dashes, no spaces.

Templates live in templates/. Schema delta vs. Karpathy's original LLMwiki: see references/karpathy-schema-delta.md. Full schema with frontmatter conventions: references/wiki-structure.md.

The 11-step save+sync protocol

Full canonical text: references/save-sync-protocol.md. Step 0's pattern set + rationale: references/secret-scan-guidance.md.

Summary:

0. Secret + PII scan (block on hit).
1. Run tests; update count if changed.
2. git commit locally (specific files, not -A).
3. Push .md files to remote (docs-only by default).
4. Push feature branch if on one.
5. Optional: project docs lint.
6. Wiki sync — propose updates, user approves per item.
7. Bump _hot.md + append _log.md.
8. Promote major findings to _findings.md.
9. Update memory + MEMORY.md (if used).
10. Generate handoff prompt → SESSION_HANDOFF_<date>.md.

Steps 5, 6 (user approval), 9 are project-specific in effect but procedurally identical across projects.

Handoff prompt template

The output of /cb-handoff. Pasted into a fresh session = warm resume in <30s.

I'm continuing the <project> work. Last session closed <YYYY-MM-DD>.

Read these in order, fast:
1. <project>/.claude/wiki/_hot.md
2. <project>/.claude/wiki/_log.md (last entry only)
3. <project>/.claude/wiki/_findings.md
4. <project>/SESSION_HANDOFF_<date>.md (full handoff)

Then summarize back to me in 5 bullets:
- What we're building
- What's pending and priority
- Top blockers/risks
- Today's first task
- What the next 60 minutes look like

After your summary, ask me:
1. <any open question pulled from _hot.md>

Honesty: 95% confidence gate. Never fabricate paths or commands. Use Read/Grep/Glob to verify.
Velocity: speed + usefulness wins. Cut scope when a gate is at risk.

Full template + adaptation guidance: references/handoff-template.md.

Honesty rules (inherited by every adopter project)

The marked section /cb-init appends to CLAUDE.md codifies two rules:

• Never fabricate. No file paths, function names, line numbers, or API signatures without verification via Read / Grep / Glob.
• Earned confidence. "95% confident" requires full end-to-end homework — trace the code path, verify data shape at each boundary, check failure modes, read tests.

Full rationale + examples: references/honesty-rules.md.

Findings register lifecycle

Each _findings.md entry: ID + severity + status + phase to fix + detail + mitigation.

• States: OPEN → IN PROGRESS → RESOLVED → ACCEPTED.
• Severity: 🔴 CRITICAL / 🟡 HIGH / 🟢 MEDIUM/LOW.
• On resolution with a non-obvious fix: promote to gotchas/gotcha-<topic>.md.

Full schema: references/findings-register.md.

Adoption checklist

1. npx skills add aksheyw/context-bridge (install once, machine-wide).
2. cd <project> and run /cb-init. Pre-flight scan flags collisions.
3. Read the 5-line tour printed by /cb-init.
4. Work normally. At session close say "save and sync" → skill runs /cb-save-sync → /cb-handoff.
5. Next session, paste the handoff prompt. Warm resume.

Migration from an existing .claude/wiki/

/cb-init detects prior wikis (Karpathy llm-wiki or your own) and prompts:

• Migrate — add _hot.md + _findings.md; preserve existing files.
• Adopt as-is — record current shape in _schema.md; no new files.
• Refuse — abort cleanly; no changes made.

Full guidance: references/migration-from-existing.md.

Attribution

Full provenance: CREDITS.md.

• Wiki-as-compounding-knowledge pattern: Andrej Karpathy (LLM Wiki gist).
• Brainstorm → spec → plan workflow + "skill that explains skills" pattern: Jesse Vincent (Superpowers, MIT; sponsor).
• Claude Code + skills format: Anthropic (claude.ai/code).
• TDD discipline informing save+sync gates: Kent Beck.

Original to this skill: 11-step save+sync protocol, _hot.md + _findings.md + decisions/ + gotchas/, handoff prompt template, honesty rules. See CREDITS.md §3.

Safety

• Templates ship scrubbed. Only ExampleApp / ExampleService / ExampleUser appear.
• Adopters should enable a local pre-commit hook (.githooks/pre-commit, opt-in via git config core.hooksPath .githooks) to scan for project-specific proper nouns + common secret patterns before any commit.
• Never paste API keys, tokens, or production IDs into the wiki. Wiki is plain markdown and travels with git.
• Repo-side: GitHub secret-scanning + push-protection are enabled on the context-bridge repo itself.