@cyanheads/mcp-ts-core 0.9.9 → 0.9.11

package/skills/orchestrations/workflows/maintenance-release.md

@@ -0,0 +1,171 @@
+---
+name: maintenance-release
+description: >
+  Workflow: run the `maintenance` skill against one or more existing MCP server projects (dependency updates, framework adoption, skill sync), verify adoption gaps in a double-check pass, then wrap up and release via `git-wrapup` and `release-and-publish`. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+# Maintenance + Release Workflow
+
+Use after reading `../SKILL.md`. Drives maintenance, adoption verification, wrap-up, and release across N existing MCP server projects.
+
+## When applicable
+
+- One or more existing servers built on `@cyanheads/mcp-ts-core` need updates from `bun outdated` landed and shipped
+- N = 1 still benefits — fresh-context sub-agents per phase keep each focused and within context budget
+- Each target should have a clean working tree before the workflow starts — uncommitted work blocks the `maintenance` skill's verification gate
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Maintenance | `skills/maintenance/SKILL.md` |
+| Double-check | `skills/polish-docs-meta/SKILL.md` (the cross-file consistency reference is the most commonly missed surface) |
+| Wrap-up | `skills/git-wrapup/SKILL.md` |
+| Release | `skills/release-and-publish/SKILL.md` |
+
+## Pre-flight
+
+Per target:
+
+1. **Clean working tree** — `git status --short` must be empty. Halt if dirty; user fixes locally before re-invoking.
+2. **Latest tag and version** — `git describe --tags --abbrev=0`, `grep '"version"' package.json`
+3. **`list-skills` script presence** — `test -f scripts/list-skills.ts && grep -q '"list-skills"' package.json`. If missing, note it — the `maintenance` skill's Phase C will install it.
+4. **`publish-mcp` script** — when `server.json` exists, check `grep -q '"publish-mcp"' package.json`. If missing, flag it — the maintenance sub-agent adds it.
+5. **Publish destinations** — note which exist: `server.json` (MCP Registry), `manifest.json` (MCPB / GH Release), `Dockerfile` (GHCR). If `server.json` exists but `manifest.json` doesn't, flag — maintenance scaffolds it.
+6. **`npm whoami`** — required if releasing publicly.
+7. **Framework version delta** — `grep '"version"' node_modules/@cyanheads/mcp-ts-core/package.json` vs `npm view @cyanheads/mcp-ts-core version` to preview adoption scope.
+
+## Phases
+
+Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce.
+
+| # | Phase | Objective | Sub-agent mode |
+|:--|:---|:---|:---|
+| 1 | Maintenance | Per target: deps updated, framework adoption applied, project skills synced, `rebuild` + `devcheck` + `test` green, Step 8 numbered summary returned | parallel fanout |
+| 2 | Double-check | Adoption gaps from Phase 1 fixed; `manifest.json`/`server.json` content validated; audience compliance verified; `rebuild` + `devcheck` + `test` green | parallel fanout |
+| 3 | Roll-up | Per-target headlines + cross-target patterns surfaced to user; version-bump intent confirmed (patch/minor/major) | orchestrator (serial) |
+| 4 | Wrap-up + release | Per target: version-bumped commit + annotated tag + push + publish per scope; tag annotation renders as structured markdown on GitHub Release | parallel fanout (Bash git only) |
+
+Phase 4 combines wrap-up and release in one sub-agent because the work is sequential and shares context (version, changelog, tag annotation). The sub-agent reads both Tier 1 skills.
+
+## Phase notes
+
+### Phase 1: Maintenance
+Each sub-agent runs `skills/maintenance/SKILL.md` Mode A — the full flow from `bun outdated` through verification.
+
+**Prompt phrasing matters.** Generic "run the maintenance skill" prompts cause sub-agents to stop at changelog analysis without executing. Include explicit steps in the prompt body:
+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 (or read `node_modules/<pkg>/CHANGELOG.md` directly if the skill isn't synced yet)
+4. If `@cyanheads/mcp-ts-core` updated, do the deeper framework review per the maintenance skill's Step 4
+5. Run Step 5 skill/script sync — Phase A (package → project `skills/`), Phase B (project `skills/` → agent dirs), Phase C (package scripts + pristine references → project)
+6. Adopt changes per Step 6 — framework changes are auto-adopt at every applicable site in this pass; third-party libs are cost/benefit
+7. `bun run rebuild` → `bun run devcheck` → `bun run test`
+8. Produce the Step 8 numbered summary
+
+**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 instructs: after Phase A sync completes, re-read the synced `maintenance` SKILL.md and continue from Step 5 with the new version.
+
+**Skill audience compliance.** Only sync skills with `metadata.audience: external` into project `skills/`. Sub-agents miss this under context pressure — restate explicitly.
+
+**Constraints to restate verbatim:**
+- No commits, tags, pushes — leave working tree dirty for orchestrator review
+- Read-only git allowed and expected — `git diff skills/` after Phase A surfaces adoption signal
+- Halt and report verbatim if `bun run devcheck` can't be made green; `bun audit` failures from a transitive dep with no patch are note-not-halt
+- Output the Step 8 numbered summary at the end — the orchestrator parses it
+
+### Phase 2: Double-check
+Independent maintenance sub-agents diverge on incidental choices and miss adoption sites under context pressure. The double-check pass catches gaps before wrap-up.
+
+**Critical: these sub-agents audit AND fix, then re-verify.** Not analysis-only.
+
+Audit categories (sub-agent prompt enumerates):
+
+- **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` belong in project `skills/`; agents sometimes sync `internal`-audience skills
+- **Content accuracy** — `isRequired` flags in `server.json` match the upstream API's reality (does the API work without the key?); `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 Phase 1 summaries, the other 2 likely missed it
+- **Error code semantics** — `InvalidParams` only for malformed JSON-RPC params shape; `ValidationError` for domain validation; `NotFound` for missing entities
+- **Description alignment** — `package.json`, `manifest.json`, `server.json` (≤100 char), README header, GH repo description should be consistent
+- **README install badges** — Claude Desktop `.mcpb`, Cursor deeplink, VS Code deeplink — present when `manifest.json` exists
+
+Exit gate: `bun run rebuild && bun run devcheck && bun run test` after fixes.
+
+A lighter model (e.g. Sonnet-class) is appropriate here — verification + targeted fixes, not deep adoption work.
+
+### Phase 3: Roll-up
+The orchestrator collects Phase 1 + Phase 2 reports and produces:
+1. **Per-target headlines** — short table: target → packages updated → mcp-ts-core delta → devcheck/test status → gaps fixed
+2. **Cross-target patterns** — features adopted across multiple targets, breaking changes that hit a subset
+3. **Open decisions** — per-target ambiguities; group by decision so the user can rule once across multiple targets when the choice is the same
+4. **Outliers** — targets with unusually large diffs or where adoption couldn't complete cleanly
+
+**Version bump intent.** Default is **patch** unless the change shape indicates otherwise:
+
+| Bump | When |
+|:---|:---|
+| **patch** (default) | Dependency updates, framework adoption, doc polish, bug fixes — ~95% of maintenance runs |
+| **minor** | New tools/resources/prompts added, new user-facing features, new env vars that change behavior |
+| **major** | Breaking changes to the server's MCP surface (removed tools, renamed fields, changed semantics) |
+
+If a target's diff suggests minor-or-above, **pause that target and surface to the user during roll-up** — unaffected targets proceed to Phase 4 at patch.
+
+### Phase 4: Wrap-up + release
+Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`. Runs wrap-up (version bump, changelog authoring, commit, annotated tag), then release (push, npm publish, MCP Registry, GH release, Docker).
+
+**Framework changelog reading.** When `mcp-ts-core` was updated, the sub-agent must read the framework's changelog files for the version delta (e.g. `node_modules/@cyanheads/mcp-ts-core/changelog/0.9.x/0.9.2.md` through `0.9.6.md`) and distill user-facing changes relevant to this server into the changelog entry and tag annotation. "Picks up upstream fixes" is not acceptable — name what changed.
+
+**Wrap-up scope.** Determined by repo visibility (`gh repo view --json visibility`):
+
+| Status | Scope |
+|:---|:---|
+| Private / in-development | Version bump → changelog → commit → tag → mcpb bundle → push → `gh release create`. Skip `bun publish`, Docker, MCP Registry. |
+| Public / launched | Full `release-and-publish`: push + `bun publish` + `publish-mcp` + bundle + GH release + Docker (if Dockerfile). |
+
+**npm 2FA mode.** Parallel `bun publish` doesn't play nicely with interactive 2FA — OTP prompts from multiple sub-agents interleave. Either:
+- Bypass token configured (granular access token with "Bypass 2FA for publish") → Phase 4 runs as parallel fanout
+- No bypass → Phase 4 runs serially, orchestrator-driven, one target at a time
+- No npm publish involved (private only) → non-issue
+
+**Commit structure.** Version bump rides with the change that warrants it. For a maintenance pass with a single cohesive change shape (e.g. just dep updates, or just one framework adoption), that's **one commit** — subject can lead with the version (e.g. `feat: 0.5.2 — adopt new error factories, framework ^0.9.6`). For a maintenance pass containing multiple distinct concerns, split into per-concern commits with the version bump folded into the headline-change commit, not a separate ceremonial release commit.
+
+**Tag annotations are for end users.** Internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in the commit body, not the tag annotation.
+
+**Tag-moving protocol.** If post-version doc changes land after the version commit, move the tag to HEAD: delete remote release, delete remote + local tag, recreate tag at new HEAD with same annotation, re-push, recreate release with `.mcpb`. Authorized within the workflow — same-day forward move.
+
+### Watchtower-style container refresh (if applicable)
+For targets with hosted instances behind an auto-pull tool, trigger the refresh after GHCR images are verified reachable. This is operational, not part of the release-and-publish skill — handle in the orchestrator's post-Phase-4 step if the deployment infrastructure has it.
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | Generic "run the maintenance skill" prompts cause ~50% of sub-agents to halt at changelog analysis without executing | Include explicit execution steps in Phase 1 prompt body; respawn with directive if Step 8 summary missing |
+| 2 | Skill-version paradox — feature rows added in newer maintenance skill don't surface in the synced older copy | Sub-agent prompt: after Phase A sync, re-read 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 Phase 3 roll-up. |
+| 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 |
+| 5 | Sub-agent runs write git commands despite instruction | Restate the no-write-git list + no-`stash` rule in prompt body; verify via `git log --oneline -1` per target after Phase 1 — should show no new commits |
+| 6 | Sub-agent syncs `internal`-audience skills into project `skills/` | Restate "Only sync skills with `metadata.audience: external`" — sub-agents miss this under context pressure |
+| 7 | `manifest.json` scaffolded with scoped name from `package.json` (e.g. `@scope/server-name`) — renders in mcpb install dialog | Phase 2 verifies `manifest.json` `name` doesn't contain `/` |
+| 8 | `manifest.json` `user_config` entries missing required `title`/`type` — `mcpb pack` fails at release time | Phase 2 verifies required fields |
+| 9 | `server.json` `isRequired` doesn't match upstream API reality | Phase 2 verifies against actual API behavior |
+| 10 | Framework version arrow in tag/changelog says nothing useful ("picks up upstream fixes") | Phase 4 prompt requires reading mcp-ts-core changelog files and distilling relevant changes |
+| 11 | Tag annotations render as flat comma-separated strings or balloon into full CHANGELOG copies | Phase 4 prompt: structured markdown with sections (Fixed, Dependencies, etc.), dep arrows (`pkg ^old → ^new`), test footer; length is earned |
+| 12 | Post-version doc changes land after the tag — release points at stale content | Tag-moving protocol; authorized within the workflow as a same-day forward move |
+| 13 | Background sub-agent bails early on context | Orchestrator checks for Step 8 summary; respawns continuation sub-agent if missing |
+| 14 | 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 work into "update deps + verify" and "adopt features" against that target |
+
+## Checklist
+
+- [ ] Pre-flight: target list confirmed, clean working trees, `list-skills`/`publish-mcp`/`manifest.json` presence noted, framework version delta noted, npm 2FA mode confirmed if releasing publicly
+- [ ] Phase 1: maintenance sub-agents complete — Step 8 summary present per target, devcheck + test green
+- [ ] Phase 1 integrity: `git log --oneline -1` per target confirms no new commits written by sub-agents
+- [ ] Phase 2: double-check sub-agents complete — adoption gaps fixed, audience compliance verified, `manifest.json` and `server.json` validated; devcheck + test green after fixes
+- [ ] Phase 3: roll-up surfaced to user; version bump intent confirmed (patch default; minor/major surfaces if applicable)
+- [ ] Phase 4: wrap-up + release sub-agents complete — commit + annotated tag + push + publish per target, scope matches private/public status
+- [ ] Post-Phase-4 verification: `git ls-remote --tags origin` shows new tag; `npm view <pkg>@<version>` resolves (public); GH release artifacts attached; Docker image exists (if Dockerfile)
+- [ ] Tag/release quality review: tag subject omits version number, structured markdown, no marketing adjectives, dep arrows present, issue backlinks where applicable

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

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.2"
+  version: "2.3"
   audience: external
   type: workflow
 ---
@@ -165,7 +165,24 @@ Never hand-edit `CHANGELOG.md` when using this pattern — it's a build artifact
 
 **Monolithic** — maintain `CHANGELOG.md` directly in [Keep a Changelog](https://keepachangelog.com/) format. To collapse from the template default: delete the `changelog/` directory, remove `changelog:build` and `changelog:check` from `package.json` scripts (and from `devcheck.config.json` if referenced), and drop `"changelog/"` from the `files` array. The `release` skill's directory-specific steps then don't apply — just edit `CHANGELOG.md` and bump version at release time.
 
-### 10. MCPB Bundling Artifacts
+### 10. Plugin Metadata (Codex / Claude Code)
+
+If `.codex-plugin/plugin.json` exists, verify it's populated and in sync with `package.json` and `server.json`:
+
+- `name` matches `package.json` `name`
+- `version` matches `package.json` `version`
+- `description` matches `package.json` `description`
+- `repository` matches `package.json` `repository.url`
+- `license` matches `package.json` `license`
+- `interface.displayName` = `package.json` `name`
+- `interface.shortDescription` matches `package.json` `description`
+- `interface.category` is set to a meaningful category
+
+If `.codex-plugin/mcp.json` exists, verify the server name key matches `package.json` `name` and env vars include any required API keys from the server config schema.
+
+If `.claude-plugin/plugin.json` exists, apply the same checks: `name`, `version`, `description`, `repository`, `license` from `package.json`. Verify the inline `mcpServers` entry key matches `package.json` `name` and env vars include any required API keys.
+
+### 11. MCPB Bundling Artifacts
 
 If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifest.json` at the project root), verify the full artifact set is present and consistent. If the project doesn't ship `.mcpb` bundles, skip this step.
 
