@cyanheads/mcp-ts-core 0.9.14 → 0.9.16

package/skills/git-wrapup/SKILL.md

@@ -1,17 +1,17 @@
 ---
 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.
+  Land working-tree changes as logical commits — the work grouped by concern, topped by a release commit (version bump, changelog, regenerated artifacts) and an annotated tag. 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.1"
+  version: "1.2"
   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`).
+Working-tree or staged changes are ready to ship as a new version. This skill lands them as a stack of logical commits — the work grouped by concern, topped by a release commit (version + changelog + tree) — 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
@@ -119,27 +119,34 @@ 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
+### 7. Commit — group by concern, release artifacts on top
 
-Stage everything and create ONE atomic commit. Version bumps ride with the change that warrants them — the version bump is not a separate commit.
+Do NOT `git add -A` into one commit. Group the working tree into a handful of logical commits — never one blob:
+
+1. **The work — one commit per concern.** A feature spanning multiple layers splits by layer: runtime/logic, linter/tooling, docs/skills. Unrelated changes (two separate fixes, an incidental doc tweak) are their own commits. Work commits do not carry the version.
+2. **The release commit — last, on top.** Version bumps (`package.json`, `server.json`, README badge, `CLAUDE.md`/`AGENTS.md`), the changelog entry, `CHANGELOG.md`, and `docs/tree.md` go in a single final commit that sits on top of the work stack — never mixed into a feature commit.
+
+Stage each group explicitly, commit it, then move to the next — the release commit goes last:
 
 ```bash
-git add -A
+git add <paths-for-this-concern>
 git commit -m "<subject>"
+# repeat per concern; version + changelog + tree are the final commit
 ```
 
-**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`
+**The file is the atomic boundary:** NEVER split a single file's changes across commits. When one file serves two concerns, it ships whole in the commit of its dominant concern.
+
+**Subject format:** Conventional Commits.
+- Work commits (no version): `feat: hosted server endpoint`, `fix: handle empty SPARQL result sets`, `feat(linter): enrichment contract rules`, `docs: document the enrichment block`
+- Release commit (subject leads with the version): `chore(release): 0.2.1 — empty SPARQL result handling`
 
 **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"
+- Each commit message stands alone for someone reading `git log` — no 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.
+**Right-size it.** "Group by concern" is not "always split." A genuinely single-concern change — one fix, a dependency bump, a small doc edit — is one work commit plus the release commit; when the change and its version bump are inseparable for a tiny patch, a single commit whose subject leads with the version is fine. The failure mode to prevent is the inverse: a large, multi-layer feature crammed into one commit alongside the release artifacts.
 
 ### 8. Create an annotated tag
 
@@ -183,8 +190,8 @@ Dependency bumps:
 ### 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 log --oneline -8              # confirm the commit stack: work commits + release commit on top
+git show v<version> --stat | head -20   # confirm tag points at HEAD (the release commit)
 git status                        # must be clean
 ```
 
@@ -211,7 +218,7 @@ If the working tree isn't clean or the tag doesn't point at HEAD, something went
 - [ ] `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
+- [ ] Work grouped into logical commits (large features split by layer); release artifacts (version + changelog + tree) committed separately on top, subject leading with the version
 - [ ] Annotated tag `v<version>` with structured markdown message
 - [ ] Working tree clean
 - [ ] Nothing pushed — local only

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "2.4"
+  version: "2.5"
   audience: external
   type: workflow
 ---
@@ -78,7 +78,7 @@ Scan specifically for:
 | Config changes | New env vars, renamed keys, changed defaults |
 | Linter rules | New definition-lint rules that may now flag existing tools/resources |
 | New or materially-changed skills | Note new skills or workflow changes (renamed steps, new checklist items) worth surfacing at end-of-run. Don't auto-invoke — some skills (e.g. `security-pass`) are user-triggered. The per-version changelog entries (e.g. 0.6.14 calling out `skills/security-pass/ (v1.0)`) name what changed. |
