# jumpifequal/handoff-skill architecture

> Architecture diagram of the GitHub repository jumpifequal/handoff-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jumpifequal/handoff-skill
- Repository: https://github.com/jumpifequal/handoff-skill

## Overview

Handoff is a portable Agent Skill for capturing session state in a structured Markdown artifact and resuming work in another AI session. The primary flow is conversational handoff creation, artifact transfer, intake, and continuation; optional Claude Code and Codex lifecycle hooks create degraded transcript-based fallback artifacts. The README documents domain-specific addenda and validation as additional capabilities. Sampled hook and validator source supports those internal edges; unsampled manual-skill behavior is represented only at the documented level.

Main entry points: [`scripts/claude_handoff_hook.js`](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/claude_handoff_hook.js) (Claude fallback hook), [`scripts/codex_handoff_hook.js`](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/codex_handoff_hook.js) (Codex fallback hook), [`scripts/validate_handoff.js`](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/validate_handoff.js) (Handoff validator), [`SKILL.md`](https://github.com/jumpifequal/handoff-skill/blob/main/SKILL.md) (Handoff skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_manual["Manual handoff"]
  node_skill["Handoff skill<br/>[SKILL.md]"]
  node_domain["Domain addenda<br/>[domain-addenda.md]"]
  node_examples["Usage examples<br/>[examples.md]"]
end

subgraph group_artifact["Artifact and intake"]
  node_handoff["Handoff artifact"]
  node_receiver(("Receiving AI"))
  node_intake["Intake guidance<br/>[intake.md]"]
end

subgraph group_automation["Lifecycle automation"]
  node_claude(("Claude Code lifecycle"))
  node_codex(("Codex CLI lifecycle"))
  node_claude_install["Claude hook installer"]
  node_codex_install["Codex hook installer"]
  node_claude_hook["Claude fallback hook"]
  node_codex_hook["Codex fallback hook"]
  node_transcript["Session transcript"]
end

subgraph group_validation["Validation"]
  node_validator["Handoff validator"]
end

node_user(("User"))

node_user -->|"requests handoff"| node_skill
node_skill -.->|"adds relevant context"| node_domain
node_skill -->|"creates artifact"| node_handoff
node_user -->|"provides artifact"| node_receiver
node_receiver -->|"follows intake"| node_intake
node_receiver -->|"reads state"| node_handoff
node_examples -.->|"demonstrates use"| node_user
node_claude -.->|"triggers fallback"| node_claude_hook
node_codex -.->|"triggers fallback"| node_codex_hook
node_transcript -.->|"supplies transcript"| node_claude_hook
node_transcript -.->|"supplies transcript"| node_codex_hook
node_claude_hook -->|"writes raw dump"| node_handoff
node_codex_hook -->|"writes raw dump"| node_handoff
node_claude_hook -.->|"self-validates"| node_validator
node_codex_hook -.->|"self-validates"| node_validator
node_user -->|"checks artifact"| node_validator
node_claude_install -->|"installs hook"| node_claude_hook
node_codex_install -->|"installs hook"| node_codex_hook
node_validator -->|"checks structure"| node_handoff

click node_skill "https://github.com/jumpifequal/handoff-skill/blob/main/SKILL.md"
click node_domain "https://github.com/jumpifequal/handoff-skill/blob/main/references/domain-addenda.md"
click node_intake "https://github.com/jumpifequal/handoff-skill/blob/main/docs/intake.md"
click node_examples "https://github.com/jumpifequal/handoff-skill/blob/main/docs/examples.md"
click node_claude_install "https://github.com/jumpifequal/handoff-skill/blob/main/scripts/claude_install_hooks.js"
click node_codex_install "https://github.com/jumpifequal/handoff-skill/blob/main/scripts/codex_install_hooks.js"
click node_claude_hook "https://github.com/jumpifequal/handoff-skill/blob/main/scripts/claude_handoff_hook.js"
click node_codex_hook "https://github.com/jumpifequal/handoff-skill/blob/main/scripts/codex_handoff_hook.js"
click node_validator "https://github.com/jumpifequal/handoff-skill/blob/main/scripts/validate_handoff.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_domain,node_examples,node_user toneBlue
class node_handoff,node_receiver,node_intake toneAmber
class node_claude,node_codex,node_claude_install,node_codex_install,node_claude_hook,node_codex_hook,node_transcript toneMint
class node_validator toneRose
```

## Components

### Manual handoff

- [Handoff skill](https://github.com/jumpifequal/handoff-skill/blob/main/SKILL.md): `SKILL.md`
- [Domain addenda](https://github.com/jumpifequal/handoff-skill/blob/main/references/domain-addenda.md): `references/domain-addenda.md`
- [Usage examples](https://github.com/jumpifequal/handoff-skill/blob/main/docs/examples.md): `docs/examples.md`

### Artifact and intake

- **Handoff artifact**
- **Receiving AI**
- [Intake guidance](https://github.com/jumpifequal/handoff-skill/blob/main/docs/intake.md): `docs/intake.md`

### Lifecycle automation

- **Claude Code lifecycle**
- **Codex CLI lifecycle**
- [Claude hook installer](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/claude_install_hooks.js): `scripts/claude_install_hooks.js`
- [Codex hook installer](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/codex_install_hooks.js): `scripts/codex_install_hooks.js`
- [Claude fallback hook](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/claude_handoff_hook.js): `scripts/claude_handoff_hook.js`
- [Codex fallback hook](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/codex_handoff_hook.js): `scripts/codex_handoff_hook.js`
- **Session transcript**

### Validation

- [Handoff validator](https://github.com/jumpifequal/handoff-skill/blob/main/scripts/validate_handoff.js): `scripts/validate_handoff.js`

### Other components

- **User**

## Connections

- User → Handoff skill: requests handoff
- Handoff skill → Domain addenda: adds relevant context
- Handoff skill → Handoff artifact: creates artifact
- User → Receiving AI: provides artifact
- Receiving AI → Intake guidance: follows intake
- Receiving AI → Handoff artifact: reads state
- Usage examples → User: demonstrates use
- Claude Code lifecycle → Claude fallback hook: triggers fallback
- Codex CLI lifecycle → Codex fallback hook: triggers fallback
- Session transcript → Claude fallback hook: supplies transcript
- Session transcript → Codex fallback hook: supplies transcript
- Claude fallback hook → Handoff artifact: writes raw dump
- Codex fallback hook → Handoff artifact: writes raw dump
- Claude fallback hook → Handoff validator: self-validates
- Codex fallback hook → Handoff validator: self-validates
- User → Handoff validator: checks artifact
- Claude hook installer → Claude fallback hook: installs hook
- Codex hook installer → Codex fallback hook: installs hook
- Handoff validator → Handoff artifact: checks structure