# 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. ## Interface The FIRST thing you do, before anything else in this file — before inferring the next task: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow handoff` before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-handoff/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/handoff.md. The next-task confirmation and any clarifying questions go through it, and the finished handoff lands on the page as a doc with the download the page offers. Switchable anytime. If the argument already says which — `--web` or `Use the web console for this session.` — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then the one hard rule. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md). ## 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 No question to ask: every handoff lives in `~/.plan2code/handoffs/`, outside every repo. From the project root, let the console name the file: ``` node "/console.mjs" handoff new --workflow handoff --skill plan2code-handoff --spec specs/ --title "" ``` `` is `references/web-console/` beside this SKILL.md, as in Interface. Pass `--spec` only when the work was inside a spec; the title is a few words naming the work. It prints one JSON object: write the document to exactly its `path`, and tell the person that path. Exit 3 means it could not write there: say so and stop. The dashboard lists the handoff for this checkout until it is picked up, and old ones go after 30 days. ## If this touched a plan2code spec `specs/` is gitignored — Glob/Grep and file search silently skip it. If the conversation worked inside `specs//`, confirm the exact state before writing with `node "/specs.mjs" status specs/`, which reads the disk: - Which `phase-X.md` is in progress, and which of its tasks are still open (each phase's `tasks` and `openTasks`: checkboxes are ground truth, not the overview's Phase Checklist; a disagreement shows up in `checks`). - Cite that file and its checkbox state directly in **Current state** and **Key files & pointers**, instead of relying on conversation memory alone. - Let **Suggested skills** name the specific next pipeline command (`/plan2code-3-implement --web` to keep implementing the phase, `/plan2code-4-finalize --web` once all phases are checked) — but only as a suggestion; the confirmed **Next task** above still governs what the reader does first. No `specs/` activity this session? Skip this section entirely. ## 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.