@cyanheads/mcp-ts-core 0.9.7 → 0.9.9

package/skills/field-test/SKILL.md

@@ -19,7 +19,7 @@ Unit tests (`add-test` skill) verify handler logic with mocked context. Field te
 
 This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. The same handlers run on both transports — only the framing differs — so HTTP exercises the full functional surface.
 
-**Stdio coverage is a boot check only.** Run `bun run rebuild && bun run start:stdio`, confirm the startup logs look clean (banner, expected tool/resource counts, no errors/warnings, no missing-config gripes), then kill it. Pino logs go to stderr in stdio mode (stdout is reserved for JSON-RPC), so they print straight to the terminal when you run interactively. No need to call tools over stdio — the HTTP pass already covered handler behavior.
+**Stdio coverage is a boot check only — run this before Step 1.** Run `bun run rebuild && bun run start:stdio`, confirm the startup logs look clean (banner, expected tool/resource counts, no errors/warnings, no missing-config gripes), then kill it. Pino logs go to stderr in stdio mode (stdout is reserved for JSON-RPC), so they print straight to the terminal when you run interactively. No need to call tools over stdio — the HTTP pass already covered handler behavior.
 
 ---
 
@@ -193,7 +193,7 @@ Capture `pid`, `url`, `port`, `log` from the `mcp_start` output — every later
 
 - `MCP_HTTP_PORT` is a *starting* port — the server auto-increments if taken. Helper parses the real URL from the log (`HTTP transport listening at ...`).
 - If `bun run rebuild` fails, stop. Don't field-test broken code — fix the build first.
-- If a server is already listening on the project's port (`lsof -i :<port>`), confirm with the user before killing it; it may be their own session.
+- If a server is already listening on the project's port (`lsof -i :<port>`), confirm with the user before killing it; it may be their own session. If the user isn't available to confirm, abort the field test and surface the port conflict in your response.
 
 ### 2. Initialize the session
 
