Maintenance

When to Use

• After running bun update --latest yourself and wanting to review the impact (Mode B — typical)
• To run the whole flow end-to-end — outdated check → update → investigate → adopt → verify (Mode A)
• Periodically, to check for skill drift from the package

Entry Modes

Both modes converge at Step 3 and end at Step 8.

Steps

1. Survey what's outdated (Mode A only)

bun run devcheck --only outdated

Wraps bun outdated with the project's devcheck.config.json allowlist applied, so intentionally-pinned packages don't surface as actionable. Plain bun outdated works too if you want the unfiltered view.

Note: bun update --latest crosses semver majors; bun update alone respects ranges. Use --latest unless a package is intentionally pinned.

2. Apply the update (Mode A only)

bun update --latest

Capture the ↑ package old → new lines from stdout — these feed Step 3. Alternatively, diff bun.lock to surface version deltas after the fact.

3. Investigate changelogs

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. 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/framework-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.

Example — 0.5.2 → 0.5.4 means reading two new version files:

• node_modules/@cyanheads/mcp-ts-core/changelog/0.5.x/0.5.3.md
• node_modules/@cyanheads/mcp-ts-core/changelog/0.5.x/0.5.4.md

Cross-series updates span multiple directories — e.g., 0.4.1 → 0.5.2 reads 0.5.x/0.5.0.md, 0.5.x/0.5.1.md, 0.5.x/0.5.2.md. Enumerate the series directories under node_modules/@cyanheads/mcp-ts-core/changelog/ to find the relevant files.

If the per-version directory isn't present (pre-0.5.5 releases, or downstream package that hasn't adopted the convention), fall back to the monolithic rollup at node_modules/@cyanheads/mcp-ts-core/CHANGELOG.md and extract the relevant sections manually.

Scan specifically for:

Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.

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 and compare it against the current CLAUDE.md/AGENTS.md section by section — the skills table row by row, since a row whose wording changed (a skill's described behavior) drifts as silently as a missing one. Apply framework-authored updates directly — new or reworded 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

Skills flow in two hops: package → project framework-skills/ → agent directories. Framework scripts flow in one: package → project scripts/. Both drift silently unless resynced.

Phase A — Package → Project framework-skills/

1. Package — node_modules/@cyanheads/mcp-ts-core/framework-skills/ (canonical source)
2. Project — framework-skills/ at project root (working copy; may contain local overrides or server-specific skills)

One-time migration from skills/ (framework 0.13.0). Earlier releases scaffolded this tree at skills/. Claude Code and Codex auto-load a plugin's root skills/, so a server shipping .claude-plugin/ or .codex-plugin/ handed its development skills to every agent that installed it. If the project has skills/ and no framework-skills/: git mv skills framework-skills, then update every path reference — CLAUDE.md/AGENTS.md, .mcpbignore (/skills/ → /framework-skills/), .github/CONTRIBUTING.md — regenerate docs/tree.md, and continue below. bun run devcheck reports an unmigrated tree until this is done. The agent mirrors (.claude/skills/, .agents/skills/) keep their names; plugin hosts do not scan them.

Procedure:

1. List all skill directories in node_modules/@cyanheads/mcp-ts-core/framework-skills/
2. For each skill with metadata.audience: external in its SKILL.md frontmatter:
   • If missing in project framework-skills/, copy the full directory
   • If present, compare metadata.version — replace if the package version is newer
   • If the local version is equal or newer, skip (local override)
   • Report every skip. List each skipped skill with both versions in the pass output. The rule trusts a downstream stamp it cannot verify, so a stamp that ever moves backwards upstream makes the skip permanent and silent — the local copy outranks the package copy forever and no future edit reaches it. A skip you can see is a skip you can question; compare the two bodies whenever one looks unexpected.
3. Leave skills in framework-skills/ that lack metadata.audience: external untouched — they're server-specific or sourced elsewhere, not framework-managed.
4. Prune framework skills deleted upstream. A skill in framework-skills/ that carries metadata.audience: external but is absent from the package was removed upstream (e.g. migrate-mcp-ts-template, removed in 0.9.12) and lingers because sync was previously add/update-only. Delete it from framework-skills/ (and from the agent mirrors in Phase B). The audience: external marker is the provenance: it scopes the prune to framework-managed skills, so a server's own skills — which never carry it — are never touched. Before deleting, scan the skill for local edits worth keeping; if any exist, reconcile or surface them rather than discarding silently.

Skill diffs are adoption signal, not just sync output. After replacing files in framework-skills/, run git diff framework-skills/ to read what changed. Updated skill bodies describe new patterns, refined workflows, or new conventions — apply them to the codebase in Step 6 the same way you'd apply a framework API addition. The file copy is the trigger, not the work. The work is what the updated skill now says to do.

Phase B — Project framework-skills/ → Agent directories

The setup skill instructs consumers to copy framework-skills/* into their agent's skill directory at init time. Those copies go stale unless re-synced. Detect which agent directories exist and propagate:

For each agent directory that exists:

1. For every directory in project framework-skills/, copy it into the agent dir (overwrite on match, add if missing)
2. Do not delete skills in the agent dir that aren't in project framework-skills/ — they may be general-purpose skills sourced elsewhere (e.g., code-security, cloudflare, changelog). Exception: a framework skill pruned in Phase A step 4 — delete that same-named directory from each agent dir too. Match by the specific name you just removed, never by a blanket "absent from framework-skills/" sweep (which would catch the externally-sourced skills above).

If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.

Phase C — Package framework files → Project

Two categories of framework-authored files ship into consumer projects and drift silently as the framework updates them. Both follow the same hash-compare-and-overwrite mechanic.

Scripts — init scaffolds a fixed set that underpin bun run build, bun run devcheck, bun run lint:mcp, bun run tree, and the changelog build. Iterate the package's shipped scripts directory:

for src in node_modules/@cyanheads/mcp-ts-core/scripts/*.ts; do
  s=$(basename "$src")
  dst="scripts/$s"
  if [ ! -f "$dst" ]; then
    cp "$src" "$dst"
    echo "added: $s"
  elif ! cmp -s "$src" "$dst"; then
    cp "$src" "$dst"
    echo "updated: $s"
  fi
done

Scripts in scripts/ that aren't present in the package directory are project-specific (custom deploy, codegen, etc.) — leave them alone. The package's files: field gates what ships into node_modules/.../scripts/, so enumerating that directory is the canonical "shipped scripts" set.

Pristine reference files — files explicitly documented as "never edit, rename, or move." The framework keeps the authoritative copy under templates/; the consumer's copy must track upstream as the format evolves (new frontmatter fields, section reorderings, etc.). Fixed src→dst mapping:

Apply the same compare-and-overwrite logic. Add new entries here only when a template is explicitly documented as pristine in the framework's CLAUDE.md/AGENTS.md or its own header.

If the consumer customized a framework script or pristine reference (against guidance), the overwrite discards those changes. After the sync runs, diff scripts/ and the affected template paths to surface replacements — review before committing. If a specific local customization needs to be preserved, revert that file using your git tools.

Report which skills were added/updated in Phase A (with version deltas), which agent directories were refreshed in Phase B, and which scripts and pristine reference files were resynced in Phase C. The user needs to know what new guidance and tooling is now in play.