@cyanheads/mcp-ts-core 0.12.9 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/AGENTS.md +11 -10
  2. package/CLAUDE.md +11 -10
  3. package/README.md +1 -1
  4. package/biome.json +1 -1
  5. package/changelog/0.13.x/0.13.0.md +48 -0
  6. package/changelog/template.md +7 -24
  7. package/dist/cli/init.js +2 -2
  8. package/dist/cli/init.js.map +1 -1
  9. package/dist/config/envValue.d.ts +18 -0
  10. package/dist/config/envValue.d.ts.map +1 -0
  11. package/dist/config/envValue.js +35 -0
  12. package/dist/config/envValue.js.map +1 -0
  13. package/dist/config/index.d.ts.map +1 -1
  14. package/dist/config/index.js +5 -7
  15. package/dist/config/index.js.map +1 -1
  16. package/dist/config/parseEnvConfig.d.ts +7 -0
  17. package/dist/config/parseEnvConfig.d.ts.map +1 -1
  18. package/dist/config/parseEnvConfig.js +9 -1
  19. package/dist/config/parseEnvConfig.js.map +1 -1
  20. package/dist/linter/validate.js +2 -2
  21. package/dist/linter/validate.js.map +1 -1
  22. package/framework-skills/README.md +40 -0
  23. package/{skills → framework-skills}/add-app-tool/SKILL.md +2 -2
  24. package/{skills → framework-skills}/add-resource/SKILL.md +2 -2
  25. package/{skills → framework-skills}/add-service/SKILL.md +2 -2
  26. package/{skills → framework-skills}/add-test/SKILL.md +2 -2
  27. package/{skills → framework-skills}/add-tool/SKILL.md +4 -4
  28. package/{skills → framework-skills}/api-config/SKILL.md +3 -1
  29. package/{skills → framework-skills}/api-context/SKILL.md +3 -3
  30. package/{skills → framework-skills}/api-linter/SKILL.md +4 -4
  31. package/{skills → framework-skills}/maintenance/SKILL.md +30 -21
  32. package/{skills → framework-skills}/orchestrations/SKILL.md +2 -2
  33. package/{skills → framework-skills}/orchestrations/workflows/field-test-fix.md +8 -8
  34. package/{skills → framework-skills}/orchestrations/workflows/fix-wrapup-release.md +5 -5
  35. package/{skills → framework-skills}/orchestrations/workflows/greenfield-build.md +11 -11
  36. package/{skills → framework-skills}/orchestrations/workflows/maintenance-release.md +12 -12
  37. package/{skills → framework-skills}/polish-docs-meta/SKILL.md +18 -10
  38. package/{skills → framework-skills}/polish-docs-meta/references/agent-protocol.md +1 -1
  39. package/{skills → framework-skills}/polish-docs-meta/references/readme.md +86 -70
  40. package/{skills → framework-skills}/release-pr-review/SKILL.md +2 -2
  41. package/{skills → framework-skills}/report-issue-framework/SKILL.md +25 -25
  42. package/{skills → framework-skills}/report-issue-local/SKILL.md +22 -24
  43. package/{skills → framework-skills}/setup/SKILL.md +10 -8
  44. package/package.json +8 -8
  45. package/scripts/check-framework-antipatterns.ts +1 -1
  46. package/scripts/check-skill-versions.ts +16 -9
  47. package/scripts/check-skills-sync.ts +64 -13
  48. package/scripts/clean-mcpb.ts +3 -3
  49. package/scripts/devcheck.ts +16 -13
  50. package/scripts/lint-packaging.ts +158 -24
  51. package/scripts/list-skills.ts +2 -2
  52. package/templates/.claude-plugin/plugin.json +5 -1
  53. package/templates/.env.example +1 -1
  54. package/templates/.github/CONTRIBUTING.md +4 -5
  55. package/templates/.github/ISSUE_TEMPLATE/bug_report.yml +5 -4
  56. package/templates/.github/ISSUE_TEMPLATE/config.yml +6 -1
  57. package/templates/.github/ISSUE_TEMPLATE/feature_request.yml +1 -2
  58. package/templates/AGENTS.md +15 -14
  59. package/templates/CLAUDE.md +15 -14
  60. package/templates/_.mcpbignore +1 -1
  61. package/templates/changelog/template.md +7 -24
  62. package/templates/package.json +3 -2
  63. package/templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts +1 -1
  64. package/skills/README.md +0 -38
  65. /package/{skills → framework-skills}/add-export/SKILL.md +0 -0
  66. /package/{skills → framework-skills}/add-prompt/SKILL.md +0 -0
  67. /package/{skills → framework-skills}/add-provider/SKILL.md +0 -0
  68. /package/{skills → framework-skills}/api-auth/SKILL.md +0 -0
  69. /package/{skills → framework-skills}/api-canvas/SKILL.md +0 -0
  70. /package/{skills → framework-skills}/api-errors/SKILL.md +0 -0
  71. /package/{skills → framework-skills}/api-mirror/SKILL.md +0 -0
  72. /package/{skills → framework-skills}/api-services/SKILL.md +0 -0
  73. /package/{skills → framework-skills}/api-services/references/graph.md +0 -0
  74. /package/{skills → framework-skills}/api-services/references/llm.md +0 -0
  75. /package/{skills → framework-skills}/api-services/references/speech.md +0 -0
  76. /package/{skills → framework-skills}/api-telemetry/SKILL.md +0 -0
  77. /package/{skills → framework-skills}/api-testing/SKILL.md +0 -0
  78. /package/{skills → framework-skills}/api-utils/SKILL.md +0 -0
  79. /package/{skills → framework-skills}/api-utils/references/formatting.md +0 -0
  80. /package/{skills → framework-skills}/api-utils/references/parsing.md +0 -0
  81. /package/{skills → framework-skills}/api-utils/references/security.md +0 -0
  82. /package/{skills → framework-skills}/api-workers/SKILL.md +0 -0
  83. /package/{skills → framework-skills}/code-simplifier/SKILL.md +0 -0
  84. /package/{skills → framework-skills}/design-mcp-server/SKILL.md +0 -0
  85. /package/{skills → framework-skills}/field-test/SKILL.md +0 -0
  86. /package/{skills → framework-skills}/git-wrapup/SKILL.md +0 -0
  87. /package/{skills → framework-skills}/polish-docs-meta/references/package-meta.md +0 -0
  88. /package/{skills → framework-skills}/polish-docs-meta/references/server-json.md +0 -0
  89. /package/{skills → framework-skills}/release-and-publish/SKILL.md +0 -0
  90. /package/{skills → framework-skills}/security-pass/SKILL.md +0 -0
  91. /package/{skills → framework-skills}/techniques/SKILL.md +0 -0
  92. /package/{skills → framework-skills}/techniques/references/outline-on-overflow.md +0 -0
  93. /package/{skills → framework-skills}/tool-defs-analysis/SKILL.md +0 -0