@@ -251,7 +251,7 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 | Resource declared an `errors: [...]` contract | Error contract (resource): trigger ≥1 declared failure mode by reading a URI that exercises it. Resources re-throw errors at the JSON-RPC level — verify `error.code` matches the contract entry and `error.data.reason` is the declared reason. (Resources don't use the `result.isError` envelope — they fail the request itself.) |
 | Mutator (write/update/delete/append/patch verbs, or `destructiveHint: true`) | Mutator response observability: run an intentionally-ambiguous input (typo path, wrong ID, already-deleted target). Confirm the response carries enough state (pre/post values, state-change discriminator) for the agent to detect intent-effect divergence without re-fetching. |
 
-**Resources.** Happy path, not-found URI, `list` if defined, pagination if used.
+**Resources.** Happy path, not-found URI (use a syntactically valid but non-existent ID — e.g., substitute a fake ID into the URI template), `list` if defined, pagination if used.
 **Prompts.** Happy path, defaults omitted, skim message quality.
 
 **Sampling for large servers.** If more than 15 tools, run the universal battery on all, but pick roughly 30–40% for situational testing. Weight toward: write-shaped tools, complex schemas, external deps. List which ones you skipped in the report.
@@ -285,7 +285,7 @@ mcp_stop <pid> <log>
 rm -f /tmp/<project-name>-field-test-<ID>.sh
 ```
 
-Kills the background server, removes the server log, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session.
+Kills the background server, removes the server log, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session. If `mcp_stop` warns the PID is still alive after SIGKILL, note it in the report and proceed — don't block on a zombie process.
 
 ### 7. Report
 
@@ -332,13 +332,15 @@ End with:
 
 ## Checklist
 
-- [ ] Server built and started; real port parsed from log
+- [ ] Stdio boot check completed — `bun run rebuild && bun run start:stdio` shows clean startup (banner, expected counts, no errors)
+- [ ] HTTP server built and started; real port parsed from log
 - [ ] Session initialized; `notifications/initialized` sent
 - [ ] Catalog surfaced and presented; descriptions audited for leaks (implementation details, meta-coaching, consumer-aware phrasing)
-- [ ] Universal battery run on every definition
+- [ ] Universal battery run on every definition (happy path, parity, input error)
 - [ ] Situational categories applied only when triggered
+- [ ] **If >15 tools:** sampled 30–40% for situational testing; skipped definitions listed in report
 - [ ] **If a tool declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; `result.structuredContent.error.code` and `data.reason` verified against the contract entry
 - [ ] **If a resource declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; top-level JSON-RPC `error.code` and `error.data.reason` verified against the contract entry
 - [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
-- [ ] Server stopped; state file removed
+- [ ] Server stopped; server log and helper script removed
 - [ ] Report: summary paragraph → grouped findings → numbered options

package/skills/git-wrapup/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: git-wrapup
+description: >
+  Land working-tree changes as a versioned release commit with an annotated tag — version bump, changelog, regenerate derived artifacts, verify, commit, tag. Stops at "committed and tagged locally" — no push, no publish. The release-and-publish skill picks up from here. Distilled from the git_wrapup_instructions protocol.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: workflow
+---
+
+## When to use
+
+Working-tree or staged changes are ready to ship as a new version. This skill lands them as a single atomic commit with an annotated tag. It does NOT push or publish — that's a separate step (`release-and-publish`).
+
+Common triggers:
+- Feature work, bug fixes, or dependency updates are done and tested
+- A maintenance or polish pass left changes in the working tree
+- An orchestrator says "wrapup this project"
+
+## Pre-wrapup gate checklist
+
+Every item must be true before starting wrapup. Committing means releasing — a commit only happens when the work is ready to ship, not just "the edits are done." Each item is a goal to verify.
+
+- [ ] **Changes exist** — uncommitted files or commits since the last tag
+- [ ] **Work is complete** — no half-finished features, no "I'll add the test later," no TODO placeholders. The diff represents a shippable unit.
+- [ ] **Code simplified** — if the diff spans more than ~50 changed lines or touches 3+ source files, the `code-simplifier` skill has been run across the changes
+- [ ] **`bun run devcheck` passes** — typecheck + lint clean
+- [ ] **`bun run rebuild` succeeds** — full clean build from scratch
+- [ ] **All tests pass** — `bun run test:all` (or `bun run test`). New tests and regression tests added as needed for the changes being shipped.
+- [ ] **Fixes verified** — bug fixes validated, generally via `bun run rebuild` and field-testing. Not just written — confirmed to resolve the described behavior.
+- [ ] **No known regressions** — the changes don't break existing functionality
+- [ ] **GH issues updated** — issues addressed by this work commented with what landed and any follow-ups needed. Concise. Backlinked as needed.
+- [ ] **Docs updated** — surgical updates to existing docs as needed. New docs for new features. No large rewrites for documentation that's still accurate.
+
+If any gate is red, fix it before proceeding. This skill re-verifies build + tests in step 6, but starting wrapup on a broken tree wastes the version number and creates a revert-or-amend situation.
+
+After all gates pass, spawn dedicated agents to handle the wrapup (this skill) and publish (`release-and-publish`). These are separate agents from the ones that did the editing work.
+
+## Steps
+
+### 1. Review the diff
+
+Understand what's about to ship before touching version numbers:
+
+```bash
+git status
+git log v<latest-tag>..HEAD --oneline    # commits since last release
+git diff --stat                           # uncommitted changes
+git diff                                  # review the actual content
+```
+
+If the working tree is clean AND there are no commits since the last tag, halt — nothing to wrap up.
+
+### 2. Determine the new version
+
+Read the current version from `package.json`. Apply the intended bump:
+
+| Bump | When |
+|:-----|:-----|
+| **patch** | Bug fixes, dependency updates, metadata changes, docs |
+| **minor** | New tools, new features, new env vars, behavioral changes |
+| **major** | Breaking changes to tool schemas, removed tools, incompatible config |
+
+Default to **patch** unless the diff clearly warrants minor or major.
+
+### 3. Bump version everywhere
+
+Every file that declares a version must be updated. Skip any file that doesn't exist in the project. For `@cyanheads/mcp-ts-core` projects:
+
+- `package.json` — `version`
+- `server.json` — top-level `version` AND every `packages[].version` entry
+- `manifest.json` (if present) — `version`. Verify `name` is the bare package name (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`)
+- `README.md` — version badge
+- `CLAUDE.md` / `AGENTS.md` — if they pin a version string
+- `Dockerfile` — OCI labels if they pin the version
+
+Catch stragglers (replace the placeholder with the actual current version string, e.g. `0.9.7`):
+
+```bash
+grep -rn "0.9.7" . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=changelog
+```
+
+Resolve hits case by case — historical changelog entries are correct as-is; everything else should match the new version.
+
+### 4. Author the changelog
+
+Create `changelog/<major.minor>.x/<version>.md`. Use `changelog/template.md` as the format reference — never edit, rename, or move that file.
+
+**Frontmatter (required):**
+
+```yaml
+---
+summary: "<one-line headline, ≤350 chars, no markdown>"
+breaking: false    # true if consumers must change code to upgrade
+security: false    # true if this release contains a security fix
+---
+```
+
+**Body:** Section order follows Keep a Changelog — Added / Changed / Deprecated / Removed / Fixed / Security. Include only sections with entries. Delete empty sections.
+
+**Tone:** Terse, fact-dense. Lead each bullet with the symbol or concept in **bold**. One sentence per bullet by default. See the authoring guide in `changelog/template.md` for full conventions.
+
+### 5. Regenerate derived artifacts
+
+```bash
+bun run changelog:build    # rebuilds CHANGELOG.md rollup from per-version files
+bun run tree               # regenerates docs/tree.md — run when files were added, removed, or moved in src/
+```
+
+Both scripts are idempotent — safe to run even if nothing changed.
+
+### 6. Run the verification gate
+
+The tree being committed must pass verification. Both must succeed:
+
+```bash
+bun run devcheck
+bun run test:all           # or `bun run test` if no test:all script exists
+```
+
+**If either fails, halt.** Do not bypass verification to land the commit. Fix the issue first, then re-run from step 6.
+
+### 7. Commit
+
+Stage everything and create ONE atomic commit. Version bumps ride with the change that warrants them — the version bump is not a separate commit.
+
+```bash
+git add -A
+git commit -m "<subject>"
+```
+
+**Subject format:** Conventional Commits. Examples:
+- `feat: 0.1.5 — hosted server endpoint`
+- `fix: 0.2.1 — handle empty SPARQL result sets`
+- `chore(deps): 0.3.2 — mcp-ts-core ^0.9.1 → ^0.9.6`
+
+**Rules:**
+- Plain `-m` flag only — no heredoc, no command substitution
+- No `Co-authored-by` or `Generated with` trailers
+- No marketing adjectives ("comprehensive", "robust", "enhanced", "seamless", "improved")
+- The commit message must stand alone for someone reading `git log` — no references to chat context, option numbers, or "as discussed"
+
+**When to split into multiple commits:** Only when the working tree contains genuinely independent concerns (e.g., two unrelated bug fixes in unrelated files). NEVER split a single file's changes across commits.
+
+### 8. Create an annotated tag
+
+```bash
+git tag -a v<version> -m "<tag message with embedded newlines>"
+```
+
+Use `-m` with embedded newlines in the string (the commit `-m`-only constraint applies here too — no heredoc). The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string. Format:
+
+```
+<theme — omit version number, GitHub prepends v<VERSION>:>
+
+<1-2 sentence context: what this release does>
+
+<Sections — Keep a Changelog names, only those with entries>
+
+Added:
+
+- <bullet>
+
+Changed:
+
+- <bullet>
+
+<dep arrows if applicable>
+
+Dependency bumps:
+
+- `pkg` ^old → ^new
+
+<N> tests pass; `bun run devcheck` clean.
+```
+
+**Rules:**
+- Subject line omits the version number (GitHub prepends `v<VERSION>:` to the release title)
+- Not a CHANGELOG copy — terse, scannable
+- No marketing adjectives
+- Length is earned — two-line tags are fine for small patches
+
+### 9. Verify end state
+
+```bash
+git log --oneline -1              # confirm commit subject
+git show v<version> --stat | head -20   # confirm tag points at HEAD
+git status                        # must be clean
+```
+
+If the working tree isn't clean or the tag doesn't point at HEAD, something went wrong — investigate before proceeding.
+
+**Do NOT push.** This skill stops here. Use the `release-and-publish` skill for the push + publish workflow.
+
+## Constraints
+
+- **Local only.** No `git push`, no remote operations
+- **Never stash.** Not for quick checks, not for testing, not for any reason
+- **Never destructive.** No `git reset --hard`, `git restore .`, `git clean -f`, `git checkout -- .`
+- **Bash git only** when running inside orchestrated sub-agents (git-mcp-server session state leaks across parallel agents)
+- If `v<version>` already exists as a tag, **halt and report the conflict** — include the version string, existing tag SHA, and current HEAD SHA so the caller can resolve it. Do not delete or move tags without explicit authorization
+
+## Checklist
+
+- [ ] Diff reviewed end-to-end before version bump
+- [ ] Version bumped in every declaring file (`package.json`, `server.json`, `manifest.json`, README badge, `CLAUDE.md`/`AGENTS.md` if they pin a version)
+- [ ] GH issues addressed by this work commented with what landed (if working from GH issues)
+- [ ] Docs updated for any new or changed features
+- [ ] Changelog authored at `changelog/<major.minor>.x/<version>.md`
+- [ ] `CHANGELOG.md` rollup regenerated (`bun run changelog:build`)
+- [ ] `docs/tree.md` regenerated if structure changed (`bun run tree`)
+- [ ] `bun run devcheck` passes
+- [ ] `bun run test:all` (or `test`) passes
+- [ ] One atomic commit in Conventional Commits format
+- [ ] Annotated tag `v<version>` with structured markdown message
+- [ ] Working tree clean
+- [ ] Nothing pushed — local only

