From 7e9de755f107b0d95d5064a10866e1cfe7b10a78 Mon Sep 17 00:00:00 2001 From: Justin Parker Date: Mon, 20 Jul 2026 22:07:21 -0700 Subject: [PATCH] Add plan2code-handoff skill for conversation handoff documents AI Assisted --- .claude/skills/plan2code-handoff/SKILL.md | 138 ++++++++++++++++++++++ .gitignore | 1 + CHANGELOG.md | 9 ++ package.json | 2 +- 4 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/plan2code-handoff/SKILL.md diff --git a/.claude/skills/plan2code-handoff/SKILL.md b/.claude/skills/plan2code-handoff/SKILL.md new file mode 100644 index 0000000..8116a3f --- /dev/null +++ b/.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/-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 — + + +## Next task +.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 + + +## Key files & pointers + + +## Gotchas & decisions + + +## Suggested skills + + +## Verification + +``` + +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. diff --git a/.gitignore b/.gitignore index edfe916..1396d35 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ plan2code-metrics/package-lock.json .plan2code-metrics nul .cognition/ +handoffs/ node_modules/ package-lock.json SYNC.md \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d07e1b..ded3b83 100644 --- a/CHANGELOG.md +++ b/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/-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 diff --git a/package.json b/package.json index ed35d97..2158f71 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "plan2code", - "version": "1.15.4", + "version": "1.16.0", "private": true, "bin": { "plan2code": "./install.js"