Session Handoff
Create comprehensive handoff documents that enable a fresh agent to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.
The workstream path first
When arbora is connected (see the canopy skill), the handoff lives in the shared workstream of
this workspace, so any coding harness on the same workspace picks it up:
- Hand off: call
write with op="workstream.checkpoint" and params
harness_session_id (this session), summary (2000 characters or fewer:
what was done, what is left, the decisions taken), run_ids (open runs) and
trigger="manual".
- Resume: call
ask with op="workstream.get" and workspace_root set to
the current working directory. Continue from its last checkpoint and note
the other attached sessions.
Use the local handoff file below only when the door is unreachable.
Capabilities
- Scaffold Generation — Auto-scaffolds handoff documents with system, git, and file context.
- Handoff Validation — Performs secret-scanning, placeholder checks, and quality scoring.
- Staleness Scoring — Calculates divergency metrics based on git timeline and files.
- Episodic Memory Integration — Double-writes handoffs as markdown and Arbora knowledge nodes.
Steps
Step 1: mode_selection
Determine which mode applies to the current session:
- Creating a handoff? User wants to save current state, pause work, or context is getting full.
- Follow branch:
generate_scaffold -> complete_and_validate -> memory_persistence.
- Resuming from a handoff? User wants to continue previous work or load context.
- Follow branch:
locate_handoffs -> verify_staleness_context -> begin_execution.
- Proactive suggestion — After substantial work (5+ file edits, complex debugging, major design decisions), suggest:
"We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
Step 2: generate_scaffold [depends_on: mode_selection]
Run the scaffold script to create a pre-filled handoff document if in CREATE mode:
- Requires: primary script
scripts/create_handoff.py [task-slug]
- Example:
python scripts/create_handoff.py implementing-user-auth
- For continuation handoffs (linking to previous):
python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-143022-auth.md
- The script will:
- Create
.agent/handoffs/ directory if needed
- Generate timestamped filename (
YYYY-MM-DD-HHMMSS-[slug].md)
- Pre-fill: project path, git branch, recent commits, modified files
- Add chain links if continuing from a previous handoff
Step 3: locate_handoffs [depends_on: mode_selection]
Find available handoffs if in RESUME mode using either local filesystem or the Knowledge Graph:
Step 4: complete_and_validate [depends_on: generate_scaffold]
Open the generated file, fill in all sections, and run the validation script to verify completeness and security:
Step 5: verify_staleness_context [depends_on: locate_handoffs]
Assess if handoff context is still current and analyze divergence:
- Requires: primary script
scripts/check_staleness.py <handoff-file>
- The script checks: time elapsed, git commits since handoff, files changed, branch divergence, missing referenced files.
- Staleness levels:
- FRESH — Safe to resume; minimal changes since handoff
- SLIGHTLY_STALE — Review changes, then resume
- STALE — Verify context carefully before proceeding
- VERY_STALE — Consider creating a fresh handoff first
Step 6: memory_persistence [depends_on: complete_and_validate]
Persist the validated handoff to both local markdown and Arbora:
- Markdown local fallback: file is stored in
.agent/handoffs/ following the naming convention YYYY-MM-DD-HHMMSS-[slug].md.
- Knowledge Graph global memory store:
- Invoke
kg_memory_store MCP tool with memory_type set to episodic.
- Pass the full content of the handoff document, and include tags like
handoff, session, and the [slug].
- This ensures the dual-write strategy: the Markdown file acts as a local fallback, while the KG serves as the global memory store.
- For long-running projects, chain handoffs together to maintain context lineage:
handoff-1.md (initial work) -> handoff-2.md --continues-from handoff-1.md -> handoff-3.md --continues-from handoff-2.md.
Step 7: begin_execution [depends_on: verify_staleness_context]
Load the verified context and begin working on the immediate next steps list:
- Follow
references/resume-checklist.md:
- Verify project directory and git branch match
- Check if blockers from the handoff have been resolved
- Validate assumptions still hold (run a quick
git status)
- Review modified files for conflicts
- Check environment state (services running, env vars set)
- Start with Immediate Next Steps item #1 from the handoff document. Reference:
- "Critical Files" section for important file locations
- "Key Patterns Discovered" for conventions to follow
- "Potential Gotchas" to avoid known issues
- As you work: mark completed items in "Pending Work", add new discoveries to relevant sections, and for long sessions create a new handoff with
--continues-from to chain them.
Storage Location
Handoffs are stored in: .agent/handoffs/
Naming convention: YYYY-MM-DD-HHMMSS-[slug].md
Example: 2024-01-15-143022-implementing-auth.md
Scripts
| Script |
Purpose |
scripts/create_handoff.py [slug] [--continues-from <file>] |
Generate new handoff with smart scaffolding |
scripts/list_handoffs.py [path] |
List available handoffs in a project |
scripts/validate_handoff.py <file> |
Check completeness, quality, and security |
scripts/check_staleness.py <file> |
Assess if handoff context is still current |
References
references/handoff-template.md — Complete template structure with guidance
references/resume-checklist.md — Verification checklist for resuming agents
1---2name: session-handoff-23description: >-4 Create and restore comprehensive context handoff documents for agent session5 transfers. Use when context is getting full, a major task milestone is complete,6 work is pausing, or when resuming from a previous session. Triggers include7 "create handoff", "save state", "context is full", "I need to pause", "load8 handoff", "resume where we left off", or proactively after 5+ file edits or9 complex multi-step work. Do NOT use for project documentation — this is for10 agent-to-agent context preservation.11license: MIT12metadata:13 source: https://skillmd.com/skills/knuckles-team/session-handoff-214 domain: core15 skill_type: skill16 tags: [handoff, context, session, resumption, continuity, memory]17 version: '1.6.0'18 author: Genius19---2021# Session Handoff2223Create comprehensive handoff documents that enable a fresh agent to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.2425---2627## The workstream path first2829When arbora is connected (see the `canopy` skill), the handoff lives in the shared workstream of30this workspace, so any coding harness on the same workspace picks it up:31321. **Hand off:** call `write` with `op="workstream.checkpoint"` and params33 `harness_session_id` (this session), `summary` (2000 characters or fewer:34 what was done, what is left, the decisions taken), `run_ids` (open runs) and35 `trigger="manual"`.362. **Resume:** call `ask` with `op="workstream.get"` and `workspace_root` set to37 the current working directory. Continue from its last checkpoint and note38 the other attached sessions.3940Use the local handoff file below only when the door is unreachable.4142---4344## Capabilities45461. **Scaffold Generation** — Auto-scaffolds handoff documents with system, git, and file context.472. **Handoff Validation** — Performs secret-scanning, placeholder checks, and quality scoring.483. **Staleness Scoring** — Calculates divergency metrics based on git timeline and files.494. **Episodic Memory Integration** — Double-writes handoffs as markdown and Arbora knowledge nodes.5051---5253## Steps5455### Step 1: mode_selection56Determine which mode applies to the current session:57- **Creating a handoff?** User wants to save current state, pause work, or context is getting full.58 - Follow branch: `generate_scaffold` -> `complete_and_validate` -> `memory_persistence`.59- **Resuming from a handoff?** User wants to continue previous work or load context.60 - Follow branch: `locate_handoffs` -> `verify_staleness_context` -> `begin_execution`.61- **Proactive suggestion** — After substantial work (5+ file edits, complex debugging, major design decisions), suggest:62 > "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."6364### Step 2: generate_scaffold [depends_on: mode_selection]65Run the scaffold script to create a pre-filled handoff document if in CREATE mode:66- Requires: primary script `scripts/create_handoff.py [task-slug]`67 - Example: `python scripts/create_handoff.py implementing-user-auth`68 - For continuation handoffs (linking to previous): `python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-143022-auth.md`69- The script will:70 - Create `.agent/handoffs/` directory if needed71 - Generate timestamped filename (`YYYY-MM-DD-HHMMSS-[slug].md`)72 - Pre-fill: project path, git branch, recent commits, modified files73 - Add chain links if continuing from a previous handoff7475### Step 3: locate_handoffs [depends_on: mode_selection]76Find available handoffs if in RESUME mode using either local filesystem or the Knowledge Graph:77- **Local Filesystem**:78 ```bash79 python scripts/list_handoffs.py80 ```81- **Knowledge Graph (Recommended)**: Use the `kg_memory_recall` MCP tool with `memory_type` set to `episodic` to semantically search for previous handoff states related to your current task. This is particularly useful if the local `.agent/handoffs/` directory was lost or if you need to find a handoff by context rather than filename.8283### Step 4: complete_and_validate [depends_on: generate_scaffold]84Open the generated file, fill in all sections, and run the validation script to verify completeness and security:85- Open the generated file and fill in all `[TODO: ...]` sections. Prioritize:86 1. **Current State Summary** — What is happening right now87 2. **Important Context** — Critical info the next agent MUST know88 3. **Immediate Next Steps** — Clear, actionable first steps (numbered)89 4. **Decisions Made** — Choices with rationale, not just outcomes90 Use `references/handoff-template.md` for guidance.91- Execute validation:92 ```bash93 python scripts/validate_handoff.py <handoff-file>94 ```95 - The validator checks: No `[TODO: ...]` placeholders remaining, required sections present and populated, no potential secrets detected (API keys, tokens, passwords), referenced files exist, and a quality score (0–100).96- **Do not finalize a handoff with secrets detected or a score below 70.**97- Report to user: Handoff file location, validation score and any warnings, summary of captured context, and first action item for the next session.9899### Step 5: verify_staleness_context [depends_on: locate_handoffs]100Assess if handoff context is still current and analyze divergence:101- Requires: primary script `scripts/check_staleness.py <handoff-file>`102- The script checks: time elapsed, git commits since handoff, files changed, branch divergence, missing referenced files.103- Staleness levels:104 - **FRESH** — Safe to resume; minimal changes since handoff105 - **SLIGHTLY_STALE** — Review changes, then resume106 - **STALE** — Verify context carefully before proceeding107 - **VERY_STALE** — Consider creating a fresh handoff first108109### Step 6: memory_persistence [depends_on: complete_and_validate]110Persist the validated handoff to both local markdown and Arbora:111- Markdown local fallback: file is stored in `.agent/handoffs/` following the naming convention `YYYY-MM-DD-HHMMSS-[slug].md`.112- Knowledge Graph global memory store:113 - Invoke `kg_memory_store` MCP tool with `memory_type` set to `episodic`.114 - Pass the full content of the handoff document, and include tags like `handoff`, `session`, and the `[slug]`.115 - This ensures the dual-write strategy: the Markdown file acts as a local fallback, while the KG serves as the global memory store.116- For long-running projects, chain handoffs together to maintain context lineage:117 `handoff-1.md` (initial work) -> `handoff-2.md --continues-from handoff-1.md` -> `handoff-3.md --continues-from handoff-2.md`.118119### Step 7: begin_execution [depends_on: verify_staleness_context]120Load the verified context and begin working on the immediate next steps list:121- Follow `references/resume-checklist.md`:122 1. Verify project directory and git branch match123 2. Check if blockers from the handoff have been resolved124 3. Validate assumptions still hold (run a quick `git status`)125 4. Review modified files for conflicts126 5. Check environment state (services running, env vars set)127- Start with **Immediate Next Steps** item #1 from the handoff document. Reference:128 - "Critical Files" section for important file locations129 - "Key Patterns Discovered" for conventions to follow130 - "Potential Gotchas" to avoid known issues131- As you work: mark completed items in "Pending Work", add new discoveries to relevant sections, and for long sessions create a new handoff with `--continues-from` to chain them.132133---134135## Storage Location136137Handoffs are stored in: `.agent/handoffs/`138139Naming convention: `YYYY-MM-DD-HHMMSS-[slug].md`140141Example: `2024-01-15-143022-implementing-auth.md`142143---144145## Scripts146147| Script | Purpose |148|--------|---------|149| `scripts/create_handoff.py [slug] [--continues-from <file>]` | Generate new handoff with smart scaffolding |150| `scripts/list_handoffs.py [path]` | List available handoffs in a project |151| `scripts/validate_handoff.py <file>` | Check completeness, quality, and security |152| `scripts/check_staleness.py <file>` | Assess if handoff context is still current |153154## References155156- `references/handoff-template.md` — Complete template structure with guidance157- `references/resume-checklist.md` — Verification checklist for resuming agents