# Aim Handoff

> Ephemeral context handoff: structure Engineering Handoff docs to the gold-standard numbered template (LD-CLAUDE_HANDOFF style), update in place, optional Tmux baton pass to a fresh vessel session.

- Skill: `brianv1981/aim-handoff-5` (Agent Skill)
- Install (CLI): `npx skillmds@latest add brianv1981/aim-handoff-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/brianv1981/aim-handoff-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: BrianV1981 (https://skillmd.com/u/brianv1981)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/brianv1981/aim-handoff-5

---


# `aim-handoff`

> **MANDATE:** Package tactical working memory into a standardized Engineering Handoff
> document, and optionally pass that baton into a fresh agent via tmux.

## Relationship to other skills

| Skill | Role |
|-------|------|
| **`aim-memory-wiki`** | **Persistent** project lore — do this **first** (or ensure wiki is current) |
| **`aim-handoff`** (this) | **Ephemeral** baton — mission, traps, exact next steps for the *next* session |
| **`aim-precompact-handoff`** | **Safeguard** — Grok context-window guard; forces a handoff *before* auto-compact destroys context |

Do not confuse precompact (when/why to write under token pressure) with this skill
(what the handoff document must look like).

---

## 1. Core philosophy

1. **UPDATE, do not decapitate.** If `HANDOFF.md` / `LD-CLAUDE_HANDOFF.md` exists, **update** it. Preserve overarching context; consolidate completed work; expand future detail.
2. **Wiki first.** Long-term architecture and decisions belong in `memory-wiki/` via `aim-memory-wiki`. The handoff is the relay baton, not a second wiki.
3. **No guesses.** Unknown → write `UNKNOWN`. Proven → path, SHA, issue #, command, count.
4. **No forced architecture.** Do not invent `docs/` trees or roadmaps the Operator did not provide.

---

## 2. Gold-standard template (numbered sections)

Canonical shape: gold-standard Engineering Handoff with numbered sections **0–9**
(LeadDeed-style `LD-CLAUDE_HANDOFF.md` when that project uses it; otherwise `HANDOFF.md`).

When instructed to prepare a handoff, generate or **update** a structured markdown file
(e.g. `HANDOFF.md` or project-specific `LD-CLAUDE_HANDOFF.md`) with **all** of the following
sections. Mission-specific titles may specialize (e.g. “MODULE-BY-MODULE ANALYSIS FOR #173”)
but the **numbers and roles must remain**:

```markdown
# [Project Name] — Engineering Handoff

> **Updated:** [Timestamp]
> **Updated by:** [Session / vessel id]
> **Priority Mission:** [One-line goal]
> **Operator:** [Name / email]

---

## 0. COMPLETED WORK (DO NOT REVISIT)
| Session | Work | Status |
|---------|------|--------|
| [id] | [brief] | ✅ RESOLVED |

*(Keep clean and consolidated. Point to wiki/issues for deep history — do not re-audit.)*

---

## 1. PROJECT IDENTITY
*(1–3 sentences: what the system is, prod vs local, monorepo root. Bullet key envs/URLs.)*

### Your Knowledge Base
*(Absolute paths to memory-wiki index + 3–5 critical pages/docs.)*

---

## 2. YOUR MISSION: [TITLE]
*(Overarching goal for the *incoming* session.)*

### Execution Queue (in order)
#### 1️⃣ [Task]
**Problem:** …
**Fix:** …
**Key files:** [absolute paths]

---

## 3. DETAILED ANALYSIS / BREAKDOWN
*(Mission-specific depth: module-by-module, system-by-system, or risk-ordered breakdown.
Expand freely; this is where complexity lives so §2 stays scannable.)*

---

## 4. IMPLEMENTATION STRATEGY
*(Ordered approach, tiers, pass structure, tests expected. How to attack §2/§3 without thrash.)*

---

## 5. THE CRITICAL TRAPS & WARNINGS
> **⚠️ EPISTEMIC / OPERATIONAL WARNINGS**
*(Top landmines — e.g. Vercel vs local, wrong env files, destructive git habits.)*

---

## 6. KEY PATHS
*(5–15 absolute paths grouped by concern: infra, targets of the mission, config.)*

---

## 7. THE FULL PICTURE / WHAT COMES AFTER
*(Dependency graph or short roadmap after the priority mission. Parallel quick wins table OK.)*

---

## 8. OPERATOR PREFERENCES
*(Boundaries: do/don't, proof standards, multi-agent coordination, push discipline.)*

---

## 9. IMMEDIATE NEXT STEPS
1. …
2. … *(Imperative, ordered, first command the incoming agent should run.)*
```

### Section count note
The gold standard is **sections 0–9** (ten numbered blocks), matching `LD-CLAUDE_HANDOFF.md`.
Older drafts used a shorter 0–6 skeleton; **prefer 0–9** for full coherence with LeadDeed handoffs.
Do not drop §3–§4 or §7 when the mission is non-trivial.

---

## 3. Update rules (anti-bloat)

1. Move finished items into **§0** with one-line status; strip stale “still open” prose.
2. Rewrite **§2 / §9** for the *next* agent — more detail on the future than on the past.
3. Prefer editing the existing handoff path the project already uses.
4. After structural facts change, also run **`aim-memory-wiki`** so the wiki stays the long-term store.

---

## 4. Blackbox Ingestion (Mandatory Pre-Handoff)

Before executing the final Tmux baton pass or exiting, you MUST seal your current session's raw logs into the immutable blackbox vault using the OpenCode specific extraction hook:

1. Run: `./aim opencode-blackbox --session-id <your-session-uuid>`

> **⚠️ NON-FATAL KEY WARNING:** The blackbox vault uses a headless key fallback. If it reports a missing keyring or a vault warning, DO NOT attempt to fix it or abort the handoff. It is non-fatal. Proceed with the handoff normally.

---

## 5. Tmux baton pass (optional)

Only if the Operator asks you to spawn the next agent:

1. `CURRENT_SESSION=$(tmux display-message -p '#{session_name}')`
2. New name: `${CURRENT_SESSION}-` + 6 random alphanumerics
3. `tmux new-session -d -s "$NEW" "grok"` (or `agy` / `opencode` as appropriate)
4. Load handoff into buffer and paste (not long `send-keys` novels):
   - `tmux set-buffer "$(cat /abs/path/HANDOFF.md)"`
   - `tmux paste-buffer -p -t "$NEW"`
5. Submit:
   - **Grok / OpenCode:** `tmux send-keys -t "$NEW" Enter` only
   - **AGY:** `Escape` then `Enter` (separate calls)
6. Prefer `aim-communicate` / `tmux_send.sh` when messaging an *existing* peer session.
7. Report `tmux attach -t <new>` to Operator; witty goodbye optional.

---

## 6. Slash / triggers

Triggers: handoff, baton, reincarnation doc, `HANDOFF.md`, `LD-CLAUDE_HANDOFF`, session transfer.

Default filename preference: use the project’s existing handoff file if present; else `HANDOFF.md` at vessel/project root.