@cyanheads/mcp-ts-core 0.9.10 → 0.9.11

package/skills/orchestrations/workflows/greenfield-build.md

@@ -0,0 +1,143 @@
+---
+name: greenfield-build
+description: >
+  Workflow: scaffold one or more new MCP server projects from `bunx @cyanheads/mcp-ts-core init` through design → build → polish → first public release. Each phase invokes a foundational skill end-to-end; this file is the sequencing and gates, not the procedural detail. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+# Greenfield Build Workflow
+
+Use after reading `../SKILL.md`. Drives one or more freshly-scaffolded MCP servers from idea to first public release by sequencing foundational skills with gates and verification.
+
+## When applicable
+
+- One or more new servers from `bunx @cyanheads/mcp-ts-core init <name>` need to be driven through design → build → ship
+- Each target is a freshly-scaffolded project with no implementation yet (echo definitions still present)
+- N = 1 and N > 1 both apply — parallelism is the optimization; the phase structure is the value
+
+## Pre-flight
+
+1. **Target list** — absolute paths and intended GitHub owner/org per target
+2. **`gh auth status`** — Phase 1 creates GH repos
+3. **`npm whoami`** — required if Phase 18 publishes publicly
+4. **API key inventory** per target — Phase 11 (field-test loop) skips targets without keys
+5. **Gold-standard reference(s)** — repo(s) the `polish-docs-meta` phase anchors on for README/metadata style. Skip the phase if no anchor exists in the ecosystem.
+
+## Versioning strategy
+
+Everything stays at **v0.1.0** through the build. Intermediate commits don't bump versions. The launch version (typically v0.1.1) is set in Phase 17.
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Scaffold (1) | `skills/setup/SKILL.md` |
+| Initial commit, design commit, build commit, pre-launch commit (2, 5, 10, 16) | `skills/git-wrapup/SKILL.md` (commit + tag, no push) |
+| Design + validation (3, 4) | `skills/design-mcp-server/SKILL.md` |
+| 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` |
+| Tool-def audit (7) | `skills/tool-defs-analysis/SKILL.md` |
+| Test coverage (8) | `skills/add-test/SKILL.md` |
+| Field-test loop (11) | → `workflows/field-test-fix.md` as a sub-loop (see Phase 11 note) |
+| Simplify (12) | `skills/code-simplifier/SKILL.md` |
+| Polish docs/meta (13) | `skills/polish-docs-meta/SKILL.md` |
+| Security pass (14) | `skills/security-pass/SKILL.md` |
+| Final wrap-up (17) | `skills/git-wrapup/SKILL.md` |
+| Release (18) | `skills/release-and-publish/SKILL.md` |
+
+## Phases
+
+Each phase's Objective column is the goal state per target — the verifiable end state the phase must produce. Phase notes only appear for orchestration overrides; phases without notes run the foundational skill end-to-end.
+
+| # | Phase | Objective | Sub-agent mode |
+|:--|:---|:---|:---|
+| 1 | Scaffold + repo | `bunx init` scaffold complete; `--private` GH repo created; LICENSE in place; working tree dirty (no commit) | parallel fanout |
+| 2 | Initial commit | v0.1.0 commit + annotated tag + push to private GH repo | parallel fanout |
+| 3 | Design | `docs/design.md` authored with Decisions Log | parallel fanout |
+| 4 | Design validation | `docs/design.md` hardened by review pass; gate sub-agent returned PASS | two sub-agents per target |
+| 5 | Design commit | Design changes committed and pushed | parallel fanout |
+| 6 | Build | All designed tools/resources/prompts implemented; no echo definitions; `devcheck` + `test` green | parallel fanout |
+| 7 | Tool-def audit | `tool-defs-analysis` findings reviewed and applied | parallel fanout |
+| 8 | Test coverage | Tests extended beyond happy path; `devcheck` + `test` green | parallel fanout |
+| 9 | Design ↔ implementation check | Every surface element in `docs/design.md` has a definition (or `docs/design.md` updated to reflect what shipped) | parallel fanout or orchestrator-direct |
+| 10 | Build commit | Build work committed and pushed | parallel fanout |
+| 11 | Field-test loop (optional) | Live API surface exercised; valid findings filed and fixed (or skipped with note) | conditional |
+| 12 | Simplify | `code-simplifier` applied; `devcheck` + `test` green — last source-code modification | parallel fanout |
+| 13 | Polish docs/meta | README, metadata, and agent protocol aligned to gold-standard reference | parallel fanout |
+| 14 | Security pass | `security-pass` findings addressed; no open security gaps | parallel fanout |
+| 15 | Final-state check | `rebuild` + `devcheck` + `test:all` + `lint:packaging` green; LICENSE present; no unfinished TODO/FIXME | orchestrator-direct |
+| 16 | Pre-launch commit | Final polish + security work committed and pushed | parallel fanout |
+| 17 | Final wrap-up | Launch version (typically v0.1.1) commit + annotated tag in place; **not pushed** | parallel fanout (Bash git only) |
+| 18 | Release | Pushed and published per scope; tag annotation renders as structured markdown on GitHub Release; artifacts reachable | parallel fanout or serial (per npm 2FA mode) |
+
+Phase 11 is optional. Phase 12 is the last phase that modifies source code — everything after is docs/metadata/verification.
+
+## Phase notes
+
+Only phases with orchestration overrides or non-obvious instructions appear below. Other phases run their foundational skill end-to-end.
+
+### Phase 1: Scaffold + repo
+Sub-agent runs `bunx @cyanheads/mcp-ts-core init <name>`, follows the `setup` skill, then creates a **private** GitHub repo (`gh repo create --private`). Override the `setup` skill's commit step — **do NOT commit**; Phase 2 is the commit. Copy `LICENSE` from `node_modules/@cyanheads/mcp-ts-core/LICENSE` if not already present.
+
+### Phase 2: Initial commit
+Sub-agent verifies `gh repo view --json visibility` returns `PRIVATE` (or has explicit user authorization for public) before push. Tag is `v0.1.0`.
+
+### Phase 4: Design validation
+Two sub-agents per target, sequential:
+
+1. **Review** — fresh sub-agent re-runs `design-mcp-server` against the existing `docs/design.md` cold (no `docs/idea.md`, no prior context). Goal: spot what the original author justified away. Output: hardened `docs/design.md`.
+2. **Gate** — sub-agent reads ONLY the hardened design and returns **PASS** or **FAIL**. PASS means "ready to build as-is." FAIL flags structural issues that would cause wasted build effort: missing tool the API clearly supports and users would expect; wrong endpoint or data model that would fail at runtime; contradictory constraints; missing error handling strategy for common failures. **Filter style preferences and marginal scope suggestions** — those are not gate failures.
+
+If gate fails, spawn a focused fix sub-agent for that target, then re-gate.
+
+### Phase 6: Build
+Sub-agents will exhaust context on targets with 4+ tools — work persists to disk but the sub-agent can't continue. Plan a follow-up "finish" iteration as a normal backstop, not a fallback for failure. After Phase 6 lands, the orchestrator inspects each target (`bun run devcheck`, `bun run test`, `ls src/mcp-server/tools/definitions/`) and spawns a narrow-scope finish sub-agent per incomplete target with a concrete punch list: "X TS errors here, tools A/B/C missing tests, echo definitions still present in `<file>`." Narrow scope is the antidote to context exhaustion.
+
+### Phase 9: Design ↔ implementation check
+For each tool / resource / prompt named in `docs/design.md`, verify a definition file exists in `src/mcp-server/{tools,resources,prompts}/definitions/`. For missing surface, decide: implement it (spawn a narrow-scope sub-agent), drop it from the design (update `docs/design.md`), or defer to a follow-up (record in the Decisions Log). This is orchestration glue — small enough that the orchestrator can run it directly for N ≤ 3, fan out for larger N.
+
+### Phase 11: Field-test loop (optional)
+When the upstream API supports live testing and an API key is available, run the phases of `field-test-fix.md` as a sub-loop here, ending at its field-test commit. Skip with a note if blocked.
+
+### Phase 12: Simplify
+Last phase that modifies source code. Everything after is docs/metadata/verification.
+
+### Phase 15: Final-state check
+Orchestrator-direct mechanical verification per target: `bun run rebuild`, `bun run devcheck`, `bun run test:all` (or `test`), `bun run lint:packaging`. `LICENSE` present. No `TODO`/`FIXME` indicating unfinished work. `CHANGELOG.md` current. `docs/tree.md` reflects current structure. Fix anything red before Phase 16; this is verification, not a sub-agent task.
+
+### Phase 17: Final wrap-up
+Version bump intent is typically **patch** — v0.1.0 was the scaffold tag; the launch is the first real release at v0.1.1. Bash git only; **do not push** — Phase 18 owns the push.
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | `gh repo create` defaults to public if `--private` is omitted | Phase 1 prompt restates the rule; Phase 2 sub-agent re-verifies `gh repo view --json visibility` before push |
+| 2 | Build sub-agents exhaust context on targets with 4+ tools | Expected — plan a finish iteration with a concrete punch list, narrow scope |
+| 3 | Design gate sub-agents flag style preferences as failures | Gate prompt: "Do NOT flag style preferences or marginal scope suggestions — only structural issues that would cause wasted build effort" |
+| 4 | Sub-agent commits during Phase 1 despite the orchestration override | Phase 1 prompt restates: "Do NOT commit — leave working tree dirty for Phase 2" verbatim |
+
+## Checklist
+
+- [ ] Pre-flight: targets confirmed, `gh` + `npm` auth verified, gold-standard reference(s) named, API key inventory complete
+- [ ] Phase 1: scaffold + setup run, private repo created, LICENSE present, working tree dirty (no commits)
+- [ ] Phase 2: v0.1.0 commit + annotated tag + push verified per target
+- [ ] Phase 3: `docs/design.md` authored per target with Decisions Log
+- [ ] Phase 4: design hardened by review pass; gate returns PASS per target
+- [ ] Phase 5: design committed per target
+- [ ] Phase 6: build complete — all designed surface implemented, green devcheck + test
+- [ ] Phase 7: `tool-defs-analysis` audit + fixes applied
+- [ ] Phase 8: dedicated test coverage pass — beyond happy path
+- [ ] Phase 9: every designed surface element has a definition (or `docs/design.md` updated to reflect what shipped)
+- [ ] Phase 10: build committed per target
+- [ ] Phase 11 (optional): field-test loop completed or skipped with note
+- [ ] Phase 12: code-simplifier — final source-code cleanup, green devcheck + test
+- [ ] Phase 13: polish-docs-meta against named gold-standard
+- [ ] Phase 14: security-pass complete, findings addressed
+- [ ] Phase 15: final-state check — rebuild + devcheck + test:all + lint:packaging green; LICENSE; no TODO/FIXME
+- [ ] Phase 16: pre-launch commit per target
+- [ ] Phase 17: final wrap-up — version bumped, changelog authored, commit + annotated tag per target
+- [ ] Phase 18: release — published per scope, artifacts verified reachable

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

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

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

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.2"
+  version: "2.3"
   audience: external
   type: workflow
 ---
@@ -202,6 +202,7 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - Env var names in `manifest.json` (`mcp_config.env` + `user_config`) match `server.json` `environmentVariables` — `lint:packaging` enforces this, but verify the set is complete
 - `manifest.json` `name` matches `package.json` name **without the npm scope prefix** (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`); `description` matches `package.json`
 - `manifest.json` `user_config` entries must include `title` and `type` fields — `mcpb pack` validates these
