@cyanheads/mcp-ts-core 0.9.1 → 0.9.3

package/skills/multi-server-orchestration/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: multi-server-orchestration
+description: >
+  Orchestrate parallel sub-agent fanouts across one or more MCP server projects — the same workflow run independently per target. Use for greenfield builds across N new servers, maintenance passes across N existing ones, or any repeatable workflow that benefits from fresh-context per-target sub-agents. Encodes the orient template every sub-agent needs (CLAUDE.md chain + list-skills + spec artifacts), the universal hard rules around git tooling and authorization, common gotchas that bite across runs, and a router into per-scenario references for the phase pattern.
+metadata:
+  author: cyanheads
+  version: "1.1"
+  audience: internal
+  type: workflow
+---
+
+## When to Use
+
+- Same workflow driven across multiple MCP server projects in parallel — greenfield builds, maintenance updates, security audits, design extensions
+- Single server, but the work is large enough to want fresh-context sub-agents per phase rather than one continuous session
+- Any case where the per-target work is independent and benefits from devcheck-gated handoffs between phases
+
+Skip this skill for in-session tweaks to a single server — use `add-tool`, `maintenance`, `polish-docs-meta`, etc. directly.
+
+## First Pass
+
+Read this SKILL.md end-to-end first — the concepts, orient block, and hard rules below are universal across scenarios. Then:
+
+1. **Capture the target list.** N projects with absolute paths. Per-target metadata as relevant (framework version, gold-standard reference, GH owner/org). If the user named a single target, that's still N = 1.
+2. **Identify the scenario** from user intent first, then sanity-check against project state. If user intent is ambiguous, use the state heuristics below to surface a recommendation and confirm with the user — don't pick silently.
+
+   | Likely scenario | State signals (per target) |
+   |:----------------|:---------------------------|
+   | **Greenfield build-out** | Echo definitions still present in `src/mcp-server/{tools,resources,prompts}/definitions/`, no real services in `src/services/`, no released changelog files under `changelog/<minor>.x/`, `package.json` version is `0.0.0` or unset |
+   | **Maintenance pass** | Real tool/resource definitions present, framework deps installed, `bun outdated` reports updates available, at least one prior release tagged |
+   | **Release pass** | Working tree has uncommitted/staged work, OR `git log v<latest-tag>..HEAD` shows commits since the last release that warrant a new version, OR the user explicitly asks to "ship", "release", or do a version bump |
+   | **Neither** | None of the above match cleanly — surface the state to the user, ask what they want |
+
+3. **Pick the reference** from the References table below. Each reference contains its scenario's phase pattern, per-sub-agent prompt bodies, scenario-specific gotchas, and checklist.
+4. **Surface the plan to the user** before kicking off the first fanout: scenario, target list, phase summary, gotchas in play. Get explicit authorization before any phase that commits, tags, pushes, or creates remote resources.
+
+## References
+
+| Scenario | Reference | When |
+|:---------|:----------|:-----|
+| **Greenfield build-out** | `references/greenfield-buildout.md` | New server(s) from `bunx @cyanheads/mcp-ts-core init` driven through design → build → first release |
+| **Maintenance pass** | `references/maintenance-pass.md` | Existing server(s) need `bun update --latest`, changelog investigation, framework adoption, and verification — optionally followed by a commit/push |
+| **Wrap-up pass** | `references/wrapup-pass.md` | Existing server(s) with committed/staged work to land locally as a new commit + annotated tag — verification → optional doc review → wrap-up (version + changelog + commit + tag) — **local only, no push**. Distilled from `git_wrapup_instructions` |
+| **Release-and-publish pass** | `references/release-and-publish-pass.md` | Existing server(s) have committed/staged work that needs to ship as a new version end-to-end — verification → README polish → wrap-up (version + changelog + commit + tag) → publish (npm / MCP Registry / GHCR via the `release-and-publish` skill) → optional GH issue closure. Disambiguated from the standalone `release-and-publish` skill, which is the single-target publish step this reference invokes per target |
+
+**Mental model — scenarios are related but never auto-chain.** A maintenance pass often produces work worth wrapping up; a wrap-up commonly precedes a release; a greenfield build-out ends with what's effectively a release. Useful for orienting around what comes next conceptually — but **each scenario requires its own explicit user authorization to invoke**. The orchestrator never advances from one to the next on its own. Pick the reference for the current scope; if more work follows, wait for the user to direct it.
+
+For scenarios not listed (security audits, design-only extensions, framework-wide migrations), the concepts/orient/rules/gotchas below are universal. Author a new reference describing the phase pattern when the workflow becomes repeatable.
+
+## Concepts
+
+**Parallel fanout.** One phase = one parallel batch of sub-agents, one per target. All N agents run independently in the same orchestrator message. The orchestrator (you) collects their results, normalizes inconsistencies, then triggers the next phase.
+
+**Sub-agent isolation.** Sub-agents do **not** inherit the parent session's `CLAUDE.md` chain or skills registry. They start with a blank slate plus the prompt you give them. Every sub-agent prompt must begin with an explicit orient sequence (see below) or it will work from defaults and pattern-matching instead of project conventions.
+
+**Narrow scope per fanout.** A single agent doing "implement everything, write tests, run devcheck, polish, commit, tag" will exhaust its context window before finishing — the work lands on disk but the agent can't continue. Split phases narrowly so each agent finishes well under the context limit. Plan for a follow-up "finish" pass after a big work phase.
+
+**Normalize after divergent fanouts.** Independent agents will diverge on incidental choices (scoped vs. unscoped names, script invocation form, README hero structure). When the choices should be uniform across targets, plan an explicit normalization pass after the fanout — don't expect alignment for free.
+
+## The Orient Block
+
+Every parallel sub-agent prompt opens with this block. The block is **mandatory, not advisory** — the sub-agent's first six tool calls should be the orient sequence, in order. Substitute the bracketed values per target.
+
+```text
+You are working on `[project name]` at `[project absolute path]`.
+
+Orient first. These six steps are required before any task work — do them in
+order. If any file does not exist, note it and continue.
+
+1. Read the global agent protocol at `~/.claude/CLAUDE.md` (or your agent's equivalent).
+2. Read the workspace-level protocol if one exists at `[workspace CLAUDE.md path]`
+   — skip this step if no workspace-tier protocol applies.
+3. Read the project protocol at `[project absolute path]/CLAUDE.md`.
+4. Run `cd [project absolute path] && bun run list-skills` to see the project's
+   available skills with descriptions and locations.
+5. Read the skill file(s) for this task: `[skill paths]`.
+6. Read the spec artifact(s) you'll work from: `[doc paths, e.g., docs/design.md]`.
+
+Only after that, begin the task below.
+
+**Task:** [concrete description with constraints, no-go list, expected outputs]
+```
+
+The orient block compensates for the two pieces of context sub-agents don't inherit: the CLAUDE.md chain (global → workspace → project) and the project skill registry. Both must be reconstructed manually inside the sub-agent prompt or the agent works from defaults.
+
+### Prerequisite: `list-skills.ts` in each project
+
+`list-skills.ts` is the script the orient block runs in step 4. It parses YAML frontmatter from each project-local `.claude/skills/*/SKILL.md` (falling back to `skills/`) and prints a summary an agent can read. It ships with `@cyanheads/mcp-ts-core` and is scaffolded by `init` into `scripts/list-skills.ts` with a corresponding `list-skills` package script. Projects scaffolded before the script existed pick it up via `maintenance` Phase C on the next sync.
+
+Verify presence in each target before kicking off any fanout:
+
+```bash
+test -f scripts/list-skills.ts && grep -q '"list-skills"' package.json
+```
+
+## Hard Rules
+
+These apply to every scenario. Scenario-specific rules live in their reference.
+
+1. **Bash `git` only in parallel sub-agents.** Do not let parallel sub-agents call `mcp__git-mcp-server__*` tools (or any git MCP tool that holds session state across calls). The MCP server's session state (`set_working_dir`) leaks across parallel agents in the same orchestrator session, causing silent no-ops, wrong-directory operations, and false "tag already exists" errors. Bash `git` in the agent's CWD is reliable. The orchestrator may still use git-mcp-server itself in serial.
+2. **No git commits, pushes, tags, branch creation, or destructive ops without an explicit user request.** Setup-phase and build-phase work is left unstaged for review. Wrap-up phases run only after the user authorizes a commit. Honor every `~/.claude/CLAUDE.md` rule: no `git stash`, no `reset --hard`, no `restore .`, no `clean -f`, no `--no-verify`, plain `-m` commit messages, no `Co-authored-by` or `Generated with` trailers.
+3. **`bun run devcheck` is the handoff gate.** Work phases must hand back a green devcheck. If a sub-agent can't reach green, it reports the failing step verbatim and stops rather than carrying broken state forward to the next phase.
+4. **Verify sub-agent claims with a read-only check.** Agent summaries describe intent, not always reality. After any fanout that touched the filesystem, the orchestrator confirms with `git log`, `git status`, `ls`, or its own `bun run devcheck` before declaring the phase done.
+5. **Skip marketing adjectives.** In commits, tags, READMEs, and CHANGELOG entries — no "comprehensive", "robust", "enhanced", "seamless", "improved". State the change. Restate this rule in every sub-agent prompt that produces text artifacts; the global protocol's restated rules aren't visible to sub-agents at prompt time.
+6. **One scenario per orchestration run.** Don't interleave greenfield and maintenance phases against the same target in one session. If a target needs both (e.g., a build run that needs a `bun update` first), sequence them as two scenarios with a clean handoff in between.
+
+## Gotchas
+
+These commonly bite across all scenarios. Scenario-specific gotchas live in their reference.
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | Sub-agents don't inherit the CLAUDE.md chain | Orient block — global, workspace (if applicable), and project CLAUDE.md read before work |
+| 2 | Sub-agents don't inherit the project skill registry | Orient block step 4 — `bun run list-skills` surfaces available skills, agent then reads task-specific ones by path |
+| 3 | `git-mcp-server`'s `set_working_dir` state leaks across parallel sub-agents in the same orchestrator session | Bash `git` only in parallel sub-agents; reserve `git-mcp-server` for serial orchestrator use |
+| 4 | Big work agents exhaust context before finishing — work lands on disk but the agent can't continue | Narrow scope per fanout; plan a finish-pass as the backstop in the scenario reference |
+| 5 | Parallel agent self-reports describe intent, not always reality (claimed "pushed" but no remote ref exists) | Verify with read-only `git log --oneline -5`, `git ls-remote --tags origin`, `gh repo view` after every fanout that touched git |
+| 6 | Independent agents diverge on incidental conventions (scoping, scripts, README hero) | Plan an explicit normalization pass; don't expect alignment for free |
+| 7 | Sub-agent skips the orient block and proceeds with pattern-matched defaults | Put orient as a numbered prerequisite in the prompt with "Only after that, begin the task"; spot-check the first tool calls in the agent's response |
+| 8 | Sub-agent runs `git stash` to "test something safely" | Restate the global rule verbatim in every sub-agent prompt that may touch git: "NEVER `git stash` for any reason." |
+
+## Extending the pattern
+
+When a new scenario emerges that's worth codifying (security-pass fanout across N servers, framework-wide migration, etc.), author a new reference at `references/<scenario>.md` and add a row to the table above. The reference should follow the shape of the existing two: scope, pre-flight, phase table, phase details, scenario-specific gotchas, checklist. The concepts/orient/rules/gotchas in this SKILL.md don't need to be restated — the reference assumes the reader started here.

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

@@ -0,0 +1,216 @@
+---
+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.
+
+**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,122 @@
+---
+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.1"
+  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. **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**, 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 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 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 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 |
+
+## 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