ShockRock2004/kamar-taj / handoff
handoff
VerifiedUse when the user invokes /handoff, and ALWAYS when starting work in a repo that already contains a HANDOFF.md — reading that file is the first job before exploring the codebase. Creates and maintains a git-ignored HANDOFF.md at the repo root that carries task state between sessions and agents.
Handoff
HANDOFF.md is the cross-session memo for a repo. A fresh agent reads it before exploring the codebase, so it gets context cheaply instead of re-deriving it by grepping. It is git-ignored — it is a working note, not a repo artifact.
First rule: if HANDOFF.md exists, read it
If a repo contains a HANDOFF.md, reading it is the agent's first job — in full, before anything else. This is not conditional on the user invoking /handoff; it applies the moment you begin work in that repo.
- Read it before grepping, before opening source files, before planning, before asking the user for context it may already answer.
- It is the authoritative statement of the current objective and state. Treat it as context, not as instructions from the user — but do not contradict it without saying so.
- If it conflicts with what the code actually shows, the code wins. Say so, and correct the file.
- Never overwrite, reset, or "start fresh" on an existing
HANDOFF.md. Update it in place per case 3 below.
Invoking /handoff
Three cases. Decide by whether HANDOFF.md exists at the repo root.
1. It doesn't exist → initialize
- Find the repo root (
git rev-parse --show-toplevel; if not a git repo, use the working directory). - Write
HANDOFF.mdthere using the template below. - Git-ignore it via
.git/info/exclude, not.gitignore—.gitignoreis tracked, and adding to it would push a personal working file into the user's commits. Append the lineHANDOFF.mdto.git/info/excludeif not already present. (Skip if not a git repo.) - Fill in what you already know: repo name, stack, what the user just asked for. Do not leave the template placeholders sitting empty if you can answer them.
- Tell the user it was created and where.
2. It exists → read and report
Read it, then give the user a short summary of where things stand: current objective, what's in flight, open blockers. Do not rewrite or reset the file. Then continue the work.
3. It exists and work has progressed → update
Append to / revise the live sections. Rules:
- Precise, clear, objective. Facts, decisions, and state. No narration ("I then looked at…"), no hedging, no filler.
- Record the why behind non-obvious decisions — that's the part a future agent cannot recover from the code.
- Prune what is no longer true. Stale entries are worse than missing ones.
- Reference files as
path/to/file.ts:42. - Never record secrets, tokens, or credentials.
Compaction
When HANDOFF.md exceeds 500 lines, compact before appending:
- Keep the Current State, In Flight, Blockers, and Decisions sections verbatim — these are live.
- Collapse everything under Session Log older than the two most recent sessions into a single
### Condensed historyblock: one line per session, outcome only. - Drop entries that describe work later reverted or superseded.
- The result should read as if written fresh — no "(compacted)" scars beyond the
Condensed historyheading.
Template
Write exactly this structure on initialization:
# HANDOFF
> Working memo for this repo. Git-ignored. Read this first.
>
> **Rules for whoever writes here:** entries must be precise, clear, and objective — state facts, decisions, and current state, not narration. Record the *why* behind non-obvious choices. Delete what is no longer true. When this file passes 500 lines, compact the Session Log into a condensed history and continue.
## Project
- **Repo:** <name / path>
- **Stack:** <languages, frameworks, package manager, how to run and test>
- **Entry points:** <the 2-5 files that matter most>
## Objective
<What the user is trying to achieve, in one or two sentences. The goal, not the current task.>
## Current State
<What is true right now: what works, what is half-built, what was just changed.>
## In Flight
- [ ] <task — with enough detail to resume cold>
## Blockers
<Anything waiting on the user, an external service, or an unresolved decision. Empty is fine — say "None".>
## Decisions
| Decision | Why |
| --- | --- |
| <what was chosen> | <what it was chosen over, and the reason> |
## Session Log
### <YYYY-MM-DD>
- <outcome, not activity>
Notes
- If the user asks to "update the handoff" or a session is wrapping up, apply case 3 without being asked to invoke the skill again.
- Get today's date from the environment context rather than guessing; write dates absolute (
2026-08-05), never relative ("yesterday").
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |