@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.
- package/AGENTS.md +11 -10
- package/CLAUDE.md +11 -10
- package/README.md +1 -1
- package/biome.json +1 -1
- package/changelog/0.13.x/0.13.0.md +48 -0
- package/changelog/template.md +7 -24
- package/dist/cli/init.js +2 -2
- package/dist/cli/init.js.map +1 -1
- package/dist/config/envValue.d.ts +18 -0
- package/dist/config/envValue.d.ts.map +1 -0
- package/dist/config/envValue.js +35 -0
- package/dist/config/envValue.js.map +1 -0
- package/dist/config/index.d.ts.map +1 -1
- package/dist/config/index.js +5 -7
- package/dist/config/index.js.map +1 -1
- package/dist/config/parseEnvConfig.d.ts +7 -0
- package/dist/config/parseEnvConfig.d.ts.map +1 -1
- package/dist/config/parseEnvConfig.js +9 -1
- package/dist/config/parseEnvConfig.js.map +1 -1
- package/dist/linter/validate.js +2 -2
- package/dist/linter/validate.js.map +1 -1
- package/framework-skills/README.md +40 -0
- package/{skills → framework-skills}/add-app-tool/SKILL.md +2 -2
- package/{skills → framework-skills}/add-resource/SKILL.md +2 -2
- package/{skills → framework-skills}/add-service/SKILL.md +2 -2
- package/{skills → framework-skills}/add-test/SKILL.md +2 -2
- package/{skills → framework-skills}/add-tool/SKILL.md +4 -4
- package/{skills → framework-skills}/api-config/SKILL.md +3 -1
- package/{skills → framework-skills}/api-context/SKILL.md +3 -3
- package/{skills → framework-skills}/api-linter/SKILL.md +4 -4
- package/{skills → framework-skills}/maintenance/SKILL.md +30 -21
- package/{skills → framework-skills}/orchestrations/SKILL.md +2 -2
- package/{skills → framework-skills}/orchestrations/workflows/field-test-fix.md +8 -8
- package/{skills → framework-skills}/orchestrations/workflows/fix-wrapup-release.md +5 -5
- package/{skills → framework-skills}/orchestrations/workflows/greenfield-build.md +11 -11
- package/{skills → framework-skills}/orchestrations/workflows/maintenance-release.md +12 -12
- package/{skills → framework-skills}/polish-docs-meta/SKILL.md +18 -10
- package/{skills → framework-skills}/polish-docs-meta/references/agent-protocol.md +1 -1
- package/{skills → framework-skills}/polish-docs-meta/references/readme.md +86 -70
- package/{skills → framework-skills}/release-pr-review/SKILL.md +2 -2
- package/{skills → framework-skills}/report-issue-framework/SKILL.md +25 -25
- package/{skills → framework-skills}/report-issue-local/SKILL.md +22 -24
- package/{skills → framework-skills}/setup/SKILL.md +10 -8
- package/package.json +8 -8
- package/scripts/check-framework-antipatterns.ts +1 -1
- package/scripts/check-skill-versions.ts +16 -9
- package/scripts/check-skills-sync.ts +64 -13
- package/scripts/clean-mcpb.ts +3 -3
- package/scripts/devcheck.ts +16 -13
- package/scripts/lint-packaging.ts +158 -24
- package/scripts/list-skills.ts +2 -2
- package/templates/.claude-plugin/plugin.json +5 -1
- package/templates/.env.example +1 -1
- package/templates/.github/CONTRIBUTING.md +4 -5
- package/templates/.github/ISSUE_TEMPLATE/bug_report.yml +5 -4
- package/templates/.github/ISSUE_TEMPLATE/config.yml +6 -1
- package/templates/.github/ISSUE_TEMPLATE/feature_request.yml +1 -2
- package/templates/AGENTS.md +15 -14
- package/templates/CLAUDE.md +15 -14
- package/templates/_.mcpbignore +1 -1
- package/templates/changelog/template.md +7 -24
- package/templates/package.json +3 -2
- package/templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts +1 -1
- package/skills/README.md +0 -38
- /package/{skills → framework-skills}/add-export/SKILL.md +0 -0
- /package/{skills → framework-skills}/add-prompt/SKILL.md +0 -0
- /package/{skills → framework-skills}/add-provider/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-auth/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-canvas/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-errors/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-mirror/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-services/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-services/references/graph.md +0 -0
- /package/{skills → framework-skills}/api-services/references/llm.md +0 -0
- /package/{skills → framework-skills}/api-services/references/speech.md +0 -0
- /package/{skills → framework-skills}/api-telemetry/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-testing/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-utils/SKILL.md +0 -0
- /package/{skills → framework-skills}/api-utils/references/formatting.md +0 -0
- /package/{skills → framework-skills}/api-utils/references/parsing.md +0 -0
- /package/{skills → framework-skills}/api-utils/references/security.md +0 -0
- /package/{skills → framework-skills}/api-workers/SKILL.md +0 -0
- /package/{skills → framework-skills}/code-simplifier/SKILL.md +0 -0
- /package/{skills → framework-skills}/design-mcp-server/SKILL.md +0 -0
- /package/{skills → framework-skills}/field-test/SKILL.md +0 -0
- /package/{skills → framework-skills}/git-wrapup/SKILL.md +0 -0
- /package/{skills → framework-skills}/polish-docs-meta/references/package-meta.md +0 -0
- /package/{skills → framework-skills}/polish-docs-meta/references/server-json.md +0 -0
- /package/{skills → framework-skills}/release-and-publish/SKILL.md +0 -0
- /package/{skills → framework-skills}/security-pass/SKILL.md +0 -0
- /package/{skills → framework-skills}/techniques/SKILL.md +0 -0
- /package/{skills → framework-skills}/techniques/references/outline-on-overflow.md +0 -0
- /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":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACzF,OAAO,EAAE,wBAAwB,EAA0B,MAAM,6BAA6B,CAAC;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAA2B,MAAM,8BAA8B,CAAC;AACjG,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAEL,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,4EAA4E;AAC5E,MAAM,oBAAoB,GAAG,
|
|
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.
|
|
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@
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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.**
|
|
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.
|
|
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 |
|