package/skills/maintenance/SKILL.md

@@ -48,11 +48,11 @@ Capture the `↑ package old → new` lines from stdout — these feed Step 3. A
 
 Invoke the **`changelog`** skill with the captured list of updated packages. It resolves each repo, fetches release notes (or CHANGELOG entries) between old and new versions, and cross-references changes against actual imports in `src/`. Output per package: what changed, impact on this project, action items.
 
-Do not redo this investigation inline — the `changelog` skill handles tag-format detection, monorepo patterns, and fallbacks.
+Do not redo this investigation inline — the `changelog` skill handles tag-format detection, monorepo patterns, and fallbacks. If the skill cannot resolve a package (private repo, no tags, no CHANGELOG), note it in Step 8 under "Open decisions" and proceed.
 
 ### 4. Framework review (`@cyanheads/mcp-ts-core`)
 
-**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`'s `version` exceeds the one running, run Step 5 Phase A first and re-invoke `maintenance` — otherwise feature-adoption rows added in the new version silently don't surface.
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`'s `version` exceeds the one running, run Step 5 Phase A first and re-invoke `maintenance` — otherwise feature-adoption rows added in the new version silently don't surface. After Phase A, confirm the running skill version matches the package before continuing. If the session still has the old skill loaded, exit and restart.
 
 If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. The framework ships a **directory-based changelog** grouped by minor series (`.x` semver-wildcard convention) — one file per released version at `node_modules/@cyanheads/mcp-ts-core/changelog/<major.minor>.x/<version>.md`. Read only the files between old and new rather than scanning a monolithic file.
 