@@ -1 +1 @@
1
- {"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/linter/validate.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/linter/validate.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,40 @@
1
+ # Framework skills
2
+
3
+ Agent Skills for `@cyanheads/mcp-ts-core`. Each subdirectory contains a `SKILL.md` following the [Agent Skills specification](https://agentskills.io/specification).
4
+
5
+ The directory is `framework-skills/`, not `skills/`, on purpose. Claude Code and Codex auto-load a plugin's root `skills/`, and these are development-time skills for building a server — not skills for the agents that use one. A server that ships a plugin manifest keeps `skills/` free for that second kind.
6
+
7
+ ## Three-Tier Distribution
8
+
9
+ Skills flow through three locations. Each tier has a distinct role:
10
+
11
+ | Tier | Location | Written by | Purpose |
12
+ |:-----|:---------|:-----------|:--------|
13
+ | 1. Package | `node_modules/@cyanheads/mcp-ts-core/framework-skills/` | `npm publish` / `bun publish` | Canonical source. Ships with the package. |
14
+ | 2. Project | `framework-skills/` (project root) | `@cyanheads/mcp-ts-core init` CLI | Project's source of truth. Committed to git. Server-specific skills live here too. |
15
+ | 3. Agent | `.claude/skills/`, `.codex/skills/`, etc. | The agent itself | Agent's working copy. Synced from project `framework-skills/`. Checklists are checked here. |
16
+
17
+ ### Flow
18
+
19
+ ```text
20
+ npm publish init CLI agent sync
21
+ [package framework-skills/] ──────────> [project framework-skills/] ──────────> [.claude/skills/]
22
+ │
23
+ ├── core skills (from package)
24
+ └── server-specific skills (added by devs)
25
+ ```
26
+
27
+ ## Audience
28
+
29
+ Each skill declares `metadata.audience` in its SKILL.md frontmatter:
30
+
31
+ - **`external`** — For consumers building MCP servers. Copied to project `framework-skills/` by `init`.
32
+ - **`internal`** — For core package developers. Stays in `node_modules`, not copied.
33
+
34
+ ## Versioning
35
+
36
+ Skills declare `metadata.version` in frontmatter. The `maintenance` skill's Phase A compares versions after `bun update` and replaces a skill directory when the package version is newer; `init` only fills in what is missing and never overwrites an existing file. To pin a skill against those replacements, bump its local `metadata.version` above the package's.
37
+
38
+ ## Adding Server-Specific Skills
39
+
40
+ Create a new directory in `framework-skills/` with a `SKILL.md` following the same format. The agent will pick it up on next sync. Use the core skills as examples for structure and checklist conventions.
@@ -4,7 +4,7 @@ description: >
4
4
  Scaffold an MCP App tool + UI resource pair. Use when the user asks to add a tool with interactive UI, create an MCP App, or build a visual/interactive tool.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.4"
7
+ version: "1.5"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -117,7 +117,7 @@ const APP_HTML = `<!DOCTYPE html>
117
117
  applyDocumentTheme,
118
118
  applyHostFonts,
119
119
  applyHostStyleVariables,
120
- } from "https://unpkg.com/@modelcontextprotocol/ext-apps@1/app-with-deps";
120
+ } from "https://unpkg.com/@modelcontextprotocol/ext-apps@2/app-with-deps";
121
121
 
122
122
  const app = new App({ name: "{{TOOL_TITLE}}", version: "1.0.0" });
123
123
 
@@ -4,7 +4,7 @@ description: >
4
4
  Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.5"
7
+ version: "1.6"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -139,7 +139,7 @@ export const articleResource = resource('article://{pmid}', {
139
139
  });
140
140
  ```
141
141
 
142
- Without `errors[]`, the handler receives plain `Context` (no `fail` method) and throws via error factories (`notFound`, `serviceUnavailable`, …) directly. The contract is opt-in. See `skills/api-errors/SKILL.md` for the full pattern, baseline codes, and conformance rules.
142
+ Without `errors[]`, the handler receives plain `Context` (no `fail` method) and throws via error factories (`notFound`, `serviceUnavailable`, …) directly. The contract is opt-in. See `framework-skills/api-errors/SKILL.md` for the full pattern, baseline codes, and conformance rules.
143
143
 
144
144
  ### URI template variable completion
145
145
 
@@ -4,7 +4,7 @@ description: >
4
4
  Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.9"
7
+ version: "1.10"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -95,7 +95,7 @@ handler: async (input, ctx) => {
95
95
 
96
96
  ## Resilience (External API Services)
97
97
 
98
- When a service wraps an external API, apply these patterns. For the framework retry contract, see `skills/api-utils/SKILL.md`.
98
+ When a service wraps an external API, apply these patterns. For the framework retry contract, see `framework-skills/api-utils/SKILL.md`.
99
99
 
100
100
  ### Retry wraps the full pipeline
101
101
 
@@ -4,7 +4,7 @@ description: >
4
4
  Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a matching test file.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.6"
7
+ version: "1.7"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -15,7 +15,7 @@ Tests use Vitest and `createMockContext` from `@cyanheads/mcp-ts-core/testing`.
15
15
 
16
16
  For the full `createMockContext` API and testing patterns, read:
17
17
 
18
- skills/api-testing/SKILL.md
18
+ framework-skills/api-testing/SKILL.md
19
19
 
20
20
  ## Steps
21
21
 
@@ -4,7 +4,7 @@ description: >
4
4
  Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "2.23"
7
+ version: "2.24"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -169,7 +169,7 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
169
169
  });
170
170
  ```
171
171
 
172
- Write it as `return ctx.requestInput(...)` — the `never` return type makes it valid in return position for any output, and it is what lets TypeScript narrow the line below. Full reference (`inputRequired.elicitUrl` / `.createMessage` / `.listRoots`, `requestState`, decline handling): `skills/api-context`.
172
+ Write it as `return ctx.requestInput(...)` — the `never` return type makes it valid in return position for any output, and it is what lets TypeScript narrow the line below. Full reference (`inputRequired.elicitUrl` / `.createMessage` / `.listRoots`, `requestState`, decline handling): `framework-skills/api-context`.
173
173
 
174
174
  ### Registration
175
175
 
@@ -413,7 +413,7 @@ async handler(input, ctx) {
413
413
  },
414
414
  ```
415
415
 
416
- The alternative — declaring `previewData: z.string()` in `output` and emitting the block from `format()` — ships the bytes twice (once in `structuredContent`, once in the block). Reserve `output` for data the agent reasons over; route raw media through `ctx.content`. Test with `getContentBlocks(ctx)`. Full reference: `skills/api-context` § `ctx.content`.
416
+ The alternative — declaring `previewData: z.string()` in `output` and emitting the block from `format()` — ships the bytes twice (once in `structuredContent`, once in the block). Reserve `output` for data the agent reasons over; route raw media through `ctx.content`. Test with `getContentBlocks(ctx)`. Full reference: `framework-skills/api-context` § `ctx.content`.
417
417
 
418
418
  ### Capped lists must disclose truncation
419
419
 
@@ -714,7 +714,7 @@ throw invalidParams(
714
714
  );
715
715
  ```
716
716
 
717
- **Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `skills/api-errors/SKILL.md` for the full contract pattern, factories list, auto-classification table, and error-path parity (how `data.recovery.hint` reaches both client surfaces).
717
+ **Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `framework-skills/api-errors/SKILL.md` for the full contract pattern, factories list, auto-classification table, and error-path parity (how `data.recovery.hint` reaches both client surfaces).
718
718
 
719
719
  ### Include operational metadata
720
720
 
@@ -4,7 +4,7 @@ description: >
4
4
  Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.16"
7
+ version: "1.17"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -262,6 +262,8 @@ export function getServerConfig(): ServerConfig {
262
262
 
263
263
  **Env booleans — use `z.stringbool()`, never `z.coerce.boolean()`.** `z.coerce.boolean()` runs `Boolean(value)`, so `"false"`, `"0"`, and `"no"` all coerce to `true` — the flag becomes impossible to disable through the environment except by omitting it entirely. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` (case-insensitive) and rejects anything else, so `MY_VERBOSE_LOGGING=false` actually disables and a typo fails loudly at startup instead of silently coercing. Empty string and unset both fall through to `.default()`.
264
264
 
265
+ **Unset means unset.** `parseEnvConfig` and the framework's own config both treat an empty string and a whole-value `${…}` placeholder — what an MCPB or plugin host forwards when a user leaves an option blank and nothing substitutes it — as the variable being absent: an optional field stays `undefined`, a defaulted field takes its default, and a required field fails as missing rather than as a format error against the literal text. A value that merely contains `${…}` is kept. No per-field `z.preprocess` guard is needed for either case.
266
+
265
267
  **Why `parseEnvConfig`?** It maps Zod schema paths to env var names so validation errors name the actual variable at fault. A missing `MY_API_KEY` produces:
266
268
 
267
269
  ```
@@ -4,7 +4,7 @@ description: >
4
4
  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, its `RequestContext` base, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.requestInput`, `ctx.inputs`, `ctx.enrich`, `ctx.content`), and when to use each.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "2.2"