-| New template-scaffolded files | Compare `templates/` in the package against the project root. Files that `init` would create for a new project but don't exist in this project are adoption candidates — create them with project-specific values (version, name, description, env vars from `server.json`). Examples: `manifest.json`, `.mcpbignore`, `.codex-plugin/`, `.claude-plugin/`. Skip files the project has intentionally opted out of (documented in CLAUDE.md or a code comment). |
+| New template-scaffolded files | Compare `templates/` in the package against the project root. Files that `init` would create for a new project but don't exist in this project are adoption candidates — create them with project-specific values (version, name, description, env vars from `server.json`). Examples: `manifest.json`, `.mcpbignore`, `.codex-plugin/`, `.claude-plugin/`. Skip files the project has intentionally opted out of (documented in CLAUDE.md/AGENTS.md or a code comment). |
 | Changelog `agent-notes` | Read `agent-notes` frontmatter from each new per-version changelog file — these carry release-specific adoption instructions for downstream consumers (new files to create, fields to populate, one-time migration steps). Apply them alongside other adoption work in Step 6. |
 
 Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
@@ -103,7 +103,8 @@ Procedure:
    - If missing in project `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)
-3. Do not touch skills in `skills/` that don't exist in the package (server-specific)
+3. Leave skills in `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 `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 `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 `skills/`, run `git diff 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.
 
@@ -122,7 +123,7 @@ The `setup` skill instructs consumers to copy `skills/*` into their agent's skil
 For each agent directory that exists:
 
 1. For every directory in project `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 `skills/` — they may be general-purpose skills sourced elsewhere (e.g., `code-security`, `cloudflare`, `changelog`)
+2. Do **not** delete skills in the agent dir that aren't in project `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 `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.
 
@@ -154,7 +155,7 @@ Scripts in `scripts/` that aren't present in the package directory are project-s
 |:--|:--|
 | `templates/changelog/template.md` | `changelog/template.md` |
 
-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 or its own header.
+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.
 
@@ -181,7 +182,7 @@ The consumer opted into the framework; its templates, skills, scripts, linter ru
 
 | ❌ Not a valid reason to defer | ✅ Valid reason to defer |
 |:-------------------------------|:-------------------------|
-| "Larger change than fits this pass" | Code-commented or `CLAUDE.md`-documented local override that intentionally diverges from the framework convention |
+| "Larger change than fits this pass" | Code-commented or `CLAUDE.md`/`AGENTS.md`-documented local override that intentionally diverges from the framework convention |
 | "Marginal benefit / leaving as-is" | Breaking change with multiple migration paths that need user input |
 | "Per-tool refactor — worth doing as a focused follow-up" | Feature genuinely doesn't apply (the surface doesn't exist in this server) |
 | "Existing helper has rich domain messages we'd lose" | — (port the messages onto the framework path) |
@@ -221,7 +222,7 @@ Present a concise numbered summary to the user:
 3. **Features adopted** — new framework APIs now in use
 4. **Skills synced** — added/updated with versions (Phase A) and agent directories refreshed (Phase B)
 5. **New/changed skills available** — skills that appeared in Phase A for the first time or had materially-changed step sequences. Frame as "consider running when the time is right" rather than immediate actions; the user decides when to invoke them.
-6. **Open decisions** — genuinely ambiguous items only. Valid: breaking changes with multiple migration paths needing user input, framework changes that conflict with a code-commented or `CLAUDE.md`-documented local override, third-party adoptions where cost/benefit is close. **Not valid:** framework adoptions deferred for scope, effort, or marginal-benefit reasoning — those were already adopted in Step 6 and belong under "Features adopted." If this section is empty, that's the expected outcome of a clean framework upgrade.
+6. **Open decisions** — genuinely ambiguous items only. Valid: breaking changes with multiple migration paths needing user input, framework changes that conflict with a code-commented or `CLAUDE.md`/`AGENTS.md`-documented local override, third-party adoptions where cost/benefit is close. **Not valid:** framework adoptions deferred for scope, effort, or marginal-benefit reasoning — those were already adopted in Step 6 and belong under "Features adopted." If this section is empty, that's the expected outcome of a clean framework upgrade.
 7. **Status** — rebuild / devcheck / test results
 
 ## Checklist

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

@@ -133,7 +133,7 @@ Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-p
 - 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.
+**Commit structure.** Group the work by concern, then land the release artifacts (version bumps + changelog + regenerated `docs/tree.md`/`server.json`/`manifest.json`) as a `chore(release): <version> — <theme>` commit on top — same model as `git-wrapup` Step 7. A single-concern pass (just dep updates, or one framework adoption) is one work commit plus the release commit; a pass spanning multiple distinct concerns splits into per-concern work commits with the release commit last. Regenerated meta-drift is release-artifact-shaped — it rides in the release commit, never carved out as its own.
 
 **Tag annotations are for end users.** Internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in the commit body, not the tag annotation.
 

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.4"
+  version: "2.5"
   audience: external
   type: workflow
 ---

package/skills/polish-docs-meta/references/agent-protocol.md

@@ -71,11 +71,11 @@ These sections should remain intact unless you have a specific reason to change
 - **Core Rules** — universal to all servers built on the framework
 - **Errors section** — "handlers throw, framework catches" is universal
 - **Imports section** — keep unless the alias convention was changed
-- **Framework reference pointer** — the line directing agents to `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
+- **Framework reference pointer** — the line directing agents to `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` (or `AGENTS.md`)
 
 ## Pitfalls
 
-- Don't duplicate the full framework CLAUDE.md into the project file. The project file covers server-specific conventions; the framework file covers the API. The pointer at the top connects them.
+- Don't duplicate the full framework CLAUDE.md/AGENTS.md into the project file. The project file covers server-specific conventions; the framework file covers the API. The pointer at the top connects them.
 - Don't remove `## Core Rules` even if it seems obvious — agents read this fresh each session.
 - Don't add implementation details that change frequently. The agent protocol file should be stable — update it when the server's shape changes, not on every commit.
 - Don't assume this is a one-time pass. The protocol file should be revisited whenever the server's surface area changes (tools added/removed, new services, config changes).

package/skills/polish-docs-meta/references/readme.md

@@ -20,7 +20,7 @@ Framework badge                         ← solo spotlight row — `Built on @cy
 ## Configuration                        ← env var table + `.env.example` pointer
 ## Running the server                   ← dev, production, Workers/Docker
 ## Project structure                    ← directory/purpose table
-## Development guide                    ← link to CLAUDE.md, key rules
+## Development guide                    ← link to CLAUDE.md/AGENTS.md, key rules
 ## Contributing                         ← brief
 ## License                              ← one line
 ```
@@ -471,12 +471,12 @@ Directory/purpose table orienting contributors to the codebase.
 
 ### Development Guide
 
-Brief — link to CLAUDE.md for full details. State 3-4 key rules. **Include the "validate → normalize → never fabricate" bullet** — it's the canonical anti-hallucination convention for external API wrappers and reinforces the framework's `no fabricated signal` principle.
+Brief — link to CLAUDE.md/AGENTS.md for full details. State 3-4 key rules. **Include the "validate → normalize → never fabricate" bullet** — it's the canonical anti-hallucination convention for external API wrappers and reinforces the framework's `no fabricated signal` principle.
 
 ```markdown
 ## Development guide
 
-See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
+See [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
 - Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage

package/skills/setup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: workflow
 ---
@@ -15,14 +15,9 @@ This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. Th
 
 ## Agent Protocol File
 
-The init CLI generates both `CLAUDE.md` and `AGENTS.md` with the same purpose. Keep one authoritative file for the agent you actually use:
+The init CLI generates both `CLAUDE.md` and `AGENTS.md` with identical content — `CLAUDE.md` is read by Claude Code, `AGENTS.md` by Codex, Cursor, Windsurf, and other agents. **Keep both.** Shipping both keeps the project agent-agnostic, and they're cheap to hold in sync: edit one, then `cp CLAUDE.md AGENTS.md` (the framework keeps its own pair byte-identical the same way, enforced by `check-docs-sync`). Only delete one if you're certain the project will never be opened by the other family of agents.
 
-- **Claude Code** — keep `CLAUDE.md`, delete `AGENTS.md`
-- **All other agents** (Codex, Cursor, Windsurf, etc.) — keep `AGENTS.md`, delete `CLAUDE.md`
-
-Both files serve the same purpose: project-specific agent instructions. Prefer committing one authoritative copy rather than trying to keep both in sync by hand.
-
-For the full framework docs, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
+For the full framework docs, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` (or its identical twin `AGENTS.md`) once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
 
 ## Project Structure
 
@@ -155,12 +150,12 @@ Skip or reorder as the project calls for it. The agent protocol's "What's Next?"
 
 ## Checklist
 
-- [ ] Agent protocol file selected — one authoritative file kept (`CLAUDE.md` or `AGENTS.md`), the other deleted
+- [ ] Agent protocol files kept — both `CLAUDE.md` and `AGENTS.md` present and in sync (or the unused one deliberately deleted)
 - [ ] `bun install` run
 - [ ] Dependencies updated (`bun update --latest`)
 - [ ] Git repo initialized and initial commit made (`chore: scaffold from @cyanheads/mcp-ts-core`)
 - [ ] Substituted server name verified in `package.json`, agent protocol file, and `server.json`
-- [ ] Framework docs read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
+- [ ] Framework docs read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` or `AGENTS.md`)
 - [ ] Unused echo definitions cleaned up (and unregistered from `src/index.ts`)
 - [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)

package/templates/AGENTS.md

@@ -309,7 +309,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
 | `npm run tree` | Generate directory structure doc |
-| `npm run format` | Auto-fix formatting |
+| `npm run format` | Auto-fix formatting (safe fixes only) |
+| `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
 | `npm test` | Run tests |
 | `npm run start:stdio` | Production mode (stdio) |
 | `npm run start:http` | Production mode (HTTP) |

package/templates/CLAUDE.md

@@ -309,7 +309,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
 | `npm run tree` | Generate directory structure doc |
-| `npm run format` | Auto-fix formatting |
+| `npm run format` | Auto-fix formatting (safe fixes only) |
+| `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
 | `npm test` | Run tests |
 | `npm run start:stdio` | Production mode (stdio) |
 | `npm run start:http` | Production mode (HTTP) |

package/templates/_.mcpbignore

@@ -1,6 +1,8 @@
 .env*
 .mcpregistry_*
 .claude/
+.agents/
+skills/
 Dockerfile
 bun.lock
 bunfig.toml

package/templates/changelog/template.md

@@ -43,7 +43,7 @@ security: false
   name the symbol, state what changed, stop. Use a second sentence only when
   it carries weight. If a bullet feels long, it is.
 
-  Cut: mechanism walkthroughs (those belong in JSDoc, AGENTS.md, or the
+  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
   relevant skill), ceremonial framings ("This release introduces…",
   backwards-compat paragraphs), file-by-file test enumerations, internal
   implementation notes. Prefer code/symbol names over English re-explanations.

package/templates/package.json

@@ -26,7 +26,8 @@
     "audit:refresh": "rm -f bun.lock && bun install && bun audit",
     "tree": "tsx scripts/tree.ts",
     "list-skills": "tsx scripts/list-skills.ts",
-    "format": "biome check --write --unsafe .",
+    "format": "biome check --write .",
+    "format:unsafe": "biome check --write --unsafe .",
     "lint:mcp": "tsx scripts/lint-mcp.ts",
     "lint:packaging": "tsx scripts/lint-packaging.ts",
     "bundle": "npm run build && npx -y @anthropic-ai/mcpb pack . dist/{{PACKAGE_NAME}}.mcpb",