knowledge-transfer

---
name: knowledge-transfer
description: "Use when a colleague is leaving a project and must hand over knowledge, or when someone new joins a project and receives handover.zip or a handover/ folder. Two phases: export (analyze project + agent project memories from Claude, Codex, or another assistant, then produce a transferable handover.zip archive containing a non-technical onboarding doc + filtered portable memories + a privacy-safe omissions manifest) and import (extract/read the handover package, dry-run the candidate memories, verify every claim against current code, then install accepted memories through the current agent's memory mechanism with per-memory receipts). Trigger on /knowledge-transfer, /knowledge-transfer:knowledge-transfer, $knowledge-transfer, 'handover', 'knowledge transfer', 'passaggio di consegne', 'onboard a new colleague', or when the user mentions taking over / leaving a project."
---

# knowledge-transfer

Transfer project knowledge between colleagues: a short non-technical onboarding
document plus the AI's accumulated project memories, packaged as a local
`handover.zip` archive so the newcomer starts oriented and their AI starts
informed.

## Usage

Claude Code standalone skill:

```
/knowledge-transfer            # auto-detect mode (see below)
/knowledge-transfer export     # outgoing colleague: build handover.zip
/knowledge-transfer import     # new colleague: dry-run, verify, ask, then install
/knowledge-transfer import --dry-run  # verify and show the plan, but write no memories
/knowledge-transfer import --yes      # verify and install without a second prompt
```

Claude Code plugin install:

```
/knowledge-transfer:knowledge-transfer
/knowledge-transfer:knowledge-transfer export
/knowledge-transfer:knowledge-transfer import
```

Codex or another agent that reads `SKILL.md`:

```
$knowledge-transfer            # auto-detect mode
$knowledge-transfer export     # outgoing colleague
$knowledge-transfer import     # new colleague
```

## Mode detection (no argument)

1. If `handover/manifest.json` or `handover.zip` exists in the project root → announce import mode.
2. Otherwise → announce export mode.

State the detected mode in one line and proceed. The user can override at any time.

## Contracts

Read these before producing anything:

- `references/package-format.md` — package structure and manifest schema
- `references/privacy-filter.md` — what may and may not be exported
- `references/onboarding-template.md` — structure, tone, and length of the document
- `references/agent-memory.md` — how to locate and install memories in Claude,
  Codex, or another agent

---

## Export phase

Run from the project root by the colleague leaving the project.

### 1. Analyze the project

- Read README, agent guidance files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
  `.cursor/rules/`, etc. if present), the top-level structure, entry points, and
  main config files. Use subagents for large codebases rather than reading
  everything inline.
- Identify: what the project does, the 3–7 main components, and 2–3 end-to-end
  logical flows worth narrating.
- Detect the project's dominant language (README, docs, recent commit messages);
  the onboarding document is written in that language. Unclear or mixed → English.

### 2. Read the memories

- Locate the current agent's project memory source using
  `references/agent-memory.md`.
- Read only memories scoped to this project or repo. Do not export global user
  preferences or unrelated project history.
- No memory directory or no memories → proceed with the document only, set
  `memories: {"exported": 0, "excluded": 0}` in the manifest, write an empty
  `handover/omissions.json`, and tell the user the package contains no memories.

### 3. Filter the memories

Apply `references/privacy-filter.md` strictly to every memory. Produce:

- portable versions (rewritten, neutral) with `source_id`, `source_hash`,
  `redactions`, and `claims` metadata;
- a per-memory exclusion list with safe categories and short reasons;
- a privacy-safe omissions manifest for the package.

For each exported memory:

- `source_id` is a stable short id, preferably `sha256:<12 hex>` from the
  privacy-normalized source memory content plus the export commit if available.
- `source_hash` is `sha256:<full hash>` of the privacy-normalized source memory
  content before final packaging. Never hash secret-bearing memories or omitted
  private memories into the package.
- `redactions.count` is the number of privacy edits made during rewrite.
- `redactions.categories` uses only safe category names, never private values.
- `claims` is a short list of concrete repo facts the import phase can verify.

### 4. Write the package and archive

- If `handover/` or `handover.zip` already exists, STOP and ask before overwriting.
- Write `handover/ONBOARDING.md` following `references/onboarding-template.md`.
- Write each surviving memory to `handover/memories/<slug>.md` in the portable
  format.
- Write `handover/omissions.json` per `references/package-format.md`. Include
  counts and categories only; never include private source text, names, emails,
  usernames, secrets, or enough detail to reconstruct omitted content.
- Write `handover/manifest.json` per the schema (commit SHA from `git rev-parse
  HEAD`; omit `commit` if not a git repo, omit `author` if git config has no name).
- Create `handover.zip` in the project root containing the full `handover/`
  folder. Prefer `python3 -m zipfile -c handover.zip handover`; if unavailable,
  use an equivalent zip command that preserves the top-level `handover/` directory.
- Do not commit `handover/` or `handover.zip` unless the user explicitly asks.
  The normal workflow is to pass `handover.zip` to the next colleague.

### 5. Final checklist — verify before declaring done

- [ ] `grep` the whole `handover/` tree for the colleague's name, email, and
      username: zero hits.
- [ ] No memory of type `user` in `handover/memories/`.
- [ ] ONBOARDING.md is 600–1000 words (`wc -w`) and contains the six template
      sections.