7
+ version: "2.3"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -594,7 +594,7 @@ async handler(input, ctx) {
594
594
  }
595
595
  ```
596
596
 
597
- The contract is opt-in. See `skills/api-errors/SKILL.md` for the full type-driven pattern, lint rules, and baseline-codes guidance.
597
+ The contract is opt-in. See `framework-skills/api-errors/SKILL.md` for the full type-driven pattern, lint rules, and baseline-codes guidance.
598
598
 
599
599
  ---
600
600
 
@@ -737,7 +737,7 @@ async handler(input, ctx) {
737
737
 
738
738
  The `capped-list-no-truncation` lint rule fires when a cap-like input + array output shape is present without any of: `truncated` or `totalCount` in the declared `enrichment`, or `truncated` or `totalCount` in `output`. Using `ctx.enrich.total(n)` (writes `totalCount`) is also recognized as honest disclosure.
739
739
 
740
- See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*` rules) for the full pattern. Test enrichment with `getEnrichment(ctx)` from `@cyanheads/mcp-ts-core/testing`.
740
+ See `add-tool`'s **Tool Response Design** and `framework-skills/api-linter` (`enrichment-*` rules) for the full pattern. Test enrichment with `getEnrichment(ctx)` from `@cyanheads/mcp-ts-core/testing`.
741
741
 