+- For each `user_config` entry referenced as `${user_config.X}` in `mcp_config.env`: if it's not `required: true`, set `"default": ""`. MCPB hosts (Claude Desktop included) pass the literal placeholder string through to the process when an optional field is left blank without a default — strict consumer validators (`z.email()`, `z.url()`, `.regex()`) then crash at lazy config load, exiting silently after `initialize`. Server-side: pair every optional env-backed strict-validator field with a `z.preprocess` that strips `${...}` placeholders to `undefined`.
 - `server.json` env var `isRequired` must match the upstream API's actual requirement — if the API works without the value (rate-limited, DEMO_KEY fallback, polite pool), mark `isRequired: false` and describe the tradeoff in the description
 - Server description aligned across all surfaces: `package.json`, `manifest.json`, `server.json` (condensed, hard 100-char limit), README header `<p><b>`, and GitHub repo description (`gh repo edit --description`)
 - `package.json` `keywords` include baseline terms: `mcp`, `mcp-server`, `model-context-protocol`, `typescript`, `bun`, `stdio`, `streamable-http`, plus data-domain terms. GitHub repo topics (`gh repo edit --add-topic`) should match.

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

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

package/templates/AGENTS.md

@@ -264,9 +264,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -275,6 +280,7 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |

package/templates/CLAUDE.md