- [ ] Every exported memory has `source_id`, `source_hash`, `redactions`, and at
      least one verifiable claim.
- [ ] Every file/path cited in an exported memory exists in the project.
- [ ] `omissions.json` contains only safe categories/counts and no omitted
      private content.
- [ ] `manifest.json` parses and counts match the actual files.
- [ ] `handover.zip` exists, passes `python3 -m zipfile -t handover.zip`, and
      contains `handover/ONBOARDING.md`, `handover/manifest.json`,
      `handover/omissions.json`, and every memory file.

Report to the user: package contents, omission category counts, exported memory
count, and suggest passing `handover.zip` to the next colleague. Do not commit the
package unless the user explicitly asks.

---

## Import phase

Run by the new colleague, from the project root, after receiving `handover.zip`
or an already extracted `handover/` folder.

### 1. Read the package

- If `handover.zip` exists and `handover/` is absent, inspect the archive first:
  every entry must start with `handover/`, and no entry may be absolute or contain
  `..`. Then extract it into the project root, for example with
  `python3 -m zipfile -e handover.zip .`.
- Read `handover/manifest.json`, `handover/ONBOARDING.md`,
  `handover/omissions.json` if present, and every file in `handover/memories/`.
- `handover/` and `handover.zip` both missing → stop: explain that the outgoing
  colleague must run `/knowledge-transfer export` first, then send `handover.zip`.
- `manifest.version` unknown → stop and say the skill is too old for this package.
- `manifest.version` 1 → treat `omissions.json`, `claims`, and source hashes as
  optional legacy fields; derive claims from memory bodies during verification.
- `manifest.version` 2 → require `omissions.json`, `source_id`, `source_hash`,
  `redactions`, and `claims` for every memory.

### 2. Verify each memory against the current code

- If the repo is git and the manifest has `commit`, run
  `git diff --stat <commit>..HEAD` to see which areas changed since the export.
- For each memory, verify every claim in `metadata.claims`. If claims are absent
  because this is a legacy package, extract 1–5 concrete claims from the memory
  body before checking.
- Check that the files, paths, and identifiers each claim cites still exist
  (Glob/Grep, not assumption). Record the repo evidence checked: file paths,
  grep queries/hits, git history commands, or the absence that caused rejection.
- Classify:
  - **valid** — everything checks out → install as-is;
  - **stale, obvious fix** — e.g. a cited file was renamed and the new path is
    unambiguous (git log --follow, or a unique search hit) → update the memory body,
    then install;
  - **stale, no obvious fix** — discard, note the one-line reason.

### 3. Dry-run import plan

Before writing to any memory store, create and present a dry-run plan:

- Write `handover/import-plan.json` with one entry per candidate memory:
  `source_id`, `source_hash`, `memory_file`, `claims`, `evidence_checked`,
  `proposed_action` (`install`, `rewrite`, `reject`), `reason`,
  `redactions`, and `destination`.
- Show the full `ONBOARDING.md` content first.
- Then show a concise candidate memory table with the proposed action and reason.
- If the user invoked `import --dry-run`, stop here and write no memories.
- If the user invoked plain `import`, STOP after presenting the plan and ask for
  confirmation before writing memories.
- If the user invoked `import --yes`, continue after presenting the plan.

### 4. Install

- Install each accepted memory through the current agent's memory mechanism (see
  `references/agent-memory.md`), keeping the portable memory content intact and
  adapting only the storage wrapper/index if the target agent requires it.
- Slug collision with an existing memory: do NOT overwrite. Report the collision
  and ask the user which to keep.
- If the target memory store has an index file, append one index line per
  installed memory (create it if absent). If the current agent forbids direct
  memory writes, create or present the approved memory-update artifact instead.
- For every candidate memory, write a per-memory receipt to
  `handover/import-receipts/<slug>.json`, including:
  - `source_id` and `source_hash`;
  - `export_commit` from `manifest.commit` if present;
  - claims the memory made;
  - repo evidence checked;
  - stale or superseded findings;
  - privacy redaction count/categories;
  - destination memory path or update mechanism;
  - final action: `installed`, `rewritten`, `rejected`, or `blocked`;
  - reason.
- Write `handover/import-report.json` summarizing counts and receipt paths.

### 5. Report

Present to the user, in this order:

1. The import summary: installed / rewritten / rejected / blocked.
2. Receipt path for each memory and one line of reasoning.
3. Any omission categories from `omissions.json`, phrased as known gaps rather
   than private details.
4. A closing note: technical questions can now lean on the imported memories.

---

## Edge cases

| Situation | Behavior |
|---|---|
| No memories at export | Document-only package; say so explicitly. |
| Project is not a git repo | Manifest without `commit`; import verification falls back to existence checks only. |
| `handover/` exists at export | Ask before overwriting. |
| `handover.zip` exists at export | Ask before overwriting. |
| `handover.zip` present at import | Validate archive paths, extract to `handover/`, then import. |
| `import --dry-run` | Verify, write/present `import-plan.json`, then stop before memory writes. |
| `handover/` and `handover.zip` missing at import | Stop with instructions for the outgoing colleague. |
| Slug collision at import | Never overwrite; surface and ask. |
| `omissions.json` missing in a v1 package | Continue as legacy import and say omission details are unavailable. |
| `omissions.json` missing in a v2 package | Stop; the package is incomplete. |
| Unknown `manifest.version` | Stop; ask the user to update the skill. |