@@ -84,7 +84,7 @@ Cross-reference each finding against the server's code. Collect adoption opportu
 
 **Template review.** The framework also ships `templates/CLAUDE.md` and `templates/AGENTS.md` as scaffolding for consumer agent protocol files. The consumer's `CLAUDE.md`/`AGENTS.md` was copied at init time and has since diverged (local customizations, echo replacements, server-specific sections). Read the upstream template fresh at `node_modules/@cyanheads/mcp-ts-core/templates/CLAUDE.md`.
 
-Read the upstream template end-to-end, mentally comparing against the current `CLAUDE.md`/`AGENTS.md`. Apply framework-authored updates directly — new skill references in the skills table, new entries in the "What's Next?" section, updated convention callouts, clarified patterns. These are factual updates, not taste decisions; the consumer's agent protocol file is meant to track the framework's. Only surface a decision when a template change conflicts with a section the consumer has intentionally customized (server-specific domain context, bespoke checklists, etc.) — in that case, note the conflict and ask.
+Read the upstream template end-to-end, mentally comparing against the current `CLAUDE.md`/`AGENTS.md`. Apply framework-authored updates directly — new skill references in the skills table, new entries in the "What's Next?" section, updated convention callouts, clarified patterns. These are factual updates, not taste decisions; the consumer's agent protocol file is meant to track the framework's. Only surface a decision when a template change conflicts with a section the consumer has intentionally customized — a section is "intentionally customized" when it contains server-specific domain context, bespoke checklists, or content that doesn't originate from the template. In that case, note the conflict and ask.
 
 ### 5. Sync project skills and scripts
 
@@ -205,7 +205,7 @@ bun run test
 
 `rebuild` (clean + build) catches API surface and type-alignment issues that `devcheck` alone may miss — module resolution, path aliases, post-build processing. `devcheck` includes `bun audit` and `bun outdated`, so no separate audit step is needed.
 