@@ -265,9 +265,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `migrate-mcp-ts-template` | One-time migration of an existing project to the current framework template |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
@@ -276,6 +281,7 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |

package/skills/multi-server-orchestration/SKILL.md

@@ -1,137 +0,0 @@
----
-name: multi-server-orchestration
-description: >
-  Orchestrate parallel sub-agent fanouts across one or more MCP server projects — the same workflow run independently per target. Use for greenfield builds across N new servers, maintenance passes across N existing ones, or any repeatable workflow that benefits from fresh-context per-target sub-agents. Encodes the orient template every sub-agent needs (CLAUDE.md chain + list-skills + spec artifacts), the universal hard rules around git tooling and authorization, common gotchas that bite across runs, and a router into per-scenario references for the phase pattern.
-metadata:
-  author: cyanheads
-  version: "1.2"
-  audience: internal
-  type: workflow
----
-
-## When to Use
-
-- Same workflow driven across multiple MCP server projects in parallel — greenfield builds, maintenance updates, security audits, design extensions
-- Single server, but the work is large enough to want fresh-context sub-agents per phase rather than one continuous session
-- Any case where the per-target work is independent and benefits from devcheck-gated handoffs between phases
-
-Skip this skill for in-session tweaks to a single server — use `add-tool`, `maintenance`, `polish-docs-meta`, etc. directly.
-
-## First Pass
-
-Read this SKILL.md end-to-end first — the concepts, orient block, and hard rules below are universal across scenarios. Then:
-
-1. **Capture the target list.** N projects with absolute paths. Per-target metadata as relevant (framework version, gold-standard reference, GH owner/org). If the user named a single target, that's still N = 1.
-2. **Identify the scenario** from user intent first, then sanity-check against project state. If user intent is ambiguous, use the state heuristics below to surface a recommendation and confirm with the user — don't pick silently.
-
-   | Likely scenario | State signals (per target) |
-   |:----------------|:---------------------------|
-   | **Greenfield build-out** | Echo definitions still present in `src/mcp-server/{tools,resources,prompts}/definitions/`, no real services in `src/services/`, no released changelog files under `changelog/<minor>.x/`, `package.json` version is `0.0.0` or unset |
-   | **Maintenance pass** | Real tool/resource definitions present, framework deps installed, `bun outdated` reports updates available, at least one prior release tagged |
-   | **Wrap-up / release pass** | Working tree has uncommitted/staged work, OR `git log v<latest-tag>..HEAD` shows commits since the last release that warrant a new version, OR the user explicitly asks to "ship", "release", or do a version bump. If the user explicitly wants to publish to npm/registries → release-and-publish pass; if local-only → wrap-up pass |
-   | **Neither** | None of the above match cleanly — surface the state to the user, ask what they want |
-
-3. **Pick the reference** from the References table below. Each reference contains its scenario's phase pattern, per-sub-agent prompt bodies, scenario-specific gotchas, and checklist.
-4. **Surface the plan to the user** before kicking off the first fanout: scenario, target list, phase summary, gotchas in play. Get explicit authorization before any phase that commits, tags, pushes, or creates remote resources. Non-destructive phases (read, analyze, write files, devcheck) proceed without additional check-ins after the initial plan approval.
-
-## References
-
-| Scenario | Reference | When |
-|:---------|:----------|:-----|
-| **Greenfield build-out** | `references/greenfield-buildout.md` | New server(s) from `bunx @cyanheads/mcp-ts-core init` driven through design → build → first release |
-| **Maintenance pass** | `references/maintenance-pass.md` | Existing server(s) need `bun update --latest`, changelog investigation, framework adoption, and verification — optionally followed by a commit/push |
-| **Wrap-up pass** | `references/wrapup-pass.md` | Existing server(s) with committed/staged work to land locally as a new commit + annotated tag — verification → optional doc review → wrap-up (version + changelog + commit + tag) — **local only, no push**. Sub-agents execute the standalone `git-wrapup` skill per target |
-| **Release-and-publish pass** | `references/release-and-publish-pass.md` | Existing server(s) have committed/staged work that needs to ship as a new version end-to-end — verification → README polish → wrap-up → publish → optional GH issue closure. Sub-agents execute the standalone `git-wrapup` then `release-and-publish` skills per target |
-
-**Mental model — scenarios are related but never auto-chain.** A maintenance pass often produces work worth wrapping up; a wrap-up commonly precedes a release; a greenfield build-out ends with what's effectively a release. Useful for orienting around what comes next conceptually — but **each scenario requires its own explicit user authorization to invoke**. The orchestrator never advances from one to the next on its own. Pick the reference for the current scope; if more work follows, wait for the user to direct it.
-
-For scenarios not listed (security audits, design-only extensions, framework-wide migrations), the concepts/orient/rules/gotchas below are universal. Author a new reference describing the phase pattern when the workflow becomes repeatable.
-
-## Concepts
-
-**Parallel fanout.** One phase = one parallel batch of sub-agents, one per target. All N agents run independently in the same orchestrator message. The orchestrator (you) collects their results, normalizes inconsistencies, then triggers the next phase.
-
-**Sub-agent isolation.** Sub-agents do **not** inherit the parent session's `CLAUDE.md` chain or skills registry. They start with a blank slate plus the prompt you give them. Every sub-agent prompt must begin with an explicit orient sequence (see below) or it will work from defaults and pattern-matching instead of project conventions.
-
-**Narrow scope per fanout.** A single agent doing "implement everything, write tests, run devcheck, polish, commit, tag" will exhaust its context window before finishing — the work lands on disk but the agent can't continue. Split phases narrowly so each agent finishes well under the context limit. Plan for a follow-up "finish" pass after a big work phase.
-
-**Normalize after divergent fanouts.** Independent agents will diverge on incidental choices (scoped vs. unscoped names, script invocation form, README hero structure). When the choices should be uniform across targets, plan an explicit normalization pass after the fanout — don't expect alignment for free.
-
-## The Orient Block
-
-Every parallel sub-agent prompt opens with this block. The block is **mandatory, not advisory** — the sub-agent's first six tool calls should be the orient sequence, in order. Substitute the bracketed values per target.
-
-```text
-You are working on `[project name]` at `[project absolute path]`.
-
-Orient first. These six steps are required before any task work — do them in
-order. If any file does not exist, note it and continue.
-
-1. Read the global agent protocol at `~/.claude/CLAUDE.md` (or your agent's equivalent).
-2. Read the workspace-level protocol if one exists at `[workspace CLAUDE.md path]`
-   — skip this step if no workspace-tier protocol applies.
-3. Read the project protocol at `[project absolute path]/CLAUDE.md`.
-4. Run `cd [project absolute path] && bun run list-skills` to see the project's
-   available skills with descriptions and locations.
-5. Read the skill file(s) for this task: `[skill paths]`.
-6. Read the spec artifact(s) you'll work from: `[doc paths, e.g., docs/design.md]`.
-
-Only after that, begin the task below.
-
-**Task:** [concrete description with constraints, no-go list, expected outputs]
-```
-
-The orient block compensates for the two pieces of context sub-agents don't inherit: the CLAUDE.md chain (global → workspace → project) and the project skill registry. Both must be reconstructed manually inside the sub-agent prompt or the agent works from defaults.
-
-### Prerequisite: `list-skills.ts` in each project
-
-`list-skills.ts` is the script the orient block runs in step 4. It parses YAML frontmatter from each project-local `.claude/skills/*/SKILL.md` (falling back to `skills/`) and prints a summary an agent can read. It ships with `@cyanheads/mcp-ts-core` and is scaffolded by `init` into `scripts/list-skills.ts` with a corresponding `list-skills` package script. Projects scaffolded before the script existed pick it up via `maintenance` Phase C on the next sync.
-
-Verify presence in each target before kicking off any fanout:
-
-```bash
-test -f scripts/list-skills.ts && grep -q '"list-skills"' package.json
-```
-
-## Hard Rules
-
-These apply to every scenario. Scenario-specific rules live in their reference.
-
-1. **Bash `git` only in parallel sub-agents.** Do not let parallel sub-agents call `mcp__git-mcp-server__*` tools (or any git MCP tool that holds session state across calls). The MCP server's session state (`set_working_dir`) leaks across parallel agents in the same orchestrator session, causing silent no-ops, wrong-directory operations, and false "tag already exists" errors. Bash `git` in the agent's CWD is reliable. The orchestrator may still use git-mcp-server itself in serial.
-2. **No git commits, pushes, tags, branch creation, or destructive ops without an explicit user request.** Setup-phase and build-phase work is left unstaged for review. Wrap-up phases run only after the user authorizes a commit. Honor every `~/.claude/CLAUDE.md` rule: no `git stash`, no `reset --hard`, no `restore .`, no `clean -f`, no `--no-verify`, plain `-m` commit messages, no `Co-authored-by` or `Generated with` trailers.
-3. **`bun run devcheck` is the handoff gate.** Work phases must hand back a green devcheck. If a sub-agent can't reach green, it reports the failing step verbatim and stops rather than carrying broken state forward to the next phase.
-4. **Verify sub-agent claims with a read-only check.** Agent summaries describe intent, not always reality. After any fanout that touched the filesystem, the orchestrator confirms with `git log`, `git status`, `ls`, or its own `bun run devcheck` before declaring the phase done.
-5. **Skip marketing adjectives.** In commits, tags, READMEs, and CHANGELOG entries — no "comprehensive", "robust", "enhanced", "seamless", "improved". State the change. Restate this rule in every sub-agent prompt that produces text artifacts; the global protocol's restated rules aren't visible to sub-agents at prompt time.
-6. **One scenario per orchestration run.** Don't interleave greenfield and maintenance phases against the same target in one session. If a target needs both (e.g., a build run that needs a `bun update` first), sequence them as two scenarios with a clean handoff in between.
-
-## Gotchas
-
-These commonly bite across all scenarios. Scenario-specific gotchas live in their reference.
-
-| # | Gotcha | Mitigation |
-|:--|:-------|:-----------|
-| 1 | Sub-agents don't inherit the CLAUDE.md chain | Orient block — global, workspace (if applicable), and project CLAUDE.md read before work |
-| 2 | Sub-agents don't inherit the project skill registry | Orient block step 4 — `bun run list-skills` surfaces available skills, agent then reads task-specific ones by path |
-| 3 | `git-mcp-server`'s `set_working_dir` state leaks across parallel sub-agents in the same orchestrator session | Bash `git` only in parallel sub-agents; reserve `git-mcp-server` for serial orchestrator use |
-| 4 | Big work agents exhaust context before finishing — work lands on disk but the agent can't continue | Narrow scope per fanout; plan a finish-pass as the backstop in the scenario reference |
-| 5 | Parallel agent self-reports describe intent, not always reality (claimed "pushed" but no remote ref exists) | Verify with read-only `git log --oneline -5`, `git ls-remote --tags origin`, `gh repo view` after every fanout that touched git |
-| 6 | Independent agents diverge on incidental conventions (scoping, scripts, README hero) | Plan an explicit normalization pass; don't expect alignment for free |
-| 7 | Sub-agent skips the orient block and proceeds with pattern-matched defaults | Put orient as a numbered prerequisite in the prompt with "Only after that, begin the task"; spot-check the first tool calls in the agent's response |
-| 8 | Sub-agent runs `git stash` to "test something safely" | Restate the global rule verbatim in every sub-agent prompt that may touch git: "NEVER `git stash` for any reason." |
-| 9 | `gh release create --notes-from-tag` fails when combined with `--repo` flag | `gh` CLI limitation. Always `cd` into the target repo dir for `gh release` commands; don't use `--repo` with `--notes-from-tag` |
-
-## Extending the pattern
-
-When a new scenario emerges that's worth codifying (security-pass fanout across N servers, framework-wide migration, etc.), author a new reference at `references/<scenario>.md` and add a row to the table above. The reference should follow the shape of the existing references (e.g., `greenfield-buildout.md`): scope, pre-flight, phase table, phase details, scenario-specific gotchas, checklist. The concepts/orient/rules/gotchas in this SKILL.md don't need to be restated — the reference assumes the reader started here.
-
-## Pre-flight Checklist
-
-Applies to all scenarios — verify before picking a reference and kicking off the first fanout.
-
-- [ ] Target list captured with absolute paths and per-target metadata
-- [ ] Scenario identified from intent + state; confirmed with user if ambiguous
-- [ ] Reference selected from the table above
-- [ ] `scripts/list-skills.ts` + `list-skills` package script present in each target
-- [ ] Plan surfaced to user: scenario, targets, phase summary, active gotchas
-- [ ] User authorization captured for any phase that commits, tags, pushes, or creates remote resources
-- [ ] Scenario reference read in full before first fanout