plan2code/.claude/skills/plan2code-handoff/SKILL.md

---
name: plan2code-handoff
description: "Compact the current conversation into a handoff document so another agent (or a fresh session) can pick up where this one left off. Writes to ./handoffs/ in the repo. Invoke explicitly with /plan2code-handoff."
argument-hint: "(optional) focus area for the next session"
disable-model-invocation: true
---

# plan2code-handoff

Turn everything useful in the current conversation into a single, self-contained
handoff document that lets a *different* agent — a new session, a teammate's
session, or a subagent — resume the work without re-reading this transcript.

The reader of this document starts with **zero context**. They can see the repo
and can open files, but they cannot see this conversation. Write for them.

## The one hard rule: capture the next task, and confirm it with the user

Every handoff MUST end with a **Next task** that the incoming agent should start
on. This is the single most important part of the document — a handoff with a
vague or missing next step forces the reader to re-derive intent, which is
exactly what this skill exists to prevent.

Determine it like this:

1. **Try to infer it** from the conversation — the open TODO, the failing test,
   the plan step you were mid-way through, the thing the user just asked for
   next. Look at what's actually unfinished, not just the last message.
2. **Present it to the user for confirmation before writing the file.** If you
   inferred a candidate, show it and ask them to confirm or correct it. If you
   genuinely can't infer one, ask them to tell you what the next agent should do.
   Use `AskUserQuestion` (offer your inferred task as the recommended option) or
   a plain question — either is fine.
3. **Do not write the document until the user has confirmed or supplied the next
   task.** This gate is mandatory even when your inference feels obviously
   correct. The user's answer is the source of truth; your inference is only a
   draft of it.

If the user passed a focus area as an argument, treat it as a strong signal for
the next task (and shape the whole document around it), but still confirm.

## Where to write it

Save to `./handoffs/` at the repo root with a timestamped filename so it's
discoverable but doesn't collide with earlier handoffs:

```
./handoffs/<YYYY-MM-DD-HHmm>-handoff.md
```

Get the timestamp from the shell rather than guessing — e.g. PowerShell
`Get-Date -Format 'yyyy-MM-dd-HHmm'`. Create the `handoffs/` directory if it
doesn't exist.

### Make sure you aren't leaking the file into version control

The handoff is working state for the next session, not a project artifact, so it
should stay out of commits and PRs. Don't assume it will — this skill may run in
any repo. Before (or right after) writing, check whether the path is ignored:

- Is this even a git repo? `git rev-parse --is-inside-work-tree` — if it errors,
  there's nothing to ignore; skip this and just tell the user where the file is.
- Is the file ignored? `git check-ignore handoffs/` (exit 0 = ignored). This is
  the reliable check — a repo may ignore `handoffs/` via a global or nested
  `.gitignore`, so don't rely on grepping the root `.gitignore` alone.

If it is **not** ignored, do not silently modify the user's `.gitignore`. Tell
them the file would be tracked by git and offer to add a `handoffs/` line to
`.gitignore` — let them decide. Some users may want handoffs committed so
teammates get them; that's a legitimate choice, so present it, don't force it.

## What to include

Keep it tight and high-signal. Prefer pointers over prose: this repo already
records a lot (plan specs, the loop's NDJSON logs, git history, diffs), so
**reference those by path or URL instead of copying them in**. The reader can
open a file; they can't open your memory.

Use this structure:

```markdown
# Handoff — <short title of the work>
<!-- written <timestamp> -->

## Next task
<the confirmed next task — concrete and actionable, e.g.
"Implement Step 3 of specs/<name>.md: wire the aggregator into cli.ts, then
run `npm run build` in plan2code-metrics/ and fix the two failing tests.">

## Goal / why
<1–3 sentences: what the user is ultimately trying to achieve, so the reader
can make good judgment calls the instructions don't cover.>

## Current state
<Where things stand right now. What's done, what's in progress, what's broken.
Name the branch. Point at the plan/spec file(s) by path rather than restating
them. Note anything half-applied or left uncommitted.>

## Key files & pointers
<Bulleted paths the reader will need, each with a one-line "why". Include plan
specs, the files you were editing, relevant logs (e.g. .plan2code-loop NDJSON),
and any PR/issue URLs.>

## Gotchas & decisions
<Non-obvious things learned this session: a constraint (e.g. the 11k-char limit
on src/plan2code-*.md), a decision made and why, a dead end already ruled out,
a command that must be run a specific way. Save the reader from re-discovering
these the hard way.>

## Suggested skills
<Which skills the next agent should use, and when — e.g. sync-repo for syncing,
a plan2code workflow phase, /code-review before finishing. Skip if none apply.>

## Verification
<How the reader confirms their work: exact test/build commands, what "done"
looks like.>
```

Adapt the sections to the work — drop any that would be empty rather than
padding them. **Next task** is the only section that is never optional.

## Strip sensitive data

Before writing, remove credentials, API tokens, passwords, and personal
identifiers. If a secret is load-bearing for the next step, reference *where* it
lives (env var name, secret manager entry) rather than its value.

## After writing

Tell the user the path you wrote to and give a one-line summary of the confirmed
next task, so they know what the incoming agent will start on. Mention that a
fresh session can be pointed at the file to resume the work.

If your ignore check above found the file is **not** gitignored (or the repo has
no `.gitignore`, or it isn't a git repo at all), say so plainly here — e.g. "note:
`handoffs/` isn't gitignored in this repo, so this file will show up in `git
status` and could be committed" — and offer to add the ignore line. Never leave
the user unaware that the handoff might ride along into a commit.