-In **Mode B**, the user already ran rebuild + test before invoking this skill, but run them again here — Step 6 made code changes that need verification.
+In **Mode B**, the user already ran rebuild + test before invoking this skill, but run them again here — Step 6 made code changes that need re-verification.
 
 Fix anything that fails. Re-run until clean.
 
@@ -226,13 +226,15 @@ Present a concise numbered summary to the user:
 ## Checklist
 
 - [ ] Update applied (`bun update --latest`) — Mode A, or already done by user — Mode B
+- [ ] Skill-version paradox checked — if package maintenance skill version > running version, Phase A run first and skill re-invoked
 - [ ] `changelog` skill invoked for each updated package
 - [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
-- [ ] Every applicable framework adoption opportunity applied in this pass — no scope/effort/marginal-benefit deferrals; third-party adoptions evaluated on cost/benefit
+- [ ] Framework `CLAUDE.md`/`AGENTS.md` template reviewed; applicable updates applied or conflicts surfaced
+- [ ] Step 6 complete — all applicable framework adoption sites updated; third-party adoption decisions recorded
 - [ ] Project `skills/` synced from package (Phase A), with a change report
 - [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
 - [ ] Framework `scripts/` and pristine reference files resynced from package via content-hash compare (Phase C), with a change report; diffs reviewed before committing
-- [ ] `bun run rebuild` succeeds
+- [ ] `bun run rebuild` succeeds (re-run after Step 6, even in Mode B)
 - [ ] `bun run devcheck` passes (includes audit + outdated)
 - [ ] `bun run test` passes
 - [ ] Numbered summary presented to user

package/skills/migrate-mcp-ts-template/SKILL.md

@@ -20,7 +20,7 @@ For the full exports catalog, see `CLAUDE.md` → Exports Reference.
 ## Steps
 
 1. **Install the package**: `bun add @cyanheads/mcp-ts-core`
-2. **Search for all `@/` imports** across `src/` that reference framework internals
+2. **Search for all `@/` imports** across `src/` that reference framework internals: `grep -rn "from '@/" src/`
 3. **Rewrite each import** using the mapping table below
 4. **Identify framework source files** now provided by the package (see candidates below) — review each for server-specific additions before cleaning up
 5. **Update entry point** (`src/index.ts`) to use `createApp()` from the package and the project's chosen registration pattern (fresh scaffold default: direct imports in `src/index.ts`)
@@ -52,9 +52,9 @@ These are the actual `@/` import paths used in framework source. Rewrite any tha
 
 | Old `@/` import | New package import |
 |:----------------|:-------------------|
-| `@/mcp-server/tools/utils/toolDefinition.js` | `@cyanheads/mcp-ts-core/tools` or `@cyanheads/mcp-ts-core` (for `tool()` builder) |
-| `@/mcp-server/resources/utils/resourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` or `@cyanheads/mcp-ts-core` (for `resource()` builder) |
-| `@/mcp-server/prompts/utils/promptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` or `@cyanheads/mcp-ts-core` (for `prompt()` builder) |
+| `@/mcp-server/tools/utils/toolDefinition.js` | `@cyanheads/mcp-ts-core/tools` (types only: `ToolDefinition`, `AnyToolDefinition`) or `@cyanheads/mcp-ts-core` (for the `tool()` builder) |
+| `@/mcp-server/resources/utils/resourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` (types only: `ResourceDefinition`, `AnyResourceDefinition`) or `@cyanheads/mcp-ts-core` (for the `resource()` builder) |
+| `@/mcp-server/prompts/utils/promptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` (types only: `PromptDefinition`) or `@cyanheads/mcp-ts-core` (for the `prompt()` builder) |
 | `@/mcp-server/tasks/utils/taskToolDefinition.js` | `@cyanheads/mcp-ts-core/tasks` |
 
 ### Utils
@@ -90,7 +90,9 @@ After rewriting imports, these directories and files are candidates for cleanup
 
 **Preserve:** server-specific code under `mcp-server/tools/definitions/`, `mcp-server/resources/definitions/`, `mcp-server/prompts/definitions/`, the server's own `services/`, and `config/server-config.ts`.
 
-Framework directories (typically safe to clean up in full — verify no server-specific files were added):
+A file is server-specific if it doesn't appear in the `mcp-ts-template` repo at its path. Modified framework files should be extracted to a server-specific location (e.g., `src/utils/my-project/`) before deletion.
+
+Framework directories (typically safe to remove in full — verify no server-specific files were added):
 
 - `src/core/` (app, context, worker)
 - `src/cli/`
@@ -113,7 +115,7 @@ Framework files within directories that contain server code:
 
 ## Entry point rewrite
 
-Replace the fork's `src/index.ts` with the scaffold-default direct-registration pattern:
+Rewrite the `createApp()` call and its surrounding imports to use the package. Preserve the project's existing barrel structure and registration pattern if present:
 
 ```ts
 #!/usr/bin/env node
@@ -153,6 +155,8 @@ If the migrated project already has `definitions/index.ts` barrels and you want
 - [ ] `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`
 - [ ] `biome.json` extends `@cyanheads/mcp-ts-core/biome`
 - [ ] `vitest.config.ts` spreads from `@cyanheads/mcp-ts-core/vitest.config`
-- [ ] Framework source files cleaned up from `src/`
+- [ ] Framework-only directories removed (`src/core/`, `src/cli/`, `src/types-global/`, `src/storage/`, `src/utils/`, `src/testing/`, framework service subdirs)
+- [ ] Framework files within mixed directories removed (`server.ts`, `transports/`, `roots/`, tasks infra, `*/utils/` dirs, `*-registration.ts` files)
+- [ ] `vitest.config.ts` includes `@/` alias: `resolve: { alias: { '@/': new URL('./src/', import.meta.url).pathname } }`
 - [ ] Server-specific `@/` imports (own tools, services) still work
 - [ ] `bun run devcheck` passes

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

@@ -28,11 +28,11 @@ Read this SKILL.md end-to-end first — the concepts, orient block, and hard rul
    |:----------------|:---------------------------|
    | **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 |
+   | **Wrap-up / 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. If the user explicitly wants to publish to npm/registries → release-and-publish pass; if local-only → wrap-up pass |
    | **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.
+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. Non-destructive phases (read, analyze, write files, devcheck) proceed without additional check-ins after the initial plan approval.
 
 ## References
 
@@ -40,8 +40,8 @@ Read this SKILL.md end-to-end first — the concepts, orient block, and hard rul
 |:---------|:----------|:-----|
 | **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 |
+| **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**. Sub-agents execute the standalone `git-wrapup` skill per target |
+| **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 → publish → optional GH issue closure. Sub-agents execute the standalone `git-wrapup` then `release-and-publish` skills 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.
 
@@ -122,4 +122,16 @@ These commonly bite across all scenarios. Scenario-specific gotchas live in thei
 
 ## 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.
+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 references (e.g., `greenfield-buildout.md`): 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.
+
+## Pre-flight Checklist
+
+Applies to all scenarios — verify before picking a reference and kicking off the first fanout.
+
+- [ ] Target list captured with absolute paths and per-target metadata
+- [ ] Scenario identified from intent + state; confirmed with user if ambiguous
+- [ ] Reference selected from the table above
+- [ ] `scripts/list-skills.ts` + `list-skills` package script present in each target
+- [ ] Plan surfaced to user: scenario, targets, phase summary, active gotchas
+- [ ] User authorization captured for any phase that commits, tags, pushes, or creates remote resources
+- [ ] Scenario reference read in full before first fanout

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

@@ -147,7 +147,7 @@ The big one. One sub-agent per target builds the full implementation from `docs/
 - "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.
+- 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.
 
@@ -175,7 +175,7 @@ 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.
+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.
 
@@ -208,7 +208,7 @@ These agents fix, not just report. Re-run devcheck + test after each.
 | 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 |
+| 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 |
@@ -227,12 +227,15 @@ The orchestrator's checklist for a full N-target greenfield build:
 - [ ] 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**

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

@@ -59,7 +59,7 @@ One sub-agent per target. Each agent runs the `maintenance` skill end-to-end in
 > 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
+> 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)
 >
@@ -67,7 +67,7 @@ One sub-agent per target. Each agent runs the `maintenance` skill end-to-end in
 > - **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.
+> - 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.
@@ -94,6 +94,8 @@ Independent maintenance agents diverge on incidental choices and miss adoption s
 - **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.
@@ -104,7 +106,7 @@ Run only after explicit user authorization. Per-target commit decisions are driv
 
 - **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")
+- **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:
 
@@ -114,6 +116,10 @@ One sub-agent per target. Each agent:
 
 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 |
@@ -133,8 +139,10 @@ If the maintenance pass should drive a version bump (breaking framework upgrade,
 
 - [ ] 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