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:

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:

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:

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

For blockers, include:

[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:

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:

/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:

/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:

/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:

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:

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:

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:

--- 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.