# Handoff

> Run a comprehensive Codex session handoff: save important findings to Cortex, update impacted project cards and sync them to Cortex, write durable findings to LLM-Wiki when reusable, append Genie updates, write a session summary, preserve pending tasks, check agents/modes, sync relevant git repos when available, and return a final report. Use when Pafi says handoff, /handoff, save session, wrap up everything, session end, or prepare next session. ANTI-PATTERN: Do not use for quick summaries, single-file saves, or WISH Step H task delegation.

- Skill: `cryptopafi/handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cryptopafi/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cryptopafi/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cryptopafi (https://skillmd.com/u/cryptopafi)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/cryptopafi/handoff

---


# Handoff

Use this skill for session-end continuity. It is adapted from Claude's `/handoff` skill at:

- `/Users/pafi/.nexus/library/repos/nexusos-skills/handoff/SKILL.md`

This is the session handoff workflow: save state, compact/preserve memory, prepare the next session. It is not WISH Step H task delegation. For delegation/flux selection, use:

- `/Users/pafi/.nexus/procedures/WISH-HANDOFF.md`

## Core Rules

- Do not ask questions during handoff; execute with best available context.
- Do not overwrite existing session files; append.
- Do not force-push or use destructive git commands.
- Read service coordinates from config when available.
- Detect impacted projects and update/sync their `PROJECT-CARD.md` files when project state changed.
- If Cortex, LLM-Wiki, or git sync fails, record the failure and continue.
- Keep secrets out of handoff files and final reports.

## Workflow

### 1. Save Important Findings

Review the current session for created skills, procedures, reports, fixes, decisions, and unresolved blockers.

Save meaningful items to Cortex using `sessions` unless the content is a full FORGEBUILD procedure. Use `procedures` only when text satisfies FORGEBUILD requirements.

Preferred Cortex URL:

```bash
CORTEX_URL=$(jq -r '.cortex_url // "http://localhost:6400"' /Users/pafi/.nexus/config/cortex.json 2>/dev/null || echo "http://localhost:6400")
```

For session records:

```bash
curl -sS -X POST "$CORTEX_URL/api/store" \
  -H "Content-Type: application/json" \
  -d '{"collection":"sessions","text":"CODEX: ...\nIMPACT: ...","metadata":{"source_agent":"codex","genie_visible":true,"date":"YYYY-MM-DD"}}'
