@cyanheads/mcp-ts-core 0.9.10 → 0.9.11

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

@@ -1,246 +0,0 @@
----
-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.1"
-  audience: internal
-  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."
-- "No write `git` commands: no `commit`, `push`, `add`, `tag`, `reset`, `restore`, `checkout --`, `clean`, `stash`. Read-only git is allowed — `status`, `diff`, `log` are useful for tracking your own changes."
-- "NEVER `git stash` for any reason. NEVER `git reset --hard`, `git restore .`, `git clean -f`, or `git checkout -- .` — these violate the global protocol."
-- "Do NOT run `field-test`. That's reserved for the user's manual verification later."
-- Orient block — non-negotiable (see `../SKILL.md` for the template).
-
-**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. One sub-agent per target reads and executes the standalone `git-wrapup` skill (`skills/git-wrapup/SKILL.md`). All git calls use Bash, not git-mcp-server. After the local wrap-up, the agent pushes commits and tags to origin.
-
-Version bumps live with the change that warrants them per the global protocol's git rules — don't manufacture extra commits.
-
-## Recommended additional phases
-
-The 13-phase pattern above covers scaffold-to-ship. Experience from multi-server pipeline runs surfaces additional phases that earn their cost. Orchestrators building a prescriptive pipeline layer on top of this reference should consider inserting these:
-
-**Design gate (after Phase 3).** A third agent per target reads ONLY `docs/design.md` (no idea.md, no skill) and gives a pass/fail verdict. The point is cold-read validation: does the design make sense on its own? Filter out noise — only flag genuine structural issues, not style preferences. If all pass, proceed to build. If any fail, spawn focused fix agents.
-
-**Test quality review (after Phase 11/12).** Dedicated agents that audit test coverage and quality: are all tools tested? Are error paths exercised? Are edge cases covered? Build agents write tests as a secondary concern; dedicated test agents treat it as primary.
-
-**Field test (after test quality review).** Run the `field-test` skill per target — exercise tools with real inputs, report issues. May be blocked by API key requirements or rate limits. If blocked, note it and skip. If field tests surface issues, spawn fix agents and re-field-test.
-
-**Pre-launch sweep (before final wrap-up).** Singular-purpose verification agents per target:
-1. **Metadata sync** — descriptions aligned across package.json, manifest.json, server.json (100-char condensed), README header, GH repo description. Keywords/topics include baseline MCP terms. Versions consistent.
-2. **README accuracy** — README matches current code (tool names, parameter lists, examples, config table, feature list).
-3. **PII/secrets sweep** — no hardcoded credentials, API keys, personal emails, internal paths, or sensitive context in tracked files.
-4. **Error code semantic audit** — InvalidParams only for malformed JSON-RPC params shape; ValidationError for domain validation; NotFound for missing entities.
-
-These agents fix, not just report. Re-run devcheck + test after each.
-
-## 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 |
-| 8 | LICENSE file missing from scaffolded projects despite package.json declaring Apache-2.0 | Copy from `node_modules/@cyanheads/mcp-ts-core/LICENSE` during scaffold phase (run `bun install` first if `node_modules` isn't present) |
-| 9 | Description drift across surfaces — agents set descriptions independently, creating inconsistencies across package.json, manifest.json, server.json, README, and GH repo description | Pre-launch sweep phase catches this; or define the canonical description once in docs/design.md and have agents reference it |
-| 10 | `server.json` `isRequired` flags set without verifying upstream API reality | Pre-launch sweep should verify each env var's `isRequired` against actual API behavior (does it work without the key?) |
-| 11 | Build agents exhaust context and leave tests half-written — finish agents inherit the gap but don't prioritize test coverage | Dedicated test quality review phase after build/finish is the backstop |
-| 12 | Field-test agents can't run if the API requires a key the user hasn't provided | Check API key requirements before spawning field-test agents; skip with a note if blocked |
-
-## 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
-- [ ] **Recommended: design gate — cold-read pass/fail per target**
-- [ ] Phase 4 — setup + repo fanout — repos created private, working tree unstaged, no commits
-- [ ] Phase 4 — package name verified in `package.json`, `server.json`, and agent protocol per target
-- [ ] Phase 4 — LICENSE file present in each target
-- [ ] 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 10 state documented per incomplete target (tool count, error count, missing tests) for Phase 11 prompt
-- [ ] **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
-- [ ] **Recommended: test quality review — dedicated test coverage and quality audit**
-- [ ] **Recommended: field test — `field-test` skill per target (skip if API key blocker)**
-- [ ] **Recommended: pre-launch sweep — metadata sync, README accuracy, PII sweep, error code audit**
-- [ ] 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

@@ -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