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

.agents-docs/AGENTS-architecture.md

@@ -27,6 +27,8 @@ plan2code/
 │   └── local-commands/         # For per-project installation (.claude/, etc.)
 ├── .husky/                     # Git hooks (husky)
 │   └── pre-commit              # Runs character count validation
+├── .claude/                    # Repo-local Claude Code config (NOT installed by install.js)
+│   └── skills/                 # Maintainer-only dev skills, e.g. plan2code-publish/
 ├── docs/                       # Documentation and assets
 ├── specs/                      # Feature specs (if any in-progress)
 ├── install.js                  # Interactive installer (Node.js)
@@ -59,6 +61,7 @@ plan2code/
 | `plan2code-3-implement.md` | 3 | Execute implementation (phase by phase) |
 | `plan2code-review.md` | review | Post-implementation comprehensive review |
 | `plan2code-4-finalize.md` | 4 | Validate, summarize, feedback, archive (7 steps) |
+| `plan2code-handoff.md` | handoff | Compact the conversation into a self-contained handoff document |
 
 ## Naming Convention
 
@@ -84,6 +87,14 @@ Some workflows use companion reference files for depth that exceeds the 11k char
 
 Reference files are NOT subject to the 11,000 character limit. Currently only the review workflow uses this pattern — it serves as the POC for potential adoption by other workflows.
 
+## Repo-Local Skills (`.claude/skills/`)
+
+Maintainer-only Claude Code skills committed to the repo but **deliberately excluded** from `install.js` — they are dev tooling, not shipped product, so they never install to `~/.claude/skills/` and carry no version bump of their own (a product-version bump would wrongly imply a user-facing release); changelog mentions fold into the current version's entry.
+
+- `plan2code-publish/` — cuts a GitHub Release from the top `CHANGELOG.md` entry once `CHANGELOG.md` / `version.json` / `package.json` agree and the version is ahead of the latest published release. Delegates tag creation to `gh release create --target main`.
+
+**Warning:** anything named `plan2code-*` placed under `~/.claude/skills/` is deleted by the installer's uninstall (`uninstallFiles()` in `install.js`) and by every re-install's pre-copy cleanup in `install()` (both match `/^plan2code-/` for the Claude Code skills target). Keep these skills repo-local only.
+
 ## Status Line
 
 Optional Claude Code status bar living in `src/statusline-claude/`. Three-line bar (icon + content per line) showing model, project, branch, uncommitted diff stats, session duration + cost, context window usage, and plan/quota usage.

.agents-docs/AGENTS-development-commands.md

@@ -74,3 +74,29 @@ When modifying workflow prompts in `src/`:
 2. Run `node install.js` to regenerate distribution files
 3. Test the workflow in your AI tool of choice
 4. The `dist/` folder is regenerated automatically — don't edit files there directly
+
+## Adding a New Workflow Prompt / Skill
+
+Adding a new prompt to `src/` is more than dropping in a file — the installer is
+driven by an explicit registry and several docs enumerate the command set. When
+you add a `src/plan2code-<name>.md`, do **all** of the following so nothing drifts:
+
+1. **Create the source file** `src/plan2code-<name>.md` — body content **only**,
+   no YAML frontmatter (the installer generates frontmatter per platform). Keep
+   it **under 11,000 characters** (`npm test` enforces this).
+2. **Register it in the installer.** Add an entry to the `SOURCE_PROMPTS` array in
+   `install.js` (`source`, `stepNumber`, `name`, `displayName`, `description`, and
+   `isUtility: true` for non-numbered utilities). If `stepNumber` is a non-numeric
+   label (e.g. `'handoff'`), add a matching case to `generateStepLabel()` so the
+   generated description reads correctly.
+3. **Update every doc that lists the command set** — keep these in sync, they are
+   the canonical inventories:
+   - `README.md` — command table ("When to Use")
+   - `QUICK-REFERENCE.md` — Commands table
+   - `.agents-docs/AGENTS-architecture.md` — "Workflow Prompts (in `src/`)" table
+   - `CHANGELOG.md` — add an entry under the current version
+   - `docs/index.html` — **only** if the new prompt belongs to the core pipeline
+     shown there; utilities (like `init`, `quick-task`, `handoff`) are deliberately
+     omitted from that curated marketing list.
+4. **Regenerate and validate:** run `node install.js` (regenerates `dist/`) and
+   `npm test` (character-count validator now covers the new file).