Release v1.16.0: install handoff skill, add publish skill, sync upstream

- Make plan2code-handoff an installed workflow prompt: move to src/,
  register in install.js SOURCE_PROMPTS, remove repo-local-only copy
- Add repo-local maintainer /plan2code-publish skill (cuts GitHub Releases;
  excluded from install.js)
- Review workflow next-step suggestion made context-aware (upstream v1.15.4)
- Doc updates: list handoff in README, QUICK-REFERENCE, architecture table;
  add "Adding a New Workflow Prompt / Skill" checklist to dev-commands
- Fix broken AGENTS.md index links: rename .agents-docs loop/metrics files
  to plan2code-* to match references
- Bump version.json to 1.16.0 to align with package.json and CHANGELOG

src/plan2code-handoff.md

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

src/plan2code-review.md

@@ -141,7 +141,7 @@ Run every finding through the false-positive detection shortcuts before presenti
 
 > **Totals:** X Critical · Y Warning · Z Suggestion
 
-**Fix options:** Reply `H` (high-priority), `A` (all), or `S 1,3,5` (specific findings).
+**Fix options:** Reply `H` to fix Critical + Warning findings, `A` to fix all findings, or `S 1,3,5` to fix specific findings.
 
 **Zero findings:** Skip table and fix options. Dimension Coverage justifies each clean dimension.
 
@@ -155,16 +155,24 @@ Run every finding through the false-positive detection shortcuts before presenti
 
 ## Session End
 
+Render this section only when the session is over: fix options resolved (fixes applied and verified, or user declined) or the review had zero findings. Step 5 ends at fix options — stop there and wait.
+
 Work summary — tell user: scope reviewed, findings count by severity (Critical/Warning/Suggestion), fixes applied, unresolved findings.
 
-After approval, select template based on project state:
+**Next step** — suggest what genuinely helps next. Principles to reason from, not a lookup table — adapt; when a case doesn't fit cleanly, say what you verified and ask.
 
-**Pre-condition check:** Before suggesting implement or finalize, verify that `overview.md` AND at least one `phase-*.md` file exist in the specs directory. If they do NOT exist, the document step has not been run yet.
-
-- **Specs dir exists but NO overview.md / phase-*.md files:** "Next: generate implementation docs. NEW conversation: `/plan2code-2-document`"
-- **Specs + overview.md + phase files + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`"
-- **Specs + overview.md + phase files + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`"
-- **Standalone:** "Review complete -- [summary]."
+- **Plan2Code Workflow Pipeline:** `/plan2code-1-plan` → `PLAN-*` files · `/plan2code-2-document` → `overview.md` + `phase-*.md` (the "spec docs") in `specs/<feature>/` · `/plan2code-3-implement` → checks off phase tasks, one phase per run · `/plan2code-4-finalize` → archives to `specs--completed/`.
+- **Find specs (any OS/shell):** `specs/` is gitignored, and search tools (Glob/Grep/project search) skip gitignored paths on many platforms — an empty search result is not evidence either way. Check with a terminal listing: `ls specs/<feature>/` (bash/zsh) · `Get-ChildItem specs/<feature>` (PowerShell) · `dir specs\<feature>` (cmd). Feature dir unknown? List `specs/` first. Command errors? Try another shell's form, then read the expected files directly — file reads see gitignored paths. Conclude "no specs" only after a terminal listing or a failed direct read.
+- **Reconcile three signals:** session context (what this conversation was doing — a fresh session may have none), user intent (what they asked reviewed), the disk check above. Disk wins on state; context wins on intent and on disk silence; no context → intent + disk decide.
+- **plan2code artifact reviewed (a plan, the spec docs, phases) — route on the reviewed feature's own `specs/<feature>/` state (another feature's specs prove nothing here), to the earliest unmet stage, suggesting only a step whose input exists:**
+  - `PLAN-*` without `overview.md` → `/plan2code-2-document`
+  - `overview.md` without `phase-*.md` → `/plan2code-2-document`
+  - Unchecked `- [ ]` tasks in `phase-*.md` → `/plan2code-3-implement` (checkboxes are ground truth; flag overview conflicts)
+  - All phase tasks checked → `/plan2code-4-finalize`
+  - Archived spec → pipeline complete; summary only
+- **Anything else** (code/PRs, logs, docs, tickets, emails, a codebase): no pipeline step — close with the summary; add a next action only if the review makes one obvious and actionable.
+- **Gates:** unresolved Criticals → fixing them (H/A/S) is the next step. Signals the rules above can't reconcile, or multiple candidate specs → ask one targeted question.
+- **Output:** "Next (NEW conversation): `/plan2code-<step>` — [why + how you know]"; otherwise "Review complete -- [summary]."
 - **Commit** (code changes): `git add [files] && git commit -m "fix: [desc]" -m "<JIRA>" -m "AI Assisted"` -- derive JIRA from branch.
 
 ```