| name | mpi-handoff |
| description | MPI workflow pack - Hand the work to a fresh session in under two minutes. Commits and pushes the session's files, writes a handoff JSON from the running notes already in the active plan, and prints a paste-ready resume block. Use when the user says "handoff", "hand off", "create a handoff", "new session", "start fresh", "context is big", "I'm running out of context", "switch sessions", "$mpi-handoff", or "/mpi-handoff", and when one plan phase just ended with more phases pending. This is NOT close-out - when the work is finished, use mpi-end-session instead. |
mpi-handoff Skill
Save the thread and get out of the way. The session continues in a fresh
window within a minute or two, so nothing here re-derives what is already
written down.
Budget: under two minutes, under ~20k tokens. If this skill is taking
longer than a commit and a file write, something in it has grown that should
not have. That is the whole reason it exists apart from mpi-end-session.
What this deliberately does NOT do
None of these run here. They belong to mpi-end-session, which runs once when
the work is actually finished, not once per session switch:
- rule/doc impact pass over changed files
- project-knowledge drift check
- knowledge-healing replay
- memory pass
- board validation and the consolidation sweep
- the
validating card sweep
claim-auditor, or any other sub-agent
A session that hands off is not done. Preserving knowledge into docs, rules,
and memory is close-out work, and paying for it at every switch is what made
handoffs cost more than the work they interrupt. Resist the pull to be
thorough here - thoroughness has a skill, and this is not it.
The running notes are the source
The handoff body comes from the active plan's ## Current State,
## Plan Drift, and ## Preservation Notes, which mpi-continue keeps
current as each unit of work verifies. Read them, do not reconstruct them:
summarising a whole session from a large context is the most expensive thing
an agent can be asked to do, and it produces a worse answer than notes written
while the details were fresh.
Notes missing, empty, or clearly older than the work on disk? Reconstruct from
git diff --stat HEAD plus context, and say so in the report:
Note: plan running notes were stale; handoff reconstructed from context. Slower than it should be.
A silent fallback hides that the cheap path was skipped, and the habit never
gets fixed.
Process
1. Top up the running notes
Read the active plan. Update ## Current State to name where the work stands,
and ## Plan Drift if reality diverged. Add only the delta since the last
note - a few lines, not a session summary. No plan file? Skip; the handoff
JSON carries the state instead.
2. Commit and push
Running this skill IS the request to commit. Do not ask again, and do not
report "did not commit" - getting the work onto the branch is half the point
of handing off, and an uncommitted tree is invisible to the next session.
git status, then stage files by name. Never git add -A or git add ..- Commit message follows the repo's recent conventional style
(
git log --oneline -5 if unsure). Subject says why.
- Push per
push_policy in .agents/mpi-kanban/project-profile.md
frontmatter; absent means auto.
ask - one line, then push on approval. never - say the branch is
unpushed.
- Rejected push:
git fetch, git merge --ff-only, retry once. Still
failing - report it and stop. Never force, never auto-rebase a shared tree.
Worker sub-agents never commit or push, whatever the policy says.
3. Leave the card where it is
The card stays in doing. Do not move it, do not close it, do not run a
maturity sweep. The work is not finished - that is why this is a handoff.
Look the card up with findBoard() then findTask() from
${CLAUDE_PLUGIN_ROOT}/skills/mpi-lib/task-board-ops/read.md, by task ID,
linked plan path, or required attention in doing. Needed for task_card
below. No JSON board - set task_card to null and continue.
4. Write the handoff
Path: .agents/mpi-kanban/state/handoffs/<uuid>.json, creating the directory
if missing. Generate <uuid> with
python ${CLAUDE_PLUGIN_ROOT}/skills/mpi-lib/scripts/new_uuid.py, or
python -c "import uuid; print(uuid.uuid4())" if that script is missing. Same
value for the filename and the id field.
{
"schema": "mpi-kanban/handoff/v1",
"id": "<uuid>",
"generated_at": "<ISO-8601>",
"status": "open",
"session": { "name": "<what this session was doing>", "branch": "<branch>" },
"goal": {
"original": "<what the user set out to do>",
"status": "in_progress | blocked",
"summary": "<1-3 sentences on where things stand>"
},
"plan": {
"file": "<active plan path, or null>",
"completed": ["<done item>"]
Keys earlier handoffs carried but this one omits - from_session, to_role,
allowed_actions, knowledge_preservation, project_knowledge,
rules_active - stay legal to read and are simply absent. mpi-continue loads
project knowledge from disk, so restating it cost a paragraph of generation
every switch and bought nothing.
Keep context tight. Three constraints the next session would waste time
rediscovering beat fifteen it already knows.
When task_card.id exists, also write
.agents/mpi-kanban/tasks/<id>/handoffs/<uuid>.json:
{
"schema": "mpi-kanban/task-handoff-pointer/v1",
"canonical_handoff": ".agents/mpi-kanban/state/handoffs/<uuid>.json"
}
Never duplicate the handoff body into the task workspace. Add the handoff to
active_handoffs in .agents/mpi-kanban/state/index.json, update
index.updated_at, and mark any handoff this one supersedes resolved. Parse
that file as utf-8-sig - a BOM is common in the wild and plain utf-8
json.load dies on it.
5. Report
Three lines plus the block. Nothing else - anything worth more than this
belongs in the plan or the handoff, and the user is switching windows right
now.
**COMMITTED:** <subject> (<n> files) - pushed | not pushed (<policy>)
**CARD:** <MPI-* id and title> stays in doing (or "no board card")
**HANDOFF:** .agents/mpi-kanban/state/handoffs/<uuid>.json
To resume in a new session, paste this:
---
Read .agents/mpi-kanban/state/handoffs/<uuid>.json and use mpi-continue to continue from where we left off.
The next action is: <next_action.description>
---
Hard rules
- Never
git add -A or git add ..
- Never move, close, or re-mature the card. That is close-out.
- Never edit rules, docs, or memory here, even when the gap is obvious. Note it
in
context.constraints and let close-out handle it.
- Never spawn a sub-agent.
resume_prompt must stand alone - the fresh session has zero memory of this
one.- New handoffs go under
.agents/mpi-kanban/state/handoffs/. docs/handoffs/
is legacy compatibility, not canonical state.
- Never edit files under the installed plugin root.
- The user said the work is finished, not paused -> stop and route to
mpi-end-session. Handing off finished work leaves the card open forever.
Success criteria
- Files committed by name, pushed per policy.
- Handoff JSON written, indexed in
active_handoffs, pointer written when a
card exists.
- The paste block printed, self-contained.
- The card is still in
doing.
- No rule, doc, or memory file was touched.