742
742
  ---
743
743
 
@@ -4,7 +4,7 @@ description: >
4
4
  MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.13"
7
+ version: "1.14"
8
8
  audience: external
9
9
  type: reference
10
10
  ---
@@ -18,7 +18,7 @@ The linter validates tool, resource, and prompt definitions against the MCP spec
18
18
  | `bun run lint:mcp` | Manual or CI | Prints errors + warnings, exits non-zero on errors. |
19
19
  | `bun run devcheck` | Pre-commit workflow | Wraps `lint:mcp` alongside typecheck, format, `bun audit`, `bun outdated`. |
20
20
 
21
- Both surface the same `LintReport` from `validateDefinitions()` (exported from `@cyanheads/mcp-ts-core/linter`). Each diagnostic has a stable `rule` ID — that's the anchor you land on via the `See: skills/api-linter/SKILL.md#<rule>` breadcrumb appended to every message.
21
+ Both surface the same `LintReport` from `validateDefinitions()` (exported from `@cyanheads/mcp-ts-core/linter`). Each diagnostic has a stable `rule` ID — that's the anchor you land on via the `See: framework-skills/api-linter/SKILL.md#<rule>` breadcrumb appended to every message.
22
22
 
23
23
  **Severity:**
24
24
  - **error** — MUST-level spec violation; blocks `devcheck`.
@@ -615,7 +615,7 @@ Validate the `landing` config passed to `createApp()` (the config object that dr
615
615
  | `landing-theme-accent` | error | `theme.accent` is present but not a string |
616
616
  | `landing-theme-accent-format` | error | `theme.accent` doesn't match the expected color format |
617
617
 
618
- Diagnostic anchors for these rules are the rule ID — e.g. `skills/api-linter/SKILL.md#landing-shape`. Pass `landing` to `validateDefinitions({ landing, tools, resources, prompts })` to opt in.
618
+ Diagnostic anchors for these rules are the rule ID — e.g. `framework-skills/api-linter/SKILL.md#landing-shape`. Pass `landing` to `validateDefinitions({ landing, tools, resources, prompts })` to opt in.
619
619
 
620
620
  ---
621
621
 
@@ -692,7 +692,7 @@ throw serviceUnavailable('Upstream failed', { upstreamError: e }, { cause: e });
692
692
 
693
693
  Validate the optional `errors[]` declarative contract on tool/resource definitions. Structural rules check the shape of contract entries; conformance rules cross-check the handler body against the declared codes.
694
694
 
695
- When a contract is declared, the handler receives a typed `ctx.fail(reason, …)` keyed by the declared reason union. See `skills/api-errors/SKILL.md` for runtime semantics.
695
+ When a contract is declared, the handler receives a typed `ctx.fail(reason, …)` keyed by the declared reason union. See `framework-skills/api-errors/SKILL.md` for runtime semantics.
696
696
 
697
697
  ### error-contract-type
698
698
 
@@ -4,7 +4,7 @@ description: >
4
4
  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.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "2.6"
7
+ version: "2.7"
8
8
  audience: external
9
9
  type: workflow
10
10
  ---
@@ -52,7 +52,7 @@ Do not redo this investigation inline — the `changelog` skill handles tag-form
52
52
 
53
53
  ### 4. Framework review (`@cyanheads/mcp-ts-core`)
54
54
 
55
- **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.
55
+ **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.
56
56
 
57
57
  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.
58
58
 
@@ -77,8 +77,8 @@ Scan specifically for:
77
77
  | Deprecations | Migrate now, before the next breaking release |
78
78
  | Config changes | New env vars, renamed keys, changed defaults |
79
79
  | Linter rules | New definition-lint rules that may now flag existing tools/resources |
80
- | 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. |
81
- | 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). |
80
+ | 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. one calling out `security-pass` v1.0) name what changed. |
81
+ | 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; user-supplied variables from `server.json` go into `userConfig` + `${user_config.<option>}` for `.claude-plugin/` and into `env_vars` for `.codex-plugin/mcp.json`, never as `""` in `env`). 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). |
82
82
  | 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. |
83
83
 
84
84
  Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
