@cyanheads/mcp-ts-core 0.9.1 → 0.9.2

package/skills/multi-server-orchestration/references/greenfield-buildout.md

@@ -0,0 +1,215 @@
+---
+name: greenfield-buildout
+description: >
+  Multi-server-orchestration reference for greenfield build-outs. Drives one or more freshly-scaffolded MCP servers through 13 phases: idea seed → design → critical review → setup + repo → first wrap-up (v0.1.0) → polish docs/meta → normalize → optional design extensions → interim wrap-up → build → finish → simplify → final wrap-up. Each phase is a parallel sub-agent fanout (one agent per target) with Bash git for all commit/tag/push steps.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+# Greenfield Build-Out — Multi-Server Orchestration
+
+Use after reading `../SKILL.md`. This reference handles the full lifecycle for one or more freshly-scaffolded MCP servers — from idea seed through implementation to first published release.
+
+## When applicable
+
+- One or more new servers from `bunx @cyanheads/mcp-ts-core init <name>` need to be driven through design → build → ship
+- N = 1 works too; the parallelism is optional, the phase pattern is the value
+- Each target should be a freshly-scaffolded project with no implementation yet (only the framework's echo definitions)
+
+## Pre-flight (orchestrator)
+
+Before spawning any sub-agents:
+
+1. **Confirm the target list with the user.** Capture absolute paths and the intended GitHub owner/org for each.
+2. **Name the gold-standard references** the polish phase will anchor on — concrete repos whose README, `server.json`, badges, and agent-protocol shape are the target. Name them explicitly in the relevant fanout prompts; don't let agents pick. Examples from the `@cyanheads/*` ecosystem:
+   - **Docs/README/metadata** → `pubmed-mcp-server`
+   - **Tabular API + DataCanvas/dataframe surface** → `secedgar-mcp-server`
+
+   External projects pick analogous anchors from their own ecosystem; skip the phase if no suitable anchor exists.
+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` sync (Phase C).
+4. **Confirm GH credentials** (`gh auth status`). Repo creation in Phase 4 requires this.
+5. **Surface the plan** — scenario, target list, phase summary, gotchas — and get authorization before kicking off Phase 1.
+
+## Phase pattern
+
+| # | Phase | Mode | Inputs | Outputs |
+|:--|:------|:-----|:-------|:--------|
+| 1 | Seed | orchestrator | Server idea, domain | `docs/idea.md` per target |
+| 2 | Design | fanout | `docs/idea.md` + `design-mcp-server` skill | `docs/design.md` per target |
+| 3 | Critical review | fanout | `docs/design.md` + skill | Hardened `docs/design.md` per target |
+| 4 | Setup + repo | fanout | `setup` skill + GH credentials | Private GH repo, framework scaffolds applied, working tree unstaged |
+| 5 | First wrap-up (v0.1.0) | fanout, Bash git only | Working tree from Phase 4 | Commit + annotated `v0.1.0` tag + push, after user authorizes |
+| 6 | Polish docs/meta | fanout | `polish-docs-meta` skill + named gold-standard repo | Updated README, server.json, package.json, agent protocol per target |
+| 7 | Normalize | orchestrator (or narrow fanout) | Phase 6 outputs | Consistent naming/scripts/badges across targets |
+| 8 | Design extensions (opt) | fanout | New design pattern (e.g., `api-canvas`) | Extended `docs/design.md` per applicable target |
+| 9 | Commit/push extensions | fanout, Bash git only | Phases 6–8 outputs | Commits + pushes, after user authorizes |
+| 10 | Build | fanout | `docs/design.md` | Full implementation + unit tests + green devcheck |
+| 11 | Finish (narrow scope) | fanout | Phase 10 partial state | Remaining errors fixed, missing tests written, echo removed, green devcheck |
+| 12 | Simplify | fanout | `code-simplifier` skill | Cleanups applied; green devcheck |
+| 13 | Final wrap-up (v0.1.x+1) | fanout, Bash git only | Phases 10–12 outputs | Final commit + annotated tag + push, after user authorizes |
+
+Skip phases that don't apply. Phase 8 only fires when a subset of targets fits a new design pattern. Phase 9 only runs if Phase 6–8 produced doc changes the build should start from.
+
+## Scenario-specific hard rule
+
+In addition to the universal hard rules in `../SKILL.md`:
+
+> **Repo must be private before any push** (or user must explicitly authorize public). Phase 5/9/13 sub-agents confirm `gh repo view --json visibility` returns `PRIVATE` (or have user authorization noted) before pushing.
+
+## Phase details
+
+### Phase 1: Seed (orchestrator)
+
+Write a small `docs/idea.md` per target before involving sub-agents. Structure: **Domain → Data source → User goals → Tool sketch → Pairs with → Open questions**. Keep it to a page or less — this is the seed the design skill expands.
+
+Skip if the user already has a clear, written brief per target. The point is to give the design fanout a concrete starting point so each agent doesn't redo discovery.
+
+### Phase 2: Design (fanout)
+
+One sub-agent per target. Each agent reads its `docs/idea.md`, reads `design-mcp-server`, probes the upstream API if there is one, and writes `docs/design.md`.
+
+**Decisions Log convention.** End the design doc with a "Decisions Log" section recording answered open questions and options declined, with one-line reasoning each. This becomes the audit trail for non-obvious choices and feeds Phase 3 (the reviewer can verify the rationale held up). Preserve it as a default.
+
+**Task body (after the orient block):**
+
+> Read `docs/idea.md` and the `design-mcp-server` skill. Probe the upstream API if applicable. Write `docs/design.md` following the skill's template. For open questions, default to current modern practices and record the question + your answer (or the option you declined + why) in a Decisions Log section at the bottom. Do not commit.
+
+### Phase 3: Critical review (fanout)
+
+Fresh sub-agent per target — different conversation, different context. The design author has confirmation bias on its own choices; a second agent reading cold spots what the first justified away.
+
+Each agent re-reads `docs/design.md`, re-reads `design-mcp-server`, then surgically tightens: closes gaps, kills bad assumptions, adds material that's missing. Output is an updated `docs/design.md` + a short list of what changed and why.
+
+### Phase 4: Setup + repo (fanout)
+
+One sub-agent per target. The agent reads the `setup` skill and runs it: agent-protocol file selection, framework docs read, echo cleanup, skill sync to `.claude/skills/`. Then `git init -b main`, `gh repo create` private with description and topics derived from `docs/design.md`, but **no commits**.
+
+The `setup` skill's checklist says to commit `chore: scaffold from @cyanheads/mcp-ts-core`. The orchestrator overrides this at the prompt level:
+
+> Do NOT `git add`, `git commit`, or `git push` after running the setup skill. Leave the working tree unstaged for review.
+
+### Phase 5: First wrap-up — v0.1.0 (fanout, Bash git only)
+
+Run only after the user explicitly authorizes commits.
+
+One sub-agent per target. Each agent:
+
+1. Confirms `gh repo view --json visibility` returns `PRIVATE` (or has noted authorization for public).
+2. Regenerates: `bun run tree`, authors `changelog/0.1.x/0.1.0.md` with YAML frontmatter, runs `bun run changelog:build`. Version-bumps any files that fell out of sync.
+3. Stages and commits with a conventional-commits subject (e.g., `feat: 0.1.0 — initial scaffold` or `chore(release): v0.1.0 — initial scaffold`).
+4. Creates an **annotated** tag `v0.1.0` (`-a`, not lightweight) with a terse message.
+5. Pushes commits and tags to origin.
+
+All git calls use Bash, not git-mcp-server. Final report: commit SHA + tag name.
+
+### Phase 6: Polish docs/meta (fanout)
+
+One sub-agent per target. Each agent reads:
+- Its `docs/design.md`
+- The `polish-docs-meta` skill and its references
+- The **gold-standard repo** named in pre-flight, locally
+
+The agent updates README, `server.json`, `package.json` (sponsor links, keywords, scope), Dockerfile, and the chosen agent protocol file to match the gold-standard pattern. Name the gold-standard reference explicitly in the prompt; don't let the agent pick.
+
+### Phase 7: Normalize (orchestrator or narrow fanout)
+
+After Phase 6, parallel agents will have diverged on incidental choices. Common axes:
+
+- Package name scoping (`@scope/name` vs. bare `name`)
+- Script invocation form (`bun run` vs. `bunx` vs. `tsx`)
+- Docker block in README (present vs. absent)
+- Badge set, hero title format
+- Keywords list shape
+
+Decide the canonical choice once, then either fix each project yourself (orchestrator) or spawn a narrow fanout with an explicit rule list. Orchestrator-driven is faster when the fixes are small; fanout is faster when N is large and the fix-per-target is non-trivial.
+
+### Phase 8: Design extensions (optional fanout)
+
+Some servers fit additional design patterns the base design didn't include. Example: tabular API servers (tools that page large row sets) benefit from `DataCanvas` / dataframe-surface tools — documented in `api-canvas`, exemplified by `secedgar-mcp-server`.
+
+If a subset of targets fits a pattern, spawn a fanout only for that subset. Each agent reads the relevant skill (`api-canvas`), the gold-standard reference (`secedgar-mcp-server`), and its own `docs/design.md`, then extends the design with the new pattern. This phase produces updated `docs/design.md`, not code.
+
+### Phase 9: Commit/push extensions (fanout, Bash git only)
+
+If Phases 6–8 produced doc/meta changes that should land before the build phase begins, run a small wrap-up fanout. Conventional commit, no version bump (still pre-build), Bash git only. Runs only after user authorizes.
+
+### Phase 10: Build (fanout)
+
+The big one. One sub-agent per target builds the full implementation from `docs/design.md`: services, tool definitions, resources, prompts, config, server registration, unit tests for each tool, end-to-end devcheck.
+
+**Critical prompt directives:**
+
+- "Plan carefully before acting. Think the design through end-to-end before writing files."
+- "Run `bun run devcheck` often to verify your work as you go."
+- "Do NOT use `git` commands."
+- "Do NOT run `field-test`. That's reserved for the user's manual verification later."
+- Orient block — non-negotiable.
+
+**Expect context exhaustion on the largest targets.** The agent's work persists to disk even if its session dies, but the agent itself can't continue. Plan Phase 11 as the backstop — not a fallback for failure, a normal next phase.
+
+### Phase 11: Finish — narrow-scope fanout
+
+After Phase 10, some targets will be incomplete (last few tools missing tests, lingering TS errors, echo definitions not removed, devcheck not yet green). Spawn a narrow fanout — one sub-agent per incomplete target with a concrete punch list.
+
+**Punch list format in the prompt:**
+
+> Current state: X tools implemented of Y, Z TS errors in `bun run devcheck`, echo definitions still present in `src/mcp-server/tools/definitions/echo.tool.ts`.
+>
+> Your job:
+> 1. Fix the TS errors. Run `bun run devcheck` after each fix.
+> 2. Write tests for tools A, B, C using the pattern in `tests/tools/<existing>.tool.test.ts`.
+> 3. Delete echo definitions and their registrations in `src/index.ts`.
+> 4. Confirm green `bun run devcheck` and `bun run test`.
+
+Each finish agent is narrow in scope — one or two problem classes, not a generic "finish it" prompt. Narrow scope is the antidote to context exhaustion.
+
+### Phase 12: Simplify (fanout)
+
+One sub-agent per target reads the `code-simplifier` skill, then audits the codebase against its principles: cut unnecessary abstractions, remove dead code, replace verbose patterns with idioms, etc. Output: list of changes applied + green devcheck.
+
+No commits in this phase.
+
+### Phase 13: Final wrap-up (fanout, Bash git only)
+
+Run only after the user authorizes. Same shape as Phase 5: per-target sub-agent invokes `git_wrapup_instructions` advice (via Bash git), authors `changelog/0.1.x/<version>.md`, regenerates `CHANGELOG.md` and `docs/tree.md`, version-bumps `package.json` and `server.json`, commits with a conventional subject, creates an annotated tag, pushes.
+
+Version bumps live with the change that warrants them per the global protocol's git rules — don't manufacture extra commits.
+
+## Gotchas specific to greenfield build-out
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | Zod 4 signature change — `z.record(z.string())` no longer valid; must be `z.record(z.string(), z.string())` | Caught by devcheck; mention as a hint in build-phase prompts so agents don't burn cycles rediscovering it |
+| 2 | `exactOptionalPropertyTypes` mismatch — Zod-inferred types have `T \| undefined` for optional fields, project domain types may have truly optional | Introduce a mapped widening type at the boundary where they meet; agent will hit this in devcheck |
+| 3 | `format()` ↔ `structuredContent` parity — different MCP clients forward different surfaces (Claude Code reads `structuredContent`, Claude Desktop reads `content[]`) | Build prompts cite the design-mcp-server rule; tests assert both surfaces carry equivalent data |
+| 4 | `setup` skill's checklist tells the agent to commit; orchestrator overrides this | Restate the no-commit constraint in the Phase 4 prompt body verbatim |
+| 5 | `init` defaults package name to the cwd; if the project was scaffolded inside an outer dir, the name is wrong | Verify in Phase 4 prompt: "Check the substituted package name in `package.json`, `server.json`, and the agent protocol matches the intended server name." |
+| 6 | Sub-agent creates GH repo public by default if `gh repo create` omits `--private` | Restate the scenario hard rule in every fanout that touches `gh`: "Repo must be private before any push." |
+| 7 | Wrap-up agents have been observed reporting "pushed" while the remote ref didn't actually land — the push only succeeded on a subsequent op | Verify after every Bash-git fanout: `git ls-remote --tags origin` and `gh repo view --json defaultBranchRef` per target |
+
+## Checklist
+
+The orchestrator's checklist for a full N-target greenfield build:
+
+- [ ] Target list confirmed, GitHub owners/orgs noted, gold-standard references named
+- [ ] `scripts/list-skills.ts` and the `list-skills` package script present in each target
+- [ ] `gh auth status` passes for the orchestrator session
+- [ ] **User authorization captured for commit-bearing phases**
+- [ ] Phase 1 — `docs/idea.md` authored per target
+- [ ] Phase 2 — design fanout — `docs/design.md` with Decisions Log per target
+- [ ] Phase 3 — critical review fanout — `docs/design.md` hardened per target
+- [ ] Phase 4 — setup + repo fanout — repos created private, working tree unstaged, no commits
+- [ ] Phase 5 — v0.1.0 wrap-up fanout (Bash git only) — commits + annotated tags + pushes; verified via `git log` and `git ls-remote --tags origin`
+- [ ] Phase 6 — polish docs/meta fanout against named gold-standard
+- [ ] Phase 7 — normalization — divergent conventions aligned
+- [ ] **If extension applicable:** Phase 8 — design extension fanout (e.g., DataCanvas for tabular servers)
+- [ ] **If Phases 6–8 produced doc changes the build should start from:** Phase 9 — interim wrap-up fanout (Bash git only) after user authorizes
+- [ ] Phase 10 — build fanout — implementation + tests + green devcheck per target
+- [ ] **If any Phase 10 agent didn't finish:** Phase 11 — narrow-scope finish fanout per incomplete target
+- [ ] Phase 12 — simplify fanout — `code-simplifier` pass per target
+- [ ] All targets: green `bun run devcheck` and `bun run test`
+- [ ] Phase 13 — final wrap-up fanout (Bash git only) — version bump, changelog file, regenerated rollup, commit + annotated tag + push; verified
+- [ ] Final read-only verification: tags pushed, repos still private, no stray uncommitted work

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

@@ -0,0 +1,119 @@
+---
+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.0"
+  audience: external
+  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. **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).
+
+**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**, 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:
+> - Do NOT run `git` commands. Leave the working tree dirty for orchestrator review.
+> - NEVER `git stash` for any reason. NEVER `git reset --hard`, `git restore .`, `git clean -f`, or `git checkout -- .`.
+> - Halt and report if devcheck or tests can't be made green after adoption.
+> - 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 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")
+
+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.
+
+## 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 git commands despite instruction | Restate "Do NOT run git commands" + the no-`stash` rule in the prompt body; verify via `git log --oneline -1` per target after Phase 2 |
+| 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 |
+
+## Checklist
+
+- [ ] Pre-flight: target list confirmed, clean working trees verified, `list-skills` presence noted per target, `maintenance` skill availability noted per target, auth scope clarified with user
+- [ ] Phase 2: maintenance fanout spawned; each sub-agent returned a Step 8 summary
+- [ ] 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
+- [ ] **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-pass.md

@@ -0,0 +1,189 @@
+---
+name: release-pass
+description: >
+  Multi-server-orchestration reference for release passes. Drives parallel verification → README polish → wrap-up (version bump, changelog, commit, annotated tag — local only, Bash git emulating git_wrapup_instructions) → publish (push + npm + MCP Registry + GHCR via the release-and-publish skill) → optional GH issue closure across N MCP server projects. Phase 5 runs serial when npm 2FA prompts interactively; parallel when bypass is configured.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+# Release Pass — Multi-Server Orchestration
+
+Use after reading `../SKILL.md`. This reference handles parallel release work across N MCP server projects — verification gate → README polish → git wrapup (version bump, changelog, commit, annotated tag — local only) → publish (push + npm + MCP Registry + GHCR via the `release-and-publish` skill) → optional GH issue closure.
+
+## 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 flow runs in one session via `git_set_working_dir` + `git_wrapup_instructions` from `git-mcp-server`. 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.
+
+Any red target halts the orchestration. The user fixes locally and re-invokes from Phase 2.
+
+### 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 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)
+
+Run only after user authorizes commits.
+
+One sub-agent per target. The agent executes the wrapup steps via Bash git — the same workflow `git_wrapup_instructions` walks through, but per-target absolute paths instead of session state.
+
+**Task body:**
+
+> Run the version-bump wrapup via Bash `git` (no `git-mcp-server` tools — see the orchestration skill's Hard Rule 1).
+>
+> 1. **Inspect state:** `git status`, `git log --oneline -5`, `git diff --stat` on the working tree.
+> 2. **Determine the new version:** start from the current `package.json` `version`, apply the bump intent (`[patch/minor/major or explicit string]`). For a patch, e.g., `0.1.1 → 0.1.2`.
+> 3. **Author the changelog:** create `changelog/<major.minor>.x/<version>.md` per the directory-based convention. YAML frontmatter (`summary:` required, ≤350 chars, no markdown; `breaking:` and `security:` optional, default false). Grouped sections: Added / Changed / Fixed / Removed. Use the format reference at `changelog/template.md` — never edit, rename, or move that file.
+> 4. **Regenerate:** `bun run changelog:build` (rebuilds `CHANGELOG.md` rollup) and `bun run tree` (regenerates `docs/tree.md`).
+> 5. **Bump every version-bearing file:** `package.json` `version`, `server.json` `version` at the top level AND every `packages[].version` entry, any README badge that references the version. Use `grep -rn "<current-version>"` to find any you missed; resolve case by case.
+> 6. **Stage and commit.** Conventional Commits subject. Per the global protocol: version bumps ride with the change that warrants them — for a focused patch this is one commit. Subject style: `feat: <version> — <one-line theme>` or `chore(release): v<version> — <theme>`. Plain `-m` only, no heredoc, no `Co-authored-by` or `Generated with` trailers.
+> 7. **Annotated tag** `v<version>` (`-a`, NOT lightweight): terse message with release theme, notable changes, and dep arrows in `pkg ^old → ^new` form if applicable. Not a CHANGELOG copy.
+>
+> **Do NOT push.** Phase 5 handles the push as part of `release-and-publish`'s verification gate flow.
+>
+> **Verify state at the end:**
+> ```bash
+> git log --oneline -1
+> git show v<version> --stat | head -20
+> git status   # should be clean
+> ```
+>
+> Constraints: Bash git only. NEVER `git stash`. NEVER `reset --hard` / `restore .` / `clean -f` / `checkout -- .`. No marketing adjectives ("comprehensive", "robust", "enhanced", "seamless", "improved") in commit or tag messages. Be concise and accurate.
+
+After this fanout, each target has a clean working tree with the release commit + 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)
+> 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. `docker buildx build --platform linux/amd64,linux/arm64 --push ...` if `Dockerfile` exists (GHCR)
+> 7. Report deployed artifact URLs (npm, MCP Registry, 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 runs `release-and-publish` against each target sequentially in its own session, handling OTP prompts interactively as they appear.
+
+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 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 |
+
+## 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**
+- [ ] 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
+- [ ] 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/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: workflow
 ---

package/skills/polish-docs-meta/references/package-meta.md

@@ -9,7 +9,7 @@ Fields that may still be empty or generic from scaffolding. Check each one and f
 | `name` | `{{PACKAGE_NAME}}` (substituted by init) | Verify it's correct. Use scoped name if publishing (`@org/my-server`). |
 | `version` | `0.1.0` | Keep for initial development. Bump via the `release-and-publish` skill. |
 | `mcpName` | _(often missing)_ | Reverse-domain identifier: `"io.github.{owner}/{repo}"`. Used in `server.json` `name` field and Dockerfile OCI labels. |
-| `description` | `""` (empty) | One sentence: what the server does and what it wraps. Appears on npm and in `npm search`. |
+| `description` | `""` (empty) | One **action-first** sentence — lead with the actions/workflows, end with `via MCP. STDIO or Streamable HTTP.` (or the transports that apply). Example: `"Search projects, manage tasks, track teams via MCP. STDIO or Streamable HTTP."` Avoid `"MCP server for/that …"` framings. Appears on npm and in `npm search`; the README header tagline and `server.json` `description` derive from this (server.json drops the `via MCP …` suffix). |
 | `repository` | _(often missing)_ | `{ "type": "git", "url": "git+https://github.com/org/repo.git" }` |
 | `homepage` | _(often missing)_ | Repository URL or docs URL. |
 | `bugs` | _(often missing)_ | `{ "url": "https://github.com/org/repo/issues" }` |

package/skills/polish-docs-meta/references/readme.md

@@ -9,7 +9,8 @@ Use this section order. Omit sections that don't apply (e.g., skip Docker/Worker
 ```text
 # {Server Name}                         ← centered HTML block
 [Public hosted callout if present]      ← centered HTML block, directly under badges
-Badges row                              ← npm, Docker, Version, Framework, MCP SDK, License, TS, Bun, Coverage
+Framework badge                         ← solo, spotlight row — `Built on @cyanheads/mcp-ts-core` (cyan-300 #67E8F9)
+Badges rows                             ← grouped on subsequent rows — npm, Docker, Version, MCP SDK, License, TS, Bun, Coverage
 ---
 ## Tools                                ← grouping sentence → summary table → per-tool subsections
 ## Resources and prompts (if any)       ← single combined table (Type / Name / Description)
@@ -27,21 +28,23 @@ Badges row                              ← npm, Docker, Version, Framework, MCP
 
 ### Title Block
 
-Centered HTML. The `<h1>` is the server name — use the scoped package name if published under a scope (e.g., `@cyanheads/my-mcp-server`). The `<p>` is a bold one-liner: what the server wraps, key capabilities, transport/deployment options. **Nest the surface count as a `<div>` inside the same `<p>`**, separated by `•` (U+2022 bullet) — not as a second `<p>`. This matches the shipping convention across `@cyanheads/*` servers.
+Centered HTML. The `<h1>` is the server name — use the scoped package name if published under a scope (e.g., `@cyanheads/my-mcp-server`). The `<p>` is a bold **action-first** one-liner: lead with what the server _does_, not what it _is_. List the headline actions/workflows, then end with `via MCP. STDIO or Streamable HTTP.` (or whichever transports apply). Avoid `MCP server for/that …` framings — they describe the wrapper instead of the capability. **Nest the surface count as a `<div>` inside the same `<p>`**, separated by `•` (U+2022 bullet) — not as a second `<p>`. This matches the shipping convention across `@cyanheads/*` servers.
 
 ```html
 <div align="center">
   <h1>@cyanheads/my-mcp-server</h1>
-  <p><b>MCP server for the Acme API — search projects, manage tasks, track teams. STDIO or Streamable HTTP.</b>
+  <p><b>Search projects, manage tasks, track teams via MCP. STDIO or Streamable HTTP.</b>
   <div>7 Tools • 2 Resources • 1 Prompt</div>
   </p>
 </div>
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/@cyanheads/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/my-mcp-server) [![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
+[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/my-mcp-server)
+
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/my-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
 
 </div>
 ```
@@ -52,10 +55,10 @@ The header tagline must match the `package.json` `description`.
 
 | Badge | When to include |
 |:------|:----------------|
+| Framework | Always — links to `@cyanheads/mcp-ts-core` on npm. Cyan-300 (`67E8F9`) for dark text. **Solo on its own row** as the spotlight badge. |
 | npm | Published to npm |
 | Docker | Published to ghcr.io or Docker Hub |
 | Version | Always — link to CHANGELOG.md |
-| Framework | Always — links to `@cyanheads/mcp-ts-core` on npm |
 | MCP SDK | Always — show the `@modelcontextprotocol/sdk` version |
 | License | Always |
 | TypeScript | Always |
@@ -64,7 +67,7 @@ The header tagline must match the `package.json` `description`.
 | Status | Optional — Stable, Beta, etc. |
 | Code Coverage | If coverage is tracked |
 
-Add a `---` horizontal rule after the badge block.
+**Layout:** Framework badge sits alone on the first row of the badge block — it's the brand link back to the framework and earns its own line. Group the remaining badges across one or two subsequent rows; keep related concerns together (e.g., release/license/runtime on one row, ecosystem/language on another). Add a `---` horizontal rule after the badge block.
 
 ### Public Hosted Callout (if present)