@@ -185,6 +202,7 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - Env var names in `manifest.json` (`mcp_config.env` + `user_config`) match `server.json` `environmentVariables` — `lint:packaging` enforces this, but verify the set is complete
 - `manifest.json` `name` matches `package.json` name **without the npm scope prefix** (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`); `description` matches `package.json`
 - `manifest.json` `user_config` entries must include `title` and `type` fields — `mcpb pack` validates these
+- For each `user_config` entry referenced as `${user_config.X}` in `mcp_config.env`: if it's not `required: true`, set `"default": ""`. MCPB hosts (Claude Desktop included) pass the literal placeholder string through to the process when an optional field is left blank without a default — strict consumer validators (`z.email()`, `z.url()`, `.regex()`) then crash at lazy config load, exiting silently after `initialize`. Server-side: pair every optional env-backed strict-validator field with a `z.preprocess` that strips `${...}` placeholders to `undefined`.
 - `server.json` env var `isRequired` must match the upstream API's actual requirement — if the API works without the value (rate-limited, DEMO_KEY fallback, polite pool), mark `isRequired: false` and describe the tradeoff in the description
 - Server description aligned across all surfaces: `package.json`, `manifest.json`, `server.json` (condensed, hard 100-char limit), README header `<p><b>`, and GitHub repo description (`gh repo edit --description`)
 - `package.json` `keywords` include baseline terms: `mcp`, `mcp-server`, `model-context-protocol`, `typescript`, `bun`, `stdio`, `streamable-http`, plus data-domain terms. GitHub repo topics (`gh repo edit --add-topic`) should match.
@@ -196,11 +214,11 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - See `references/readme.md` for badge format and config generation commands
 - See the **Bundling** section of `templates/CLAUDE.md` for `base64` / `encodeURIComponent` generation
 
-### 11. `LICENSE`
+### 12. `LICENSE`
 
 Confirm a license file exists. If not, ask the user which license to use (default: Apache-2.0, matching the scaffolded `package.json`). Create the file.
 
-### 12. `Dockerfile`
+### 13. `Dockerfile`
 
 If a `Dockerfile` exists, verify the OCI labels and runtime config match the actual server:
 
@@ -211,7 +229,7 @@ If a `Dockerfile` exists, verify the OCI labels and runtime config match the act
 
 If no `Dockerfile` exists and the server is deployed via HTTP transport, consider scaffolding one — the template is available via `npx @cyanheads/mcp-ts-core init`.
 
-### 13. `docs/tree.md`
+### 14. `docs/tree.md`
 
 Regenerate the directory structure:
 
@@ -221,7 +239,7 @@ bun run tree
 
 Review the output for anything unexpected (leftover files, missing directories).
 
-### 14. Final Verification
+### 15. Final Verification
 
 Run the full check suite one last time:
 
@@ -243,6 +261,9 @@ Both must pass clean.
 - [ ] GitHub repo description matches `package.json` description; topics ↔ keywords in sync
 - [ ] `bunfig.toml` present
 - [ ] Changelog current — either monolithic `CHANGELOG.md` (hand-edited, Keep a Changelog) or directory-based (`changelog/<minor>.x/<version>.md` + rollup regenerated and in sync)
+- [ ] `.codex-plugin/plugin.json` populated and in sync with `package.json` (if present)
+- [ ] `.codex-plugin/mcp.json` server name and env vars current (if present)
+- [ ] `.claude-plugin/plugin.json` populated and in sync with `package.json` (if present)
 - [ ] MCPB artifacts consistent (if `manifest.json` present) — version synced, env vars match `server.json`, `bundle` + `lint:packaging` scripts exist, README install badges present
 - [ ] `LICENSE` file present
 - [ ] `Dockerfile` OCI labels and runtime config accurate (if present)

package/skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.6"
+  version: "2.7"
   audience: external
   type: workflow
 ---
@@ -131,11 +131,12 @@ Halt on any publisher error other than "cannot publish duplicate version".
 
 Only if `manifest.json` exists at the repo root (otherwise skip).
 
-Build the bundle, then create a Release on the existing annotated tag and attach the `.mcpb`. The Release sits on top of the tag from wrapup — `--verify-tag` enforces that the tag already exists on the remote and prevents `gh` from creating a lightweight tag that would shadow the annotated one. `--notes-from-tag` pulls release notes directly from the annotated tag message (no duplication). Note: GitHub prepends `v<VERSION>:` to the release title, so the tag annotation subject must omit the version number to avoid stutter.
+Build the bundle, then create a Release on the existing annotated tag and attach the `.mcpb`. The Release sits on top of the tag from wrapup — `--verify-tag` enforces that the tag already exists on the remote and prevents `gh` from creating a lightweight tag that would shadow the annotated one. `--notes-from-tag` pulls the tag annotation body as release notes. `--title` sets the release title from the tag subject — `--notes-from-tag` alone does NOT set the title (it defaults to the bare tag name, e.g. "v0.1.8" with no theme). The tag subject already omits the version number per the git-wrapup skill, so prepending `v<VERSION>:` produces the correct display title.
 
 ```bash
 bun run bundle              # produces dist/<name>.mcpb (stable filename, no version)
-gh release create v<VERSION> --verify-tag --notes-from-tag dist/*.mcpb
+SUBJECT=$(git tag -l --format='%(contents:subject)' v<VERSION>)
+gh release create v<VERSION> --verify-tag --notes-from-tag --title "v<VERSION>: $SUBJECT" dist/*.mcpb
 ```
 
 The stable filename matters: it lets the README "Install in Claude Desktop" badge point at `releases/latest/download/<name>.mcpb` and always resolve to the most recent release. The `bundle` script in the templates outputs `dist/{{PACKAGE_NAME}}.mcpb` for this reason.
@@ -205,7 +206,7 @@ If any check fails, halt and report which destination is unreachable. A successf
 - [ ] Tags pushed to origin
 - [ ] `bun publish --access public` succeeds
 - [ ] `bun run publish-mcp` succeeds (if `server.json` present)
-- [ ] `bun run bundle` + `gh release create --verify-tag --notes-from-tag` succeeds (if `manifest.json` present)
+- [ ] `bun run bundle` + `gh release create --verify-tag --notes-from-tag --title` succeeds (if `manifest.json` present)
 - [ ] Docker buildx multi-arch push succeeds (if `Dockerfile` present)
 - [ ] All published artifacts verified reachable (npm, MCP Registry, GH Release asset, GHCR manifest)
 - [ ] On re-invocation: idempotent-success signals recognized for already-published destinations

package/skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: workflow
 ---
@@ -33,6 +33,8 @@ For general `gh` CLI workflows outside issue filing (PRs, workflows, API access)
 gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
 ```
 
+5. **For documentation- or contract-shaped requests, audit all three doc layers first** — proposals to add reference docs, public-API conventions, attribute/event catalogs, or stability commitments often duplicate surface that already exists. Check `src/` for behavior, `docs/` for human-facing reference, and `skills/` for agent-facing reference. Skill files marked `audience: external` are the framework's public contract — treat them as authoritative when evaluating whether a documentation gap exists. Also verify the constants or types you'd reference aren't already exported from `@cyanheads/mcp-ts-core` or one of its subpaths.
+
 ## Writing Well-Structured Issues
 
 Good issues are scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
@@ -286,6 +288,7 @@ gh issue list -R cyanheads/mcp-ts-core --author @me
 - [ ] Confirmed bug is in `@cyanheads/mcp-ts-core`, not server code
 - [ ] Running latest (or documented) framework version
 - [ ] Searched existing issues — no duplicate found
+- [ ] If documentation or contract enhancement: confirmed `src/`, `docs/`, `skills/`, and public exports don't already cover the surface
 - [ ] All secrets, credentials, and tokens redacted
 - [ ] Primary label assigned (`bug` / `enhancement` / `documentation`)
 - [ ] If bug: version, runtime, repro code, actual vs expected behavior included

package/templates/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "",
+  "author": {
+    "name": ""
+  },
+  "homepage": "",
+  "repository": "",
+  "license": "Apache-2.0",
+  "mcpServers": {
+    "{{PACKAGE_NAME}}": {
+      "command": "npx",
+      "args": ["-y", "{{PACKAGE_NAME}}"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio"
+      }
+    }
+  }
+}

package/templates/.codex-plugin/mcp.json

@@ -0,0 +1,9 @@
+{
+  "{{PACKAGE_NAME}}": {
+    "command": "npx",
+    "args": ["-y", "{{PACKAGE_NAME}}"],
+    "env": {
+      "MCP_TRANSPORT_TYPE": "stdio"
+    }
+  }
+}

package/templates/.codex-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "",
+  "author": {
+    "name": "",
+    "email": "",
+    "url": ""
+  },
+  "homepage": "",
+  "repository": "",
+  "license": "Apache-2.0",
+  "keywords": ["mcp", "mcp-server", "model-context-protocol"],
+  "mcpServers": "./.codex-plugin/mcp.json",
+  "interface": {
+    "displayName": "{{PACKAGE_NAME}}",
+    "shortDescription": "",
+    "longDescription": "",
+    "developerName": "",
+    "category": "",
+    "capabilities": ["Read"],
+    "websiteURL": "",
+    "defaultPrompt": []
+  }
+}

package/templates/AGENTS.md

@@ -264,9 +264,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -275,6 +280,7 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
@@ -369,6 +375,8 @@ security: false                            # optional — true flags security fi
 
 `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
 **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
@@ -401,4 +409,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
 - [ ] `npm run devcheck` passes

package/templates/CLAUDE.md

@@ -50,7 +50,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
 - **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
-- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed before moving on. The comment is for future readers — state the concrete changes, not the conversation that produced them.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
 ---
 
@@ -265,9 +265,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -276,6 +281,7 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
@@ -370,6 +376,8 @@ security: false                            # optional — true flags security fi
 
 `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
 **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
@@ -402,4 +410,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
 - [ ] `npm run devcheck` passes

package/templates/changelog/template.md

@@ -19,6 +19,14 @@ breaking: false
 # `## Security` section below. Flagged as `Security` in the rollup so
 # users can triage upgrade urgency at a glance.
 security: false
+
+# Optional free-form notes for maintenance agents processing this release.
+# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
+# downstream servers. Use for adoption instructions that don't fit the
+# human-facing sections: new files to create, fields to populate, one-time
+# migration steps. Omit the field entirely when there's nothing to say.
+# agent-notes: |
+#   <instructions for downstream maintenance agents>
 ---
 
 # <version> — YYYY-MM-DD