@@ -89,29 +89,31 @@ Read the upstream template end-to-end, mentally comparing against the current `C
89
89
 
90
90
  ### 5. Sync project skills and scripts
91
91
 
92
- Skills flow in two hops: package → project `skills/` → agent directories. Framework scripts flow in one: package → project `scripts/`. Both drift silently unless resynced.
92
+ Skills flow in two hops: package → project `framework-skills/` → agent directories. Framework scripts flow in one: package → project `scripts/`. Both drift silently unless resynced.
93
93
 
94
- **Phase A — Package → Project `skills/`**
94
+ **Phase A — Package → Project `framework-skills/`**
95
95
 
96
- 1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source)
97
- 2. **Project** — `skills/` at project root (working copy; may contain local overrides or server-specific skills)
96
+ 1. **Package** — `node_modules/@cyanheads/mcp-ts-core/framework-skills/` (canonical source)
97
+ 2. **Project** — `framework-skills/` at project root (working copy; may contain local overrides or server-specific skills)
98
+
99
+ **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.
98
100
 
99
101
  Procedure:
100
102
 
101
- 1. List all skill directories in `node_modules/@cyanheads/mcp-ts-core/skills/`
103
+ 1. List all skill directories in `node_modules/@cyanheads/mcp-ts-core/framework-skills/`
102
104
  2. For each skill with `metadata.audience: external` in its `SKILL.md` frontmatter:
103
- - If missing in project `skills/`, copy the full directory
105
+ - If missing in project `framework-skills/`, copy the full directory
104
106
  - If present, compare `metadata.version` — replace if the package version is newer
105
107
  - If the local version is equal or newer, skip (local override)
106
108
  - **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.
107
- 3. Leave skills in `skills/` that lack `metadata.audience: external` untouched — they're server-specific or sourced elsewhere, not framework-managed.
108
- 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.
109
+ 3. Leave skills in `framework-skills/` that lack `metadata.audience: external` untouched — they're server-specific or sourced elsewhere, not framework-managed.
110
+ 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.
109
111
 
110
- **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.
112
+ **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.
111
113
 
112
- **Phase B — Project `skills/` → Agent directories**
114
+ **Phase B — Project `framework-skills/` → Agent directories**
113
115
 
114
- The `setup` skill instructs consumers to copy `skills/*` into their agent's skill directory at init time. Those copies go stale unless re-synced. Detect which agent directories exist and propagate:
116
+ 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:
115
117
 
116
118
  | Agent | Directory |
117
119
  |:------|:----------|
@@ -123,8 +125,8 @@ The `setup` skill instructs consumers to copy `skills/*` into their agent's skil
123
125
 
124
126
  For each agent directory that exists:
125
127
 
126
- 1. For every directory in project `skills/`, copy it into the agent dir (overwrite on match, add if missing)
127
- 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).
128
+ 1. For every directory in project `framework-skills/`, copy it into the agent dir (overwrite on match, add if missing)
129
+ 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).
128
130
 
129
131
  If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.
130
132
 
@@ -170,7 +172,7 @@ Apply the findings from Steps 3 and 4. Framework changes and third-party library
170
172
 
171
173
  The consumer opted into the framework; its templates, skills, scripts, linter rules, conventions, and new APIs that supersede local code are authoritative. Adopt them now — not as a follow-up.
172
174
 
173
- - **Synced skill content from Phase A** — `git diff skills/` for every skill that was updated. Each updated body is new framework guidance; apply it to matching surfaces in this server. Examples: `add-tool` gains a section on output formatting → audit existing tool definitions against that section; `api-errors` documents a new contract pattern → adopt across error surfaces; `security-pass` adds a new check → run it against the surface. Skill updates aren't metadata.
175
+ - **Synced skill content from Phase A** — `git diff framework-skills/` for every skill that was updated. Each updated body is new framework guidance; apply it to matching surfaces in this server. Examples: `add-tool` gains a section on output formatting → audit existing tool definitions against that section; `api-errors` documents a new contract pattern → adopt across error surfaces; `security-pass` adds a new check → run it against the surface. Skill updates aren't metadata.
174
176
  - **Breaking changes** — fix call sites. Not optional.
175
177
  - **Deprecations** — migrate now, while context is fresh.
176
178
  - **New linter rules** — if the rule now flags existing code, fix the code; don't silence the rule.
@@ -212,7 +214,14 @@ In **Mode B**, the user already ran rebuild + test before invoking this skill, b
212
214
 
213
215
  Fix anything that fails. Re-run until clean.
214
216
 
215
- **Transitive advisory triage.** If `bun audit` (inside devcheck) reports a vulnerability in a transitive dep, run `bun run audit:refresh` before treating it as real. Bun's `bun update` is sticky on transitive resolutions — it keeps lockfile entries even when a parent's range allows a newer patched version. `audit:refresh` deletes `bun.lock`, reinstalls, and re-audits; if the advisory disappears, it was a stale-lockfile false positive (commit the refreshed lockfile). If it survives, it's real — patch via `package.json` `overrides` or nudge upstream.
217
+ **Transitive advisory triage.** When `bun audit` (inside devcheck) reports a vulnerability in a transitive dependency, fix it in place, most surgical option first:
218
+
219
+ 1. `bun run audit:fix` (`bun audit fix`) — upgrades the vulnerable package to the lowest safe version that still satisfies every dependent's range; `package.json` changes only when an exact pin has to move. `bun audit fix --dry-run` previews; `--latest` also applies fixes the declared ranges exclude and rewrites `package.json` — the escalation, not the default.
220
+ 2. `bun update <name>` — bumps that one package wherever it appears in the lockfile, transitive entries included, when the advisory names a version `audit fix` left alone.
221
+ 3. `bun dedupe` — collapses duplicate versions of a package in the lockfile without touching `package.json` (`bun dedupe --check` lists them); the fix when the advisory sits on a stale extra copy rather than on the version the ranges resolve to.
222
+ 4. `bun run audit:refresh` — deletes `bun.lock` and reinstalls. Last resort only: every `^`-ranged dependency re-resolves to latest-in-range, so an advisory check becomes an unreviewed dependency bump, and on Bun 1.4 the fresh lockfile is written as `lockfileVersion: 2`.
223
+
224
+ If the advisory survives all four, it is real — pin the patched version in `package.json` `overrides` or nudge upstream.
216
225
 
217
226
  ### 8. Summary
218
227
 
@@ -234,8 +243,8 @@ Present a concise numbered summary to the user:
234
243
  - [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
235
244
  - [ ] Framework `CLAUDE.md`/`AGENTS.md` template reviewed; applicable updates applied or conflicts surfaced
236
245
  - [ ] Step 6 complete — all applicable framework adoption sites updated; third-party adoption decisions recorded
237
- - [ ] Project `skills/` synced from package (Phase A), with a change report
238
- - [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
246
+ - [ ] Project `framework-skills/` synced from package (Phase A), with a change report
247
+ - [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `framework-skills/` (Phase B)
239
248
  - [ ] Framework `scripts/` and pristine reference files resynced from package via content-hash compare (Phase C), with a change report; diffs reviewed before committing
240
249
  - [ ] `bun run rebuild` succeeds (re-run after Step 6, even in Mode B)
241
250
  - [ ] `bun run devcheck` passes (includes audit + outdated)
@@ -4,7 +4,7 @@ description: >
4
4
  Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
5
5
  metadata:
6
6
  author: cyanheads
7
- version: "1.8"
7
+ version: "1.9"
8
8
  audience: external
9
9
  type: workflow
10
10
  ---
@@ -28,7 +28,7 @@ Single-skill work — running just `maintenance`, just `git-wrapup`, just `relea
28
28
  | **2** | Orchestration workflows | The four files under `workflows/` | Orchestrator only |
29
29
  | **3** | Router | This `SKILL.md` | Orchestrator only |
30
30
 
31
- Workflows in Tier 2 sequence Tier 1 skills with gates and verification. They never duplicate Tier 1 content — they direct to it. A workflow file says "Phase N: agent reads and runs `skills/git-wrapup/SKILL.md`," not "here's how to wrap up a release."
31
+ Workflows in Tier 2 sequence Tier 1 skills with gates and verification. They never duplicate Tier 1 content — they direct to it. A workflow file says "Phase N: agent reads and runs `framework-skills/git-wrapup/SKILL.md`," not "here's how to wrap up a release."
32
32
 
33
33
  The orchestrator is the agent driving the workflow — the one reading this SKILL.md. Sub-agents the orchestrator spawns receive prompts pointing at Tier 1 skills directly; they do not receive this skill or the workflow file. That boundary prevents recursive sub-agent spawning.
34
34
 
@@ -25,13 +25,13 @@ For known work (issues already tracked, handoff documents) where the discovery p
25
25
 
26
26
  | Phase | Tier 1 skill(s) |
27
27
  |:---|:---|
28
- | Field-test | `skills/field-test/SKILL.md` |
29
- | Issue filing | `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
30
- | Tool definition quality (informs field-test framing) | `skills/tool-defs-analysis/SKILL.md` |
28
+ | Field-test | `framework-skills/field-test/SKILL.md` |
29
+ | Issue filing | `framework-skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
30
+ | Tool definition quality (informs field-test framing) | `framework-skills/tool-defs-analysis/SKILL.md` |
31
31
  | Fix | (No single skill — sub-agent reads issues, validates, fixes) |
32
- | Code simplify (optional) | `skills/code-simplifier/SKILL.md` |
33
- | Wrap-up | `skills/git-wrapup/SKILL.md` |
34
- | Release | `skills/release-and-publish/SKILL.md` |
32
+ | Code simplify (optional) | `framework-skills/code-simplifier/SKILL.md` |
33
+ | Wrap-up | `framework-skills/git-wrapup/SKILL.md` |
34
+ | Release | `framework-skills/release-and-publish/SKILL.md` |
35
35
 
36
36
  ## Pre-flight
37
37
 
@@ -83,7 +83,7 @@ Phase 6 is optional — stop earlier if release isn't authorized. Phase 7 only r
83
83
  - **Do NOT file against `@cyanheads/mcp-ts-core`** unless the bug is clearly in the framework — file against the server's own repo
84
84
  - **Redact secrets** — API keys, tokens, etc.
85
85
 
86
- Sub-agent reads `skills/tool-defs-analysis/SKILL.md` as a primer — field-testing evaluates the agent-facing surface during live use, not just statically.
86
+ Sub-agent reads `framework-skills/tool-defs-analysis/SKILL.md` as a primer — field-testing evaluates the agent-facing surface during live use, not just statically.
87
87
 
88
88
  ### Phase 2: Issue triage
89
89
  Orchestrator verifies filed issues exist via `gh issue list -R <owner>/<repo>` per target. Reconciles sub-agent reports against actual GH state (sub-agents sometimes report filing but hit errors). Produces a per-target issue count and severity breakdown. If all sub-agents found 0 issues, skip to Phase 6 (or end the workflow if no release authorized).
@@ -128,7 +128,7 @@ The orchestrator makes this call based on evidence — don't defer when the data
128
128
  If looping: respawn Phase 1 + Phase 3 for targets that had fixes applied; skip targets that passed clean. Diminishing returns after 2 cycles.
129
129
 
130
130
  ### Phase 6: Wrap-up + release (optional)
131
- Each sub-agent reads both `skills/git-wrapup/SKILL.md` and `skills/release-and-publish/SKILL.md`.
131
+ Each sub-agent reads both `framework-skills/git-wrapup/SKILL.md` and `framework-skills/release-and-publish/SKILL.md`.
132
132
 
133
133
  **Release PR mode.** When the target declares it (see "Release PR mode" in `../SKILL.md`), Phase 6 runs as three serial sub-agents — wrap-up (halts at the open PR) → `release-pr-review` → release — with an orchestrator check of the PR between each. Everything below is unchanged; the PR wraps it.
134
134
 
@@ -37,11 +37,11 @@ For unsourced QA — where the bugs are unknown until you test — use `field-te
37
37
 
38
38
  | Phase | Tier 1 skill(s) |
39
39
  |:---|:---|
40
- | Validate (handoff input only) | `skills/field-test/SKILL.md` + `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
40
+ | Validate (handoff input only) | `framework-skills/field-test/SKILL.md` + `framework-skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
41
41
  | Fix | (No single skill — sub-agent reads issues, validates, fixes) |
42
- | Verify | `skills/field-test/SKILL.md` (live verification) + `skills/code-simplifier/SKILL.md` (optional) |
43
- | Wrap-up | `skills/git-wrapup/SKILL.md` |
44
- | Release | `skills/release-and-publish/SKILL.md` |
42
+ | Verify | `framework-skills/field-test/SKILL.md` (live verification) + `framework-skills/code-simplifier/SKILL.md` (optional) |
43
+ | Wrap-up | `framework-skills/git-wrapup/SKILL.md` |
44
+ | Release | `framework-skills/release-and-publish/SKILL.md` |
45
45
 
46
46
  ## Pre-flight
47
47
 
@@ -112,7 +112,7 @@ Fresh sub-agent per target, reads the full `git diff` cold. Two passes:
112
112
  Exit gate: `bun run devcheck && bun run rebuild && bun run test`.
113
113
 
114
114
  ### Phase 3: Wrap-up + release
115
- Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`.
115
+ Each sub-agent reads BOTH `framework-skills/git-wrapup/SKILL.md` AND `framework-skills/release-and-publish/SKILL.md`.
116
116
 
117
117
  **Release PR mode.** When the target declares it (see "Release PR mode" in `../SKILL.md`), Phase 3 runs as three serial sub-agents — wrap-up (halts at the open PR) → `release-pr-review` → release — with an orchestrator check of the PR between each. The commit structure, version bump, and tag rules below are unchanged; the PR wraps them.
118
118
 
@@ -35,18 +35,18 @@ Everything stays at **v0.1.0** through the build. Intermediate commits don't bum
35
35
 
36
36
  | Phase | Tier 1 skill(s) |
37
37
  |:---|:---|
38
- | Scaffold (1) | `skills/setup/SKILL.md` |
39
- | Initial commit, design commit, build commit, pre-launch commit (2, 5, 10, 16) | `skills/git-wrapup/SKILL.md` (commit + tag, no push) |
40
- | Design + validation (3, 4) | `skills/design-mcp-server/SKILL.md` |
41
- | Build (6) | `skills/add-tool/SKILL.md`, `skills/add-app-tool/SKILL.md`, `skills/add-resource/SKILL.md`, `skills/add-prompt/SKILL.md`, `skills/add-service/SKILL.md` |
42
- | Tool-def audit (7) | `skills/tool-defs-analysis/SKILL.md` |
43
- | Test coverage (8) | `skills/add-test/SKILL.md` |
38
+ | Scaffold (1) | `framework-skills/setup/SKILL.md` |
39
+ | Initial commit, design commit, build commit, pre-launch commit (2, 5, 10, 16) | `framework-skills/git-wrapup/SKILL.md` (commit + tag, no push) |
40
+ | Design + validation (3, 4) | `framework-skills/design-mcp-server/SKILL.md` |
41
+ | Build (6) | `framework-skills/add-tool/SKILL.md`, `framework-skills/add-app-tool/SKILL.md`, `framework-skills/add-resource/SKILL.md`, `framework-skills/add-prompt/SKILL.md`, `framework-skills/add-service/SKILL.md` |
42
+ | Tool-def audit (7) | `framework-skills/tool-defs-analysis/SKILL.md` |
43
+ | Test coverage (8) | `framework-skills/add-test/SKILL.md` |
44
44
  | Field-test loop (11) | → `workflows/field-test-fix.md` as a sub-loop (see Phase 11 note) |
45
- | Simplify (12) | `skills/code-simplifier/SKILL.md` |
46
- | Polish docs/meta (13) | `skills/polish-docs-meta/SKILL.md` |
47
- | Security pass (14) | `skills/security-pass/SKILL.md` |
48
- | Final wrap-up (17) | `skills/git-wrapup/SKILL.md` |
49
- | Release (18) | `skills/release-and-publish/SKILL.md` |
45
+ | Simplify (12) | `framework-skills/code-simplifier/SKILL.md` |
46
+ | Polish docs/meta (13) | `framework-skills/polish-docs-meta/SKILL.md` |
47
+ | Security pass (14) | `framework-skills/security-pass/SKILL.md` |
48
+ | Final wrap-up (17) | `framework-skills/git-wrapup/SKILL.md` |
49
+ | Release (18) | `framework-skills/release-and-publish/SKILL.md` |
50
50
 
51
51
  ## Phases
52
52
 
@@ -25,10 +25,10 @@ Use after reading `../SKILL.md`. Drives maintenance, adoption verification, wrap
25
25
 
26
26
  | Phase | Tier 1 skill(s) |
27
27
  |:---|:---|
28
- | Maintenance | `skills/maintenance/SKILL.md` |
29
- | Double-check | `skills/polish-docs-meta/SKILL.md` (the cross-file consistency reference is the most commonly missed surface) |
30
- | Wrap-up | `skills/git-wrapup/SKILL.md` |
31
- | Release | `skills/release-and-publish/SKILL.md` |
28
+ | Maintenance | `framework-skills/maintenance/SKILL.md` |
29
+ | Double-check | `framework-skills/polish-docs-meta/SKILL.md` (the cross-file consistency reference is the most commonly missed surface) |
30
+ | Wrap-up | `framework-skills/git-wrapup/SKILL.md` |
31
+ | Release | `framework-skills/release-and-publish/SKILL.md` |
32
32
 
33
33
  ## Pre-flight
34
34
 
@@ -58,25 +58,25 @@ Phase 4 combines wrap-up and release in one sub-agent because the work is sequen
58
58
  ## Phase notes
59
59
 
60
60
  ### Phase 1: Maintenance
61
- Each sub-agent runs `skills/maintenance/SKILL.md` Mode A — the full flow from `bun outdated` through verification.
61
+ Each sub-agent runs `framework-skills/maintenance/SKILL.md` Mode A — the full flow from `bun outdated` through verification.
62
62
 
63
63
  **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:
64
64
  1. `bun outdated` — capture the list
65
65
  2. `bun update --latest` — apply, capturing the `↑ package old → new` lines for Step 3
66
66
  3. Invoke the `changelog` skill for each updated package (or read `node_modules/<pkg>/CHANGELOG.md` directly if the skill isn't synced yet)
67
67
  4. If `@cyanheads/mcp-ts-core` updated, do the deeper framework review per the maintenance skill's Step 4
68
- 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)
68
+ 5. Run Step 5 skill/script sync — Phase A (package → project `framework-skills/`), Phase B (project `framework-skills/` → agent dirs), Phase C (package scripts + pristine references → project)
69
69
  6. Adopt changes per Step 6 — framework changes are auto-adopt at every applicable site in this pass; third-party libs are cost/benefit
70
70
  7. `bun run rebuild` → `bun run devcheck` → `bun run test`
71
71
  8. Produce the Step 8 numbered summary
72
72
 
73
- **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.
73
+ **Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/framework-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.
74
74
 
75
- **Skill audience compliance.** Only sync skills with `metadata.audience: external` into project `skills/`. Sub-agents miss this under context pressure — restate explicitly.
75
+ **Skill audience compliance.** Only sync skills with `metadata.audience: external` into project `framework-skills/`. Sub-agents miss this under context pressure — restate explicitly.
76
76
 
77
77
  **Constraints to restate verbatim:**
78
78
  - No commits, tags, pushes — leave working tree dirty for orchestrator review
79
- - Read-only git allowed and expected — `git diff skills/` after Phase A surfaces adoption signal
79
+ - Read-only git allowed and expected — `git diff framework-skills/` after Phase A surfaces adoption signal
80
80
  - 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
81
81
  - Output the Step 8 numbered summary at the end — the orchestrator parses it
82
82
 
@@ -88,7 +88,7 @@ Independent maintenance sub-agents diverge on incidental choices and miss adopti
88
88
  Audit categories (sub-agent prompt enumerates):
89
89
 
90
90
  - **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)
91
- - **Audience compliance** — only skills with `metadata.audience: external` belong in project `skills/`; agents sometimes sync `internal`-audience skills
91
+ - **Audience compliance** — only skills with `metadata.audience: external` belong in project `framework-skills/`; agents sometimes sync `internal`-audience skills
92
92
  - **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
93
93
  - **Cross-target consistency** — if a feature shows up in 3 of 5 Phase 1 summaries, the other 2 likely missed it
94
94
  - **Error code semantics** — `InvalidParams` only for malformed JSON-RPC params shape; `ValidationError` for domain validation; `NotFound` for missing entities
@@ -117,7 +117,7 @@ The orchestrator collects Phase 1 + Phase 2 reports and produces:
117
117
  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.
118
118
 
119
119
  ### Phase 4: Wrap-up + release
120
- 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 stack), then release (annotated tag, push, npm publish, MCP Registry, GH release, Docker).
120
+ Each sub-agent reads BOTH `framework-skills/git-wrapup/SKILL.md` AND `framework-skills/release-and-publish/SKILL.md`. Runs wrap-up (version bump, changelog authoring, commit stack), then release (annotated tag, push, npm publish, MCP Registry, GH release, Docker).
121
121
 
122
122
  **Release PR mode.** When the target declares it (see "Release PR mode" in `../SKILL.md`), Phase 4 runs as three serial sub-agents — wrap-up (halts at the open PR) → `release-pr-review` → release — with an orchestrator check of the PR between each. Everything below is unchanged; the PR wraps it.
123
123
 
@@ -153,7 +153,7 @@ For targets with hosted instances behind an auto-pull tool, trigger the refresh
153
153
  | 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. |
154
154
  | 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 |
155
155
  | 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 |
156
- | 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 |
156
+ | 6 | Sub-agent syncs `internal`-audience skills into project `framework-skills/` | Restate "Only sync skills with `metadata.audience: external`" — sub-agents miss this under context pressure |
157
157
  | 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 `/` |
158
158
  | 8 | `manifest.json` `user_config` entries missing required `title`/`type` — `mcpb pack` fails at release time | Phase 2 verifies required fields |
159
159
  | 9 | `server.json` `isRequired` doesn't match upstream API reality | Phase 2 verifies against actual API behavior |