Add plan2code-handoff skill for conversation handoff documents

AI Assisted

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

@@ -0,0 +1,138 @@
+---
+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.

.gitignore

@@ -11,6 +11,7 @@ plan2code-metrics/package-lock.json
 .plan2code-metrics
 nul
 .cognition/
+handoffs/
 node_modules/
 package-lock.json
 SYNC.md

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to Plan2Code will be documented in this file.
 
+## v1.16.0
+
+### ✨ Added
+
+- **`/plan2code-handoff` skill** — compacts the current conversation into a self-contained handoff document (written to gitignored `./handoffs/<timestamp>-handoff.md`) so a fresh session or another agent can resume the work
+  - Always captures a confirmed **Next task**: infers a candidate from context and requires the user to confirm or fill it in before the file is written
+  - References plan specs, logs, and files by path rather than copying them; strips secrets; suggests follow-on skills and verification steps
+  - Repo-safe: checks `git check-ignore` and warns (without silently editing `.gitignore`) when `handoffs/` isn't ignored in an arbitrary repo
+
 ## v1.15.4
 
 ### ✨ Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan2code",
-  "version": "1.15.4",
+  "version": "1.16.0",
   "private": true,
   "bin": {
     "plan2code": "./install.js"