@cyanheads/mcp-ts-core 0.9.10 → 0.9.12

package/skills/multi-server-orchestration/references/maintenance-pass.md

@@ -1,148 +0,0 @@
----
-name: maintenance-pass
-description: >
-  Multi-server-orchestration reference for maintenance passes. Drives parallel `bun update --latest`, changelog investigation (via the changelog skill), framework adoption per the maintenance skill's auto-adopt rule, skill/script sync (Phase A/B/C), and verification across N existing MCP server projects. Optional Bash-git wrap-up fanout commits adoptions after user authorization.
-metadata:
-  author: cyanheads
-  version: "1.2"
-  audience: internal
-  type: reference
----
-
-# Maintenance Pass — Multi-Server Orchestration
-
-Use after reading `../SKILL.md`. This reference handles parallel `bun update` + changelog investigation + framework adoption + verification across N existing MCP server projects.
-
-## When applicable
-
-- One or more existing servers built on `@cyanheads/mcp-ts-core` need a coordinated maintenance pass
-- N = 1 still benefits — the value is the fresh-context sub-agent running the full `maintenance` skill end-to-end without context pollution
-- Each target must have a clean working tree (uncommitted work blocks the maintenance skill's verification gate)
-
-## Pre-flight (orchestrator)
-
-Before spawning any sub-agents:
-
-1. **Confirm the target list** with the user. Capture absolute paths.
-2. **Verify each target is a git repo with a clean working tree.** Run `git status` per target. Halt if any is dirty — user fixes locally and re-invokes.
-3. **Verify each target has `scripts/list-skills.ts` and the `list-skills` package script.** Both ship via `init`; older projects pick them up on the next `maintenance` Phase C sync — which is what's about to run. If missing at this moment, that's fine; note it and the sub-agent will pick them up.
-4. **Verify each target has the `maintenance` skill available** (in `skills/` or `.claude/skills/`). If missing, that's a sign the project hasn't been initialized from a recent framework version — flag it; the sub-agent can still work from the package's copy at `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`.
-5. **Check `publish-mcp` script presence** when `server.json` exists. If missing, flag it — the maintenance sub-agent or a follow-up agent should add it.
-6. **Check `manifest.json` existence.** If missing and the project has `server.json`, flag it — the maintenance sub-agent should scaffold it from `templates/manifest.json` during framework adoption (Step 6).
-7. **Clarify the user authorization scope.** Do they want sub-agents to commit/push at the end, or stop at "changes applied, working tree dirty, awaiting review"? Default is the latter.
-
-## Phase pattern
-
-| # | Phase | Mode | Inputs | Outputs |
-|:--|:------|:-----|:-------|:--------|
-| 1 | Pre-flight | orchestrator | Target list + auth scope | Verified clean working trees, list-skills/maintenance availability noted |
-| 2 | Maintenance fanout | fanout | `maintenance` skill | Per-target: green devcheck, working tree with framework/dep adoptions, Step 8 numbered summary |
-| 3 | Roll-up | orchestrator | Phase 2 summaries | Consolidated cross-target report presented to user |
-| 4 | (Optional) Wrap-up | fanout, Bash git only | Phase 2 outputs | Per-target commit + push, after user authorizes |
-
-Phase 4 is optional — if the user wants to review changes locally first or split adoption decisions across multiple sessions, the orchestration ends at Phase 3 with dirty working trees.
-
-## Phase details
-
-### Phase 2: Maintenance fanout
-
-One sub-agent per target. Each agent runs the `maintenance` skill end-to-end in **Mode A** (full flow from `bun outdated` through verification).
-
-**Orient block substitution.** For maintenance, the parent SKILL.md's orient step 6 ("read spec artifacts") has no applicable artifact — the maintenance skill itself is the spec, already covered by step 5. When constructing the per-target prompt, replace step 6 with "N/A for maintenance" so the sub-agent doesn't hunt for a non-existent `docs/design.md`.
-
-**Task body (after the orient block):**
-
-> Read `skills/maintenance/SKILL.md` (or `.claude/skills/maintenance/SKILL.md`, whichever exists). Run it end-to-end in Mode A:
->
-> 1. `bun outdated` — capture the list
-> 2. `bun update --latest` — apply, capturing the `↑ package old → new` lines for Step 3
-> 3. Invoke the `changelog` skill for each updated package
-> 4. If `@cyanheads/mcp-ts-core` updated, do the deeper framework review from Step 4 of the maintenance skill
-> 5. Run Step 5 skill/script sync (Phase A: package → project `skills/`; Phase B: project `skills/` → agent dirs; Phase C: package scripts + pristine refs → project)
-> 6. Adopt changes per Step 6 — **framework changes are auto-adopt every applicable site in this pass** (the maintenance skill's Step 6 defines "applicable site" — follow its guidance; don't infer scope from this summary), no scope/effort/marginal-benefit deferrals; third-party libs are cost/benefit
-> 7. `bun run rebuild` → `bun run devcheck` → `bun run test`
-> 8. Produce the Step 8 numbered summary (Updated packages, Breaking changes handled, Features adopted, Skills synced, New/changed skills available, Open decisions, Status)
->
-> Constraints:
-> - **No write git commands** — no `commit`, `push`, `tag`, `branch`, `merge`, `rebase`, `cherry-pick`, `add`, `reset`, `restore`, `checkout --`, `clean`, `stash`. Leave the working tree dirty for orchestrator review.
-> - Read-only git is allowed and expected — `status`, `diff`, `log`, `show`, `blame`. The maintenance skill's Step 5 Phase A explicitly requires `git diff skills/` after sync to surface adoption signal; do that.
-> - NEVER `git stash` for any reason. NEVER `git reset --hard`, `git restore .`, `git clean -f`, or `git checkout -- .` — these violate the global protocol.
-> - Halt and report if `bun run devcheck` can't be made green after adoption. `bun audit` failures from devcheck are note-not-halt if the advisory is in a transitive dep with no available patch — surface it in the Step 8 summary under Open decisions. `bun run test` is skip-not-halt: if the project has no `test` script in `package.json`, note it and continue.
-> - Output the Step 8 summary verbatim at the end of your run — the orchestrator parses it.
->
-> If the `maintenance` skill's own version increased in Phase A of the skill sync (skill-version paradox), re-read the synced `skills/maintenance/SKILL.md` and continue from Step 5 onward with the new version.
-
-**Expected sub-agent output:** the Step 8 numbered summary plus a `bun run devcheck` / `bun run test` final pass.
-
-### Phase 3: Roll-up (orchestrator)
-
-The orchestrator collects each sub-agent's Step 8 summary and produces a consolidated cross-target report for the user:
-
-1. **Per-target headlines** — short table: target → N packages updated → green/red devcheck → status
-2. **Cross-target patterns** — features adopted across multiple targets, third-party libs updated everywhere, breaking changes that hit a subset
-3. **Open decisions** — any per-target ambiguities flagged. Group by decision so the user can rule once across multiple targets when the choice is the same
-4. **Outliers** — targets where the working-tree diff is unusually large, or where adoption couldn't complete cleanly
-
-Wait for user direction before Phase 4 — they may want to inspect diffs locally first.
-
-### Phase 3.5: Double-check / normalization pass (recommended)
-
-Independent maintenance agents diverge on incidental choices and miss adoption sites under context pressure. A lightweight follow-up fanout catches gaps before wrap-up:
-
-- **Adoption gaps** — features the updated skills say to do that weren't applied (error code semantic audit, missing scaffolding files like `manifest.json`/`.mcpbignore`, `publish-mcp` script)
-- **Audience compliance** — only skills with `metadata.audience: external` should be in project `skills/`; agents sometimes sync `internal`-audience skills
-- **Content accuracy** — `isRequired` flags in `server.json` match the upstream API's actual requirement; `manifest.json` `name` doesn't include the npm scope prefix; `user_config` entries have required `title` and `type` fields
-- **Cross-target consistency** — if a feature shows up in 3 of 5 Step 8 summaries, the other 2 likely missed it
-
-Phase 3.5 agents operate under the same no-write-git constraint as Phase 2 agents — leave fixes in the working tree for Phase 4.
-
-These agents should **fix, not just report** — analysis-only agents create unnecessary follow-up. After fixing, re-run `bun run rebuild && bun run devcheck && bun run test`.
-
-Use a lighter model (e.g. Sonnet) for this pass — it's verification and targeted fixes, not deep adoption work.
-
-### Phase 4: Wrap-up fanout (optional, Bash git only)
-
-Run only after explicit user authorization. Per-target commit decisions are driven by the change shape:
-
-- **Pure third-party dependency update** — `chore(deps): update dependencies` (or per-package if the diff is concentrated)
-- **Framework upgrade with adoption changes** — `chore(framework): mcp-ts-core <old> → <new>, adopt <pattern>`
-- **Mixed** — split into atomic commits per the global git rules ("Related changes ship together; unrelated changes split"). Example: `package.json` + `bun.lock` + adoption code ship together in the framework adoption commit; unrelated third-party-only deps ship in a separate `chore(deps)` commit
-
-One sub-agent per target. Each agent:
-
-1. Re-confirms the working tree still reflects Phase 2's changes (no manual reverts since)
-2. Stages and commits in atomic units per the global protocol — version bumps ride with the change that warrants them; do not manufacture extra ceremonial commits
-3. Pushes to origin
-
-If the maintenance pass should drive a version bump (breaking framework upgrade, or follow-on release intent), see the `release-and-publish` skill — the orchestrator may chain a release scenario as a separate run.
-
-## Orchestrator-driven updates
-
-If the orchestrator runs `bun update --latest` centrally before spawning sub-agents (e.g. to batch the network I/O or to run changelog investigation itself), pass the resolved version deltas (`package old → new`) into each sub-agent's prompt. This lets the agent skip re-discovery and jump straight to changelog review / framework adoption with concrete versions in hand.
-
-## Gotchas specific to maintenance
-
-| # | Gotcha | Mitigation |
-|:--|:-------|:-----------|
-| 1 | Aggressive auto-adoption — the `maintenance` skill mandates "every applicable framework site, in this pass" with no scope/effort deferrals | Expected and correct. Diffs per target may be large; surface size in the roll-up so the user can prioritize review |
-| 2 | Skill-version paradox — if `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md` version is newer than the synced project copy, feature-adoption rows added in the new version don't surface | Sub-agent prompt restates the paradox: after Phase A sync completes, re-read the synced `maintenance` SKILL.md and continue from Step 5 |
-| 3 | Per-target adoption divergence is expected — projects on different starting framework versions adopt different things | Don't try to normalize. Surface divergence as informational in the roll-up; the user may run a separate orchestration to bring stragglers forward |
-| 4 | The `changelog` skill may not exist in a target's skill directory yet | Sub-agent falls back to direct `node_modules/<pkg>/CHANGELOG.md` reading, as documented in the maintenance skill's Step 3 |
-| 5 | Sub-agent runs write git commands despite instruction (commit/push/reset/stash/etc.) | Restate the no-write-git list + the no-`stash` rule in the prompt body; verify via `git log --oneline -1` per target after Phase 2 — should show no new commits since pre-flight |
-| 6 | Targets at the same framework version produce inconsistent adoption choices | Usually means one agent missed a site; spot-check the Step 8 "Features adopted" lists across targets. If a feature shows up for 3 of 4, the 4th likely missed it — spawn a narrow finish-pass agent for that target |
-| 7 | Big monorepo or many adoptions cause context exhaustion in a sub-agent | Narrow the prompt: if a target has many breaking framework changes, split the sub-agent's work into "update deps + verify" and "adopt features" as two phases against that target |
-| 8 | Agent syncs `internal`-audience skills into project `skills/` | Restate in the prompt: "Only sync skills with `metadata.audience: external`." The maintenance skill's Phase A step 2 says this, but agents miss it under context pressure |
-| 9 | `manifest.json` scaffolded with scoped name from `package.json` (e.g. `@cyanheads/bls-mcp-server`) — renders in the mcpb install dialog | Double-check pass should verify `manifest.json` `name` doesn't contain `/`; the `polish-docs-meta` skill's cross-file consistency section covers this |
-| 10 | `manifest.json` `user_config` entries missing required `title`/`type` fields — `mcpb pack` fails at release time | Agents scaffold from memory, not the template. Double-check pass should verify all `user_config` entries have `title` and `type` |
-
-## Checklist
-
-- [ ] Pre-flight: target list confirmed, clean working trees verified, `list-skills` presence noted per target, `maintenance` skill availability noted per target, `publish-mcp` and `manifest.json` presence noted, auth scope clarified with user
-- [ ] Phase 2: maintenance fanout spawned; each sub-agent returned a Step 8 summary
-- [ ] Phase 2 integrity: `git log --oneline -1` per target confirms no new commits written by sub-agents
-- [ ] All targets: green `bun run devcheck` and `bun run test` post-adoption
-- [ ] Phase 3: consolidated roll-up presented to user with per-target headlines, cross-target patterns, open decisions, outliers
-- [ ] Phase 3.5: double-check pass completed; adoption gaps fixed, audience compliance verified, `manifest.json` name/`user_config` validated; devcheck + test green per target after fixes
-- [ ] **User authorization captured for wrap-up if proceeding to Phase 4**
-- [ ] Phase 4: per-target commits via Bash git, pushed to origin
-- [ ] Final read-only verification: `git log --oneline -3` and `git ls-remote` per target — commits landed, no stray uncommitted work

package/skills/multi-server-orchestration/references/release-and-publish-pass.md

@@ -1,184 +0,0 @@
----
-name: release-and-publish-pass
-description: >
-  Multi-server-orchestration reference for release-and-publish passes — the end-to-end ship workflow combining wrap-up (version bump, changelog, commit, annotated tag) and publish (push + npm + MCP Registry + GHCR) across N MCP server projects. Drives parallel verification → README polish → wrap-up (Bash git, local only — distilled from `git_wrapup_instructions`) → publish (via the standalone `release-and-publish` skill per target) → optional GH issue closure. Phase 5 runs serial when npm 2FA prompts interactively; parallel when bypass is configured. Disambiguated from the single-target `release-and-publish` skill it invokes per target.
-metadata:
-  author: cyanheads
-  version: "1.3"
-  audience: internal
-  type: reference
----
-
-# Release-and-Publish Pass — Multi-Server Orchestration
-
-Use after reading `../SKILL.md`. This reference handles end-to-end ship work across N MCP server projects — verification gate → README polish → wrap-up (version bump, changelog, commit, annotated tag — Bash git, local) → publish (push + npm + MCP Registry + GHCR via the standalone `release-and-publish` skill) → optional GH issue closure.
-
-> **Disambiguation.** This orchestration reference invokes the standalone `release-and-publish` skill once per target in Phase 5 — the skill is the single-target publish workflow; this reference is the multi-target fanout around it (plus pre-publish phases). Don't conflate them: the skill ships one server; this reference orchestrates shipping N.
-
-## When applicable
-
-- One or more MCP servers built on `@cyanheads/mcp-ts-core` have committed/staged work that needs to ship as a new version
-- Common follow-on to a `maintenance-pass` run where adopted changes need to ship as a patch
-- Works for any version bump scope (patch / minor / major), per target
-
-This reference assumes the change to ship is already done — it's the "ship the work" phase, not the "do the work" phase. If targets still need code changes, run those phases first (greenfield build, maintenance, etc.).
-
-## Pre-flight (orchestrator)
-
-Before spawning any sub-agents:
-
-1. **Confirm the target list with the user.** Capture absolute paths and the intended version bump per target (`patch` / `minor` / `major`, or an explicit version string). Mixed bumps across targets are fine.
-2. **Confirm the change shape per target.** What changed since the last release? This drives the conventional-commit subject, the per-version changelog body, and the annotated tag message. For a patch bump with a single concern, one or two lines per target is enough.
-3. **Confirm npm 2FA setup.** Parallel `bun publish` calls don't play nicely with interactive 2FA — OTP prompts from multiple sub-agents interleave and fail. Either:
-   - **Bypass configured** — granular access token with "Bypass 2FA for publish" in `~/.npmrc` → Phase 5 can run as a parallel fanout
-   - **Not configured** — Phase 5 runs serially, orchestrator-driven, target by target
-   - **No npm publish involved** — non-issue
-4. **Capture the GH issue map (optional).** Per target: any issue numbers that this release closes or comments on, plus the intent (close vs. comment-only). Skip if no issues apply.
-5. **Surface the plan and get explicit authorization.** Scenario, target list, version bump per target, 2FA mode for Phase 5, issue map, gotchas in play. Phase 5 is irreversible — no implicit authorization.
-
-## Single-target vs. multi-target
-
-A typical single-target release-and-publish flow runs in one session: `git_set_working_dir` + `git_wrapup_instructions` from `git-mcp-server` drive the wrap-up phase, then the standalone `release-and-publish` skill drives the publish phase. This reference translates that into the multi-target parallel pattern:
-
-| Single-target (orchestrator session) | Multi-target (parallel sub-agents) |
-|:-------------------------------------|:-----------------------------------|
-| `git_set_working_dir` once | Each sub-agent uses absolute paths with Bash `git` (no session state) |
-| `git_wrapup_instructions` returns playbook + diagnostics | Phase 4 sub-agent prompt enumerates the same steps directly |
-| Orchestrator executes steps in one session | One sub-agent per target executes steps in parallel |
-| `release-and-publish` runs in the same session | Phase 5 sub-agents run the skill end-to-end per target |
-
-The orchestrator may still call `git_wrapup_instructions` *serially* against each target during pre-flight to inspect state — that's read-only, no state leak. The constraint is on parallel sub-agents.
-
-## Phase pattern
-
-| # | Phase | Mode | Inputs | Outputs |
-|:--|:------|:-----|:-------|:--------|
-| 1 | Pre-flight | orchestrator | Target list, bump intent, 2FA mode, issue map | Verified plan, user authorization |
-| 2 | Verification fanout | fanout | Existing target state | Per-target: green `bun run devcheck` + `bun run test:all` (or `test`) |
-| 3 | README review fanout | fanout | Current README + change shape | Per-target: README updates folded in (no commits) |
-| 4 | Wrap-up fanout | fanout, Bash git only | Phase 3 outputs + version bump intent | Per-target: version bumped everywhere, per-version changelog authored, rollup regenerated, commit + annotated tag — **LOCAL ONLY, no push** |
-| 5 | Release publish | fanout OR serial | Phase 4 outputs | Per-target: tags+commits pushed, npm publish, MCP Registry publish, Docker push — via `release-and-publish` |
-| 6 | (Optional) Issue closure fanout | fanout | Phase 5 outputs + issue map | Per-target: relevant GH issues commented and closed |
-
-## Phase details
-
-### Phase 2: Verification fanout
-
-One sub-agent per target. Quick verification gate before any version bump or wrapup.
-
-**Task body (after the orient block):**
-
-> Run `bun run devcheck`. Then run `bun run test:all` if it exists in `package.json` scripts, otherwise `bun run test`. Both must pass green. Halt and report the failing step's verbatim output if anything fails — do not attempt fixes from inside this phase. If neither `test:all` nor `test` exists in `package.json` scripts, note it and continue — devcheck-only is acceptable (though uncommon for a project shipping a release).
-
-Any red target halts the orchestration for that target. The user fixes locally and re-invokes Phase 2 for the failing target(s) only — other targets that passed don't need to re-run.
-
-### Phase 3: README review fanout
-
-One sub-agent per target reads the full README plus key adjacent docs, identifies stale or missing content (feature counts, version badges, surface tables, configuration sections, dep version mentions), and folds updates in. No commits — Phase 4 stages everything together.
-
-**Task body:**
-
-> Read `README.md` from front to back. Identify content stale relative to the current code: tool/resource counts, version badges, feature lists, configuration tables, version mentions in install snippets. Fold updates in naturally — don't rewrite sections that are already accurate. Do NOT commit. Leave changes in the working tree for the next phase.
->
-> If `polish-docs-meta` skill is available (`skills/polish-docs-meta/SKILL.md`) and the change spans more than just the README (e.g., new env vars, new tools), invoke that skill instead — it handles README plus `server.json`, `package.json`, agent protocol, and `.env.example` in one pass.
->
-> If the README is already accurate, report "no changes needed" and exit cleanly.
-
-For a small patch bump, this phase is often a no-op. That's fine.
-
-### Phase 4: Wrap-up fanout (Bash git only)
-
-Runs on the authorization captured in Pre-flight Step 5 — no separate authorization needed for wrap-up.
-
-One sub-agent per target. The agent reads and executes the standalone `git-wrapup` skill (`skills/git-wrapup/SKILL.md`) — the skill contains the complete protocol for version bump, changelog, verification, commit, and annotated tag.
-
-**Task body:**
-
-> Read and follow the `git-wrapup` skill — check `skills/git-wrapup/SKILL.md` first; fall back to `.claude/skills/git-wrapup/SKILL.md` if not found. Apply a `[patch/minor/major]` version bump.
->
-> Additional constraints for orchestrated runs:
-> - **Bash `git` only.** Do not use `git-mcp-server` (`mcp__git-mcp-server__*`) tools — session state leaks across parallel agents in the same orchestrator session.
-> - **Do NOT push.** Phase 5 handles the push as part of `release-and-publish`.
-> - If `v<version>` already exists as a tag, **halt and surface the conflict** to the orchestrator. Do NOT `git tag -d` without authorization.
->
-> Output for the orchestrator: commit SHA, tag name, tag annotation subject.
-
-After this fanout, each target has a clean working tree with the wrap-up commit + annotated tag locally; nothing has been pushed.
-
-### Phase 5: Release publish
-
-Run only after user authorizes the publish. **This phase is irreversible.**
-
-Each target invokes the `release-and-publish` skill end-to-end. Execution mode depends on the npm 2FA setup confirmed in pre-flight:
-
-| Mode | When | How |
-|:-----|:-----|:----|
-| **Parallel fanout** | npm 2FA bypass configured, OR no npm publish involved | One sub-agent per target runs `release-and-publish` end-to-end |
-| **Serial (orchestrator-driven)** | npm 2FA prompts OTP interactively | Orchestrator invokes `release-and-publish` against each target one at a time; may use `git-mcp-server` tools in this serial mode |
-
-**Parallel mode task body:**
-
-> Read `skills/release-and-publish/SKILL.md` (or `.claude/skills/release-and-publish/SKILL.md`). Run it end-to-end:
->
-> 1. Sanity-check wrapup outputs (working tree clean, HEAD tagged `v<version>` from Phase 4). If either check fails, halt and report to the orchestrator — do not re-run Phase 4 from inside Phase 5
-> 2. Verification gate: `bun run devcheck`, `bun run rebuild`, `bun run test:all` (or `test`)
-> 3. Push commits and tags to origin via Bash git
-> 4. `bun publish --access public` (npm — uses the configured bypass token)
-> 5. `bun run publish-mcp` if `server.json` exists (MCP Registry)
-> 6. `bun run bundle` + `gh release create v<version> --verify-tag --notes-from-tag <dist/*.mcpb>` if `manifest.json` exists (MCPB GitHub Release). Must run from inside the repo dir — `--notes-from-tag` is incompatible with `--repo`.
-> 7. `docker buildx build --platform linux/amd64,linux/arm64 --push ...` if `Dockerfile` exists (GHCR)
-> 8. Report deployed artifact URLs (npm, MCP Registry, GitHub Release, GHCR)
->
-> Honor the skill's retry/halt protocol — transient network errors retry up to 2× with backoff; idempotent-success signals ("version already exists", "cannot publish duplicate version") are treated as success and proceed. Bash git for all git ops. Never skip the verification gate.
-
-**Serial mode:** the orchestrator spawns one sub-agent at a time per target — each runs `release-and-publish` end-to-end, completing before the next target starts. This prevents OTP prompt interleaving.
-
-After Phase 5, collect per-target status: which destinations succeeded, which (if any) halted with partial state. The user re-invokes Phase 5 for any failed targets only — completed destinations hit the idempotent-success signal and skip naturally.
-
-### Phase 6: Issue closure fanout (optional)
-
-Only run if pre-flight captured a GH issue map. One sub-agent per target with the per-target issue list.
-
-**Task body:**
-
-> For each issue in `[per-target issue list]`:
->
-> 1. `gh issue view <number> --comments` to read the full thread (body + all comments)
-> 2. Compose a closing comment naming what shipped (version `v<version>` and a one-line summary of the fix or feature)
-> 3. `gh issue comment <number> -b "<comment>"` then `gh issue close <number>` — unless the thread suggests the fix is partial or the issue scope has expanded, in which case comment but do NOT close, and flag back to the orchestrator
->
-> Constraints: read the full thread before commenting — `gh issue view` alone shows only the thread, not the body; for combined view use `gh api repos/<owner>/<repo>/issues/<number>`. No marketing adjectives. Be concise and accurate.
-
-Skip Phase 6 for any target whose Phase 5 didn't complete — there's nothing to close if the release didn't ship.
-
-## Gotchas specific to release-and-publish pass
-
-| # | Gotcha | Mitigation |
-|:--|:-------|:-----------|
-| 1 | npm 2FA OTP prompts interleave under parallel publish, breaking all in-flight publishes | Confirm bypass setup in pre-flight; fall back to serial mode for Phase 5 if not configured |
-| 2 | Phase 4 sub-agent pushes prematurely | Restate "Do NOT push" in the Phase 4 prompt verbatim; Phase 5 owns the push as part of `release-and-publish`'s flow |
-| 3 | Version bump skipped a file (`server.json`'s per-package entries, README badge, Dockerfile OCI labels) | Phase 4 prompt enumerates every version-bearing file; the `grep -rn "<current-version>"` step catches stragglers |
-| 4 | Sub-agent reports "tag already exists" — a Phase 4 retry race, or a left-over tag from a failed prior run | Inspect with `git tag -l "v<version>"` and `git show v<version>` before re-running; never `git tag -d` without user authorization |
-| 5 | Two targets derive the same version from a shared assumption | Phase 4 prompt always derives version from each target's CURRENT `package.json`, not from a value the orchestrator assumed |
-| 6 | `release-and-publish` halts mid-flow for one target (network blip on docker push) | The skill's retry protocol handles transient errors; non-transient halts produce a partial-state report. Collect per-target status; user re-invokes for failed targets only |
-| 7 | Phase 6 sub-agent picks the wrong issues by guessing from commit messages | Pre-flight captures the explicit issue map per target; sub-agent works from that list, doesn't discover issues itself |
-| 8 | Annotated tag message bloats into a CHANGELOG copy | Restate the rule in Phase 4 prompt: terse release theme + notable changes + dep arrows in `pkg ^old → ^new` form. Length is earned |
-| 9 | Sub-agent uses `git-mcp-server` instead of Bash git in Phase 4 or 5 | Hard Rule 1 restated explicitly in every fanout prompt that touches git |
-| 10 | Failed publish leaves a tag pushed but no npm package — looks shipped, isn't | Collect per-destination status per target in Phase 5 roll-up; surface partial-state targets explicitly to the user before Phase 6 |
-| 11 | `gh release create --notes-from-tag` fails with `--repo` flag | `gh` CLI limitation. Always `cd` into the target repo dir for `gh release` commands instead of using `--repo` |
-| 12 | Post-version doc changes (install badges, description fixes) land after the version commit — tag points at stale content | Move the tag forward: delete remote release, delete remote+local tag, recreate tag at new HEAD with same annotation, re-push, recreate release with `.mcpb`. This requires explicit user confirmation before executing — ask at runtime |
-| 13 | `mcpb pack` fails because `manifest.json` `user_config` entries are missing `title`/`type` fields | Verify `manifest.json` `user_config` entries during Phase 3 or a pre-Phase-5 check; the `polish-docs-meta` skill's cross-file consistency section covers this |
-
-## Checklist
-
-- [ ] Pre-flight: target list confirmed, version bump intent per target, npm 2FA mode confirmed (bypass / serial / N/A), GH issue map captured (or empty), plan surfaced to user
-- [ ] **User authorization captured for the release-and-publish**
-- [ ] Phase 2: verification fanout — green `bun run devcheck` + tests per target
-- [ ] Phase 3: README review fanout — updates folded, no commits
-- [ ] Phase 4: wrap-up fanout (Bash git only) — version bumped, changelog authored, rollup regenerated, commit + annotated tag per target — **NOT pushed**
-- [ ] Working tree clean per target; `git show v<version>` succeeds per target
-- [ ] Version-bearing files consistent across `package.json`, `server.json`, README badge, and `Dockerfile` OCI labels per target — no doc changes pending after the tag
-- [ ] Phase 5: release publish — completed per target via `release-and-publish` (parallel or serial based on 2FA mode); per-target status captured
-- [ ] All targets: deployed artifact URLs reported (npm / MCP Registry / GHCR as applicable)
-- [ ] **If GH issue map captured:** Phase 6: issue closure fanout — relevant issues commented and closed per target whose Phase 5 succeeded
-- [ ] Final read-only verification: `git ls-remote --tags origin` shows the new tag per target, versions match across files, npm/registry show the new version, GH issue status matches intent

package/skills/multi-server-orchestration/references/wrapup-pass.md

@@ -1,150 +0,0 @@
----
-name: wrapup-pass
-description: >
-  Multi-server-orchestration reference for git wrap-up passes — distilled from `git-mcp-server`'s `git_wrapup_instructions` protocol. Drives parallel verification → optional doc review → wrap-up (version bump, changelog, commit, annotated tag — Bash git, local only, no push) → roll-up across N MCP server projects. Stops at "committed and tagged locally". No push, no publish — those are separate, separately-authorized workflows.
-metadata:
-  author: cyanheads
-  version: "1.2"
-  audience: internal
-  type: reference
----
-
-# Wrap-up Pass — Multi-Server Orchestration
-
-Use after reading `../SKILL.md`. This reference distills the `git_wrapup_instructions` protocol into a multi-target fanout: per target, verify → polish docs → bump version + author changelog + commit + annotated tag, **all local**. No push, no publish, no remote ops.
-
-## When applicable
-
-- One or more MCP servers have committed/uncommitted work to land as a new local commit + annotated tag — for review, or to hold locally pending a separately-authorized publish step
-- Common follow-on to a `maintenance-pass` run where adopted changes are worth shipping
-- Common precursor to a `release-and-publish-pass` run when wrap-up and publish are split across sessions (e.g., wrap-up tonight, publish tomorrow after a final review)
-
-This reference assumes the change to land is done — it's the "land it as a commit + tag" phase, not the "do the work" phase.
-
-If publish follows immediately in the same session, prefer `release-and-publish-pass.md` end-to-end; it embeds wrap-up as its Phase 4. This reference exists for sessions that stop at "tagged locally" deliberately.
-
-## The wrap-up protocol — acceptance criteria
-
-Distilled from `git_wrapup_instructions`. **Strict on goals, generic on mechanism.** Every sub-agent treats these as the acceptance checklist for "done":
-
-1. **Full diff reviewed end-to-end** before commits are planned
-2. **Version bumped per semver** (default patch; minor/major when warranted) across every place version is declared
-3. **Changelog updated** under the new version in the project's existing format
-4. **Documentation current** for any referenced behavior changes
-5. **Verification suite passes** against the tree being committed
-6. **Commits atomic and in Conventional Commits form** — version bumps ride with the change that warrants them
-7. **Annotated tag** at the project's convention (`v<version>`) with a concise message — no filler
-
-Universal constraints from the protocol: do not push, do not bypass verification failures, do not rewrite published history.
-
-For `@cyanheads/mcp-ts-core` consumers, the mechanism is concrete (below). External projects substitute their own conventions while preserving the seven acceptance goals.
-
-## Pre-flight (orchestrator)
-
-Before spawning any sub-agents:
-
-1. **Confirm the target list with the user.** Capture absolute paths and the intended version bump per target (`patch` / `minor` / `major`, or an explicit version string). Mixed bumps across targets are fine.
-2. **Confirm the change shape per target.** What changed since the last release? This drives the conventional-commit subject, the per-version changelog body, and the annotated tag message. One or two lines per target is enough for a focused patch.
-3. **Verify each target's working tree state.** Run `git status` and `git log v<latest-tag>..HEAD --oneline` per target to confirm there's actually work worth wrapping. A target with no commits since its last tag and a clean working tree has nothing to wrap.
-4. **Surface the plan and get explicit authorization.** Scenario, target list, version bump per target, gotchas in play. The wrap-up itself is reversible (no push), but tag conflicts surface fast and are easier to head off in pre-flight.
-
-## Phase pattern
-
-| # | Phase | Mode | Inputs | Outputs |
-|:--|:------|:-----|:-------|:--------|
-| 1 | Pre-flight | orchestrator | Target list, bump intent, change shape | Verified plan, user authorization |
-| 2 | Verification fanout | fanout | Existing target state | Per-target: green `bun run devcheck` + `bun run test:all` (or `test`) |
-| 3 | Doc review fanout (optional) | fanout | Current README + adjacent docs + change shape | Per-target: doc updates folded in, no commits |
-| 4 | Wrap-up fanout | fanout, Bash git only | Phase 3 outputs + version bump intent | Per-target: version bumped, changelog authored, rollup regenerated, commit + annotated tag — **LOCAL ONLY, no push** |
-| 5 | Roll-up | orchestrator | Phase 4 outputs | Per-target verification of commit + tag; consolidated report to user |
-
-Phase 3 is optional — skip when the change is small enough that the README/docs are already accurate. For a maintenance-driven patch with no user-facing behavior change, it's often a no-op.
-
-## Phase details
-
-> **Orient block:** the standard preamble instructing sub-agents to read `~/.claude/CLAUDE.md`, workspace `CLAUDE.md`, project `CLAUDE.md`, and run `bun run list-skills` — defined in `../SKILL.md`. Every sub-agent prompt starts with this block before the task body.
-
-### Phase 2: Verification fanout
-
-One sub-agent per target. Quick verification gate before any version bump or wrap-up.
-
-**Task body (after the orient block):**
-
-> Run `bun run devcheck`. Then run `bun run test:all` if it exists in `package.json` scripts, otherwise `bun run test`. Both must pass green. Halt and report the failing step's verbatim output if anything fails — do not attempt fixes from inside this phase. If neither `test:all` nor `test` exists in `package.json` scripts, note it and continue — devcheck-only is acceptable (though uncommon for a project shipping a release).
-
-Any red target halts the orchestration. The user fixes locally and re-invokes from Phase 2.
-
-### Phase 3: Doc review fanout (optional)
-
-One sub-agent per target reads the README plus adjacent docs, identifies stale content relative to the current code, and folds updates in. No commits — Phase 4 stages everything together.
-
-**Task body:**
-
-> Read `README.md` from front to back. Identify content stale relative to the current code: tool/resource counts, version badges, feature lists, configuration tables, version mentions in install snippets. Fold updates in naturally — don't rewrite sections that are already accurate. Do NOT commit. Leave changes in the working tree for the next phase.
->
-> If `polish-docs-meta` skill is available (`skills/polish-docs-meta/SKILL.md`) and the change spans more than just the README (e.g., new env vars, new tools), invoke that skill instead — it handles README plus `server.json`, `package.json`, agent protocol, and `.env.example` in one pass.
->
-> If the README is already accurate, report "no changes needed" and exit cleanly.
-
-For a small patch, this phase is often a no-op. Skip Phase 3 when the diff introduces no new tools, resources, env vars, or behavior changes visible to the user.
-
-### Phase 4: Wrap-up fanout (Bash git only)
-
-Runs on the authorization captured in Pre-flight Step 4 — no separate authorization needed for wrap-up.
-
-One sub-agent per target. The agent reads and executes the standalone `git-wrapup` skill (`skills/git-wrapup/SKILL.md`) — the skill contains the complete protocol for version bump, changelog, verification, commit, and annotated tag.
-
-**Task body:**
-
-> Read and follow the `git-wrapup` skill — check `skills/git-wrapup/SKILL.md` first; fall back to `.claude/skills/git-wrapup/SKILL.md` if not found. Apply a `[patch/minor/major]` version bump.
->
-> Additional constraints for orchestrated runs:
-> - **Bash `git` only.** Do not use `git-mcp-server` (`mcp__git-mcp-server__*`) tools — session state leaks across parallel agents in the same orchestrator session.
-> - If `v<version>` already exists as a tag, **halt and surface the conflict** to the orchestrator. Do NOT `git tag -d` without authorization.
->
-> Output for the orchestrator: commit SHA, tag name, tag annotation subject.
-
-### Phase 5: Roll-up (orchestrator)
-
-The orchestrator verifies per-target via read-only Bash git:
-
-```bash
-for d in <target paths>; do
-  echo "=== $d ==="
-  (cd "$d" && git log --oneline -1 && git tag --points-at HEAD && git status --short)
-done
-```
-
-Spot-check commit and tag quality: `git log --format='%s%n%b' -1` for marketing adjectives in commit messages, `git show v<version>` for tag annotation structure.
-
-Then produces a consolidated report:
-
-1. **Per-target headline** — target → new version → tag annotation subject → commit SHA
-2. **Outliers** — targets that halted (verification red, tag conflict, missed version files surfaced during the run)
-3. **Endpoint.** Wrap-up stops here. Anything further — pushing, publishing, closing issues — requires a separate explicit user instruction in a new invocation; the orchestrator does NOT advance from a wrap-up pass on its own.
-
-## Gotchas specific to wrap-up
-
-| # | Gotcha | Mitigation |
-|:--|:-------|:-----------|
-| 1 | Sub-agent pushes prematurely despite "local only" instruction | Restate "Do NOT push" in the Phase 4 prompt verbatim; verify post-fanout that `git log @{u}..HEAD` shows the wrap-up commit (i.e., still ahead of origin) |
-| 2 | Version bump skipped a file (`server.json`'s per-package entries, README badge, Dockerfile OCI labels, `manifest.json`) | Phase 4 prompt enumerates every version-bearing file; the `grep -rn "<current-version>"` step catches stragglers |
-| 3 | Tag at `v<version>` already exists (leftover from failed prior run, or two orchestrator runs against the same target) | Sub-agent halts and surfaces conflict; never `git tag -d` without orchestrator authorization. Inspect with `git tag -l "v<version>"` and `git show v<version>` |
-| 4 | Annotated tag message bloats into a CHANGELOG copy, or collapses into a flat comma-separated string | Phase 4 prompt has explicit structured format: subject, prose intro, sectioned bullets, dep arrows, test footer. Both extremes (too long, too flat) are format violations |
-| 5 | Marketing adjectives slip into commit/tag messages | Restate the no-marketing rule in the prompt body; orchestrator spot-checks during Phase 5 (`git log --format='%s%n%b' -1`, `git show v<version>`) |
-| 6 | Sub-agent uses `git-mcp-server` instead of Bash git | Phase 4 prompt restates Hard Rule 1 from parent SKILL.md; session-state leak across parallel agents is real |
-| 7 | Verification gate skipped because "the change is small" | Restate "Halt if not green — do NOT bypass" in the prompt; the wrap-up protocol forbids bypass and the orchestrator confirms green status in Phase 5 |
-| 8 | Two targets derive the same target version from a shared assumption | Phase 4 prompt always derives version from each target's CURRENT `package.json`, not from a value the orchestrator assumed |
-| 9 | Sub-agent commits in multiple atomic chunks when the work is one cohesive concern | Restate the rule: "Version bumps ride with the change that warrants them — for a focused patch, ONE commit." Multi-commit splits are for genuinely independent concerns, not ceremonial separation of "the work" from "the release" |
-
-## Checklist
-
-- [ ] Pre-flight: target list confirmed, version bump intent per target, change shape per target, user authorization captured
-- [ ] Phase 2: verification fanout — green `bun run devcheck` + tests per target
-- [ ] Phase 3 (if applicable): doc review fanout — README/docs updates folded in, no commits
-- [ ] Phase 4: wrap-up fanout (Bash git only) — every acceptance criterion satisfied per target; commit + annotated tag — **NOT pushed**
-- [ ] Working tree clean per target after Phase 4
-- [ ] Tags exist locally; nothing pushed to remotes
-- [ ] Phase 5: orchestrator verification — `git log --oneline -1`, `git tag --points-at HEAD`, `git status --short` per target
-- [ ] Consolidated report presented to user with per-target headlines, outliers, next steps
-- [ ] Orchestrator has NOT advanced to push, publish, or any remote operation — wrap-up is complete