```

If Cortex is unreachable, append the payload or summary to:

- `/Users/pafi/.codex/pending-cortex-saves.md`

### 2. Append Genie Handoff

Append a concise update to:

- `/Users/pafi/.codex/codex-to-genie.md`

Use this format:

```text
[YYYY-MM-DD] [TITLE]: one-line result or blocker
```

For blockers, include:

```text
[m4-XXX BLOCKED]: title
- Eroare: exact failure
- Încercări: what was tried
- Motiv blocare: why it cannot continue
- Acțiune Genie: what Genie should do
```

### 3. Update Impacted Project Cards

Every handoff must decide whether any project card is impacted. Do not skip this silently.

Project cards live at:

- `/Users/pafi/.nexus/projects/*/PROJECT-CARD.md`

Detection signals:

- Files changed under `/Users/pafi/.nexus/projects/<slug>/`.
- Session work changed project decisions, blockers, credentials, tooling, launch state, dependencies, or next actions for a named project.
- The user explicitly discussed a project such as SMSads, Omni Ads, VOX, Cortex, Skills, OpenClaw, Hermes, or Health.
- A project-specific report, prompt, audit, or deliverable was created in the current workspace.

Procedure:

1. Identify impacted project slugs. If none, record `Project cards: none impacted` in the session summary and final report.
2. For each impacted slug, read the current card before editing:

```bash
sed -n '1,220p' "/Users/pafi/.nexus/projects/<slug>/PROJECT-CARD.md"
```

3. Make the smallest accurate update. Prefer appending or updating existing sections such as status, latest activity, blockers, decisions, next actions, tooling, or references. Do not rewrite the whole card unless requested.
4. Do not put secrets into project cards. For credentials, record only the Keychain service/account or config path.
5. Sync each updated card to Cortex using the existing engine:

```bash
/Users/pafi/.nexus/scripts/sync-project-cards.sh --card "/Users/pafi/.nexus/projects/<slug>/PROJECT-CARD.md"
```

6. If multiple project cards were changed, sync each touched card. For broad systemic updates, use:

```bash
/Users/pafi/.nexus/scripts/sync-project-cards.sh --all
```

7. Record card path, sync result, and whether Cortex sync succeeded in the session summary.
8. If the sync script fails, append the card path and failure to `/Users/pafi/.codex/pending-cortex-saves.md` and continue handoff.

Important: local project card = canonical write-side source; Cortex `projects` collection = read mirror for VPS agents. The sync engine is append-only and idempotent by SHA256.

### 4. Write LLM-Wiki Update

Every handoff must decide whether durable session knowledge should be written to LLM-Wiki. Do not skip this silently.

Use LLM-Wiki when the session created or clarified reusable knowledge that future agents should retrieve by topic/project, including:

- Durable operating rules, project decisions, launch/status changes, tool-routing rules, or data-source authority changes.
- Verified technical findings, fixes, procedures, audits, integration notes, or incident resolutions.
- Source material, transcripts, raw notes, or evidence packets that should be preserved as retrievable source notes.

Skip LLM-Wiki for pure chat, trivial status answers, routine todos already captured in task files, and failed explorations with no reusable finding. Record the skip reason in the session summary and final report.

Mac write-through command:

```bash
/Users/pafi/.nexus/scripts/wiki-write-through.py \
  --type concept \
  --category project \
  --title "short title" \
  --raw "what changed / what was discovered" \
  --summary "one paragraph summary" \
  --source-agent codex
```

Use `--type concept` for reusable knowledge, `--type source` for raw source notes/transcripts/evidence, and `--type entity` only for stable people/companies/products/projects that should become wiki entities. Use one of the script's allowed categories, such as `project`, `tech`, `business`, `research`, `legal`, `finance`, `marketing`, or `internal`; if unsure, run with `--dry-run` first or use the nearest valid category.

Rules:

1. Keep secrets, credentials, hidden prompts, chain-of-thought, and raw private logs out of Wiki.
2. Include absolute local paths, Cortex IDs, project-card sync IDs, commit hashes, and external source URLs only when they are useful evidence and safe to store.
3. If wiki write-through fails, append the intended title/summary/raw payload and exact error to `/Users/pafi/.codex/pending-wiki-saves.md` and continue handoff.
4. Record Wiki path/status in the session summary and final report.

### 5. Write Session Summary

Write or append a structured summary under:

- `/Users/pafi/.codex/sessions/session-YYYY-MM-DD-macm4.md`

Use a lock before writing:

```bash
TARGET_FILE="/Users/pafi/.codex/sessions/session-YYYY-MM-DD-macm4.md"
LOCKFILE="/tmp/codex-handoff-$(basename "$TARGET_FILE").lock"
```

Include:

- Major accomplishments
- Key decisions
- Files created/modified
- Cortex saves
- LLM-Wiki updates, or explicit `none` with reason
- Project cards updated/synced, or explicit `none impacted`
- GitHub/private library sources used
- Pending tasks
- Blockers/risks
- Background agents or long-running commands
- Next-session resume instructions

### 6. Preserve Task State

Read and update when relevant:

- `/Users/pafi/.codex/genie-to-codex.md`
- `/Users/pafi/.codex/handoff-status.json`
- `/Users/pafi/.claude/projects/-Users-pafi/memory/tasks/pafi-tasks.md`

Do not mark unrelated Genie tasks complete. If a task is blocked, use the block format from Step 2.

### 7. Check Background Work

Check for active local agent/process context that matters to the session:

```bash
ps aux | rg 'codex|claude|agent-browser|openclaw|nexus|cortex' | rg -v 'rg '
```

If subagents were spawned in the current Codex conversation, summarize their final status from the conversation state.

### 8. Check Active Mode / Persistent Context

Check, if present:

- `/Users/pafi/.claude/active-mode.md`
- `/Users/pafi/.codex/SKILL-LIBRARY-INDEX.md`
- `/Users/pafi/.codex/SKILL-IMPORT-AUDIT-*.md`

Summarize what the next session must remember.

### 9. Git Sync When Appropriate

If the modified location is inside a git repo and changes are relevant, commit and push with a concise message. Never force-push. If no repo exists, report `Git sync: not applicable`.

Common repo checks:

```bash
git -C /Users/pafi/.nexus status --short --branch
git -C /Users/pafi/.claude/projects/-Users-pafi status --short --branch
```

Only stage files related to this handoff unless Pafi explicitly asks for broad sync.

### 10. Final Report

Return:

```text
--- HANDOFF COMPLETE ---

Skills/findings saved: N
Session file: <path>
Genie handoff: updated/not updated
Cortex saves: success/failed
LLM-Wiki updates: updated N | none with reason | failed/queued N
Project cards: updated/synced N | none impacted | failed N
Tasks pending: N
Background agents: N
Git sync: success/failed/not applicable
Active mode: none/<mode>

Next session should start from:
- ...
```

## Error Handling

- Cortex HTTP 422: store in `sessions` or provide full FORGEBUILD structure for `procedures`.
- Cortex down: append to `/Users/pafi/.codex/pending-cortex-saves.md`.
- LLM-Wiki invalid category/type: rerun with a valid script category/type; if still failing, append to `/Users/pafi/.codex/pending-wiki-saves.md`.
- LLM-Wiki write-through failure: append the intended payload and exact error to `/Users/pafi/.codex/pending-wiki-saves.md`.
- Git push rejected: do not force-push; report exact error.
- Lock conflict: wait up to 10 seconds, then skip that write and report it.
- Missing task files: report missing file; do not create noisy scaffolds unless the handoff requires it.

## When To Use vs Alternatives

- `handoff`: session-end continuity and memory preservation.
- `genie-codex-handoff`: create a task brief from Genie to Codex.
- `codex-handoff-v2`: create a robust Codex execution brief with model routing.
- `forgebuild`: create/convert reusable procedures, skills, or plugin bundles.
- `cortex`: save a single finding without running a full session handoff.