@cyanheads/mcp-ts-core 0.9.10 → 0.9.11

package/skills/orchestrations/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: orchestrations
+description: >
+  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.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+## When to Use
+
+Multi-phase work that chains several foundational skills against one or more MCP server projects. Typical triggers:
+
+- "Build N new servers" / "scaffold and ship X, Y, Z" → `workflows/greenfield-build.md`
+- "Update and release these servers" / "run maintenance and ship" → `workflows/maintenance-release.md`
+- "QA / field-test / find-and-fix bugs in these servers" → `workflows/field-test-fix.md`
+- "Fix these issues and ship" / handoff document with findings to act on → `workflows/fix-wrapup-release.md`
+
+Single-skill work — running just `maintenance`, just `git-wrapup`, just `release-and-publish` — invokes the foundational skill directly. Use this orchestrations skill when at least two phases need to chain.
+
+## Mental Model — Three Tiers
+
+| Tier | Layer | Examples | Who reads it |
+|:---|:---|:---|:---|
+| **1** | Foundational task skills | `git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, `design-mcp-server`, `polish-docs-meta`, `code-simplifier`, `add-tool`, `add-resource`, `add-service`, `add-test`, etc. | Orchestrator AND sub-agents (by direct path reference) |
+| **2** | Orchestration workflows | The four files under `workflows/` | Orchestrator only |
+| **3** | Router | This `SKILL.md` | Orchestrator only |
+
+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."
+
+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.
+
+## Pick a Workflow
+
+Identify the workflow from user intent first, then sanity-check against project state if intent is ambiguous.
+
+| User intent / state signal | Workflow |
+|:---|:---|
+| New scaffold(s) from `bunx @cyanheads/mcp-ts-core init`, no implementation yet (echo definitions still present, no released changelog) | `workflows/greenfield-build.md` |
+| Existing server(s), `bun outdated` shows updates, want to land them and ship | `workflows/maintenance-release.md` |
+| Existing server(s), want to find bugs via live testing and fix them, optionally ship | `workflows/field-test-fix.md` |
+| Existing server(s) with known issues (GH issues, handoff document, observed gap), want to fix and ship | `workflows/fix-wrapup-release.md` |
+
+If intent is ambiguous (no clear signal), surface the candidate workflows to the user and confirm. Don't pick silently.
+
+A workflow file is the orchestrator's playbook for one run. Read it end-to-end before kicking off the first phase.
+
+## Universal Rules
+
+These apply to every workflow. Workflow files don't restate them; the orchestrator carries them forward and restates them in sub-agent prompts where applicable.
+
+1. **No commits, pushes, tags, branch creation, or destructive ops without explicit user authorization.** Work phases leave the working tree dirty for orchestrator review. Wrap-up and release phases run only after the user authorizes — though once authorized, the authorization is durable through the workflow's end (no re-asking at each phase boundary).
+2. **No `git stash`, no `git reset --hard`, no `git restore .`, no `git clean -f`, no `git checkout -- .`.** These bypass safety and risk silent data loss. Read-only git (`status`, `diff`, `log`, `show`, `blame`) is always safe.
+3. **No `--no-verify`, no `--no-gpg-sign`, no bypassing commit hooks.** If a hook fails, investigate the underlying issue.
+4. **`bun run devcheck` is the handoff gate between phases.** Work phases must hand back a green devcheck. If a phase can't reach green, halt and report the failing step verbatim rather than carrying broken state forward.
+5. **No marketing adjectives** in commits, tags, READMEs, or changelog entries — no "comprehensive", "robust", "enhanced", "seamless", "improved". State the change, not its quality.
+6. **One workflow per orchestration run.** Don't interleave two workflows in the same session. If a target needs both (e.g., maintenance surfaces a bug fix that needs field-testing first), sequence them as two workflow runs with a clean handoff in between.
+7. **`gh release create --notes-from-tag` is incompatible with `--repo`.** Always `cd` into the target repo directory for `gh release` commands.
+8. **Annotated tags only** (`git tag -a`), never lightweight. Tag annotation subject omits the version number — GitHub prepends `v<VERSION>:` to release titles when using `--notes-from-tag`, so including the version in the subject creates stutter.
+9. **Conventional Commits subjects** (`feat|fix|refactor|chore|docs|test|build(scope): message`). One logical concern per commit. The release commit (version bump + changelog + regenerated artifacts) lands on top of a stack of feature/fix commits, never collapsed alongside them.
+10. **Email on any artifact is the user's domain email**, never a personal address that might appear in git config.
+
+## Orchestrator Posture
+
+The orchestrator owns the goals. Workflow phases are not "run skill X" — they are "achieve goal Y, using skill X as the path." Sub-agents (when used) are instruments for hitting the goals, not the work itself. The same posture applies in linear mode — the orchestrator runs the phase directly, but the goal is still the contract.
+
+Before running a phase (or spawning a sub-agent for it), write down four things:
+
+1. **Goal** — the verifiable end state this phase must produce. Concrete and testable: "v0.5.2 tag exists at HEAD with structured-markdown annotation; `bun run devcheck` green; `npm view <pkg>@0.5.2` resolves." Not fuzzy: "ran the release-and-publish skill."
+2. **Primary sources** — the specific files, GH issues, and reference docs the sub-agent must read directly. Inlining content into the prompt is a paraphrase that loses nuance; agents grounded in the source catch details the orchestrator's summary missed. For GH issues, instruct `gh issue view N --comments` — body alone misses thread clarifications. The orchestrator reads these sources too (to construct the prompt), but that's prompt construction, not a substitute for the sub-agent reading them.
+3. **Path** — the Tier 1 skill(s) and steps that get to the goal. This is what gets handed to the sub-agent.
+4. **Verification** — the read-only checks that confirm the goal was hit. Defined upfront, not as an afterthought.
+
+Why the framing matters:
+
+- **Verification follows from goal definition.** If the goal is concrete, the verification is obvious — check that exact state. If the goal is fuzzy, verification degrades to "did the sub-agent say it worked?"
+- **Sub-agent self-reports describe intent, not always reality.** A goal you wrote down beforehand is the falsification target — the sub-agent's report is a hypothesis to verify against it.
+- **Replanning is local.** When verification fails, the goal is unchanged; the orchestrator picks a different path (re-spawn with the failure context, re-slice the work, intervene directly). Phase rework doesn't cascade.
+
+**Inform without inlining.** An enhanced sub-agent prompt names the specific primary sources and the goal — it does NOT paraphrase them. "Review GH issue #123 (read it via `gh issue view 123 --comments`); the goal is X; verify with Y" is the right shape. Pasting the issue body into the prompt forces the sub-agent to work from a paraphrase. Let the sub-agent read the source and explore for additional context as needed.
+
+## Sub-Agent Strategy (if available)
+
+Sub-agents are optional. If the orchestrator has the capability to spawn them, fan out work in parallel where it makes sense. Single-target workflows usually run linearly; multi-target workflows benefit from a parallel sub-agent per target. Choose based on scope, not by default.
+
+The decision tree:
+
+| Situation | Strategy |
+|:---|:---|
+| Single target, small change | Linear, orchestrator runs the phases itself |
+| Single target, large change likely to exhaust orchestrator context | Sub-agent per phase; orchestrator gates between phases |
+| N > 1 targets, independent work per target | One sub-agent per target per phase (parallel fanout) |
+| N > 1 targets, work that conflicts across targets (e.g., all editing the same file) | Linear or serial — the parallel model assumes target independence |
+| Sub-agents not available | Linear, regardless of N — same phases, just sequential |
+
+If sub-agents are not available, the workflow phases still apply — they're just executed sequentially by the orchestrator. The phase structure is the value; parallelism is the optimization.
+
+### Orient block
+
+Every sub-agent prompt opens with this block. Sub-agents do not inherit the orchestrator's `CLAUDE.md` chain or skill registry — both must be reconstructed in the prompt. Substitute the bracketed values per target.
+
+```text
+You are working on `[project name]` at `[project absolute path]`.
+
+Orient first. These 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: `[Tier 1 skill paths]`.
+6. Read the primary sources for this task directly — design docs (`docs/design.md`),
+   GH issues (use `gh issue view <N> --comments` to capture the full thread, not
+   just the body), handoff documents, reference/gold-standard files. List each
+   one explicitly: `[primary source paths and gh commands]`. Skip this step only
+   if no primary source applies (rare).
+
+Only after that, begin the task below.
+
+**Goal:** [the verifiable end state this phase must produce — concrete, testable]
+**Path:** [Tier 1 skill(s) and steps the sub-agent should follow]
+**Constraints:** [no-go list — restate git/commit rules and other invariants verbatim]
+**Expected outputs:** [report shape you want back — e.g., "Step 8 numbered summary", "list of files touched with one-line rationale per fix"]
+```
+
+The sub-agent reads the primary sources directly during orient (step 6) — do not paste their contents into the prompt. The orchestrator names them; the sub-agent reads them.
+
+### Isolation rules
+
+1. **Bash `git` only in parallel sub-agents.** Do not let parallel sub-agents call `mcp__git-mcp-server__*` tools — session state (`set_working_dir`) leaks across parallel calls 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. **Sub-agents do not receive this orchestrations skill or workflow files.** Their prompts include Tier 1 skill paths only. This prevents recursive sub-agent spawning — if a sub-agent decides it needs to fan out work, that's a signal the orchestrator sliced the work too wide. Re-slice; don't let the sub-agent recurse.
+
+3. **Sub-agent prompts must restate the no-git-write and no-`stash` rules verbatim.** The orchestrator's `CLAUDE.md` rules aren't visible to sub-agents at prompt time.
+
+4. **Narrow scope per fanout.** A sub-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 so each sub-agent finishes well under the context limit. Plan a follow-up "finish" phase as a normal backstop, not a fallback for failure.
+
+### Parallel fanout pattern
+
+For N targets in a phase:
+
+1. Compose N sub-agent prompts (one per target) with the orient block + task body + workflow's phase-specific constraints
+2. Launch them as parallel sub-agents in a single orchestrator action
+3. Collect their reports
+4. Verify with a read-only orchestrator check before advancing to the next phase
+
+### Editor / wrap-up separation
+
+Editing phases and wrap-up phases never go in the same sub-agent. Editing sub-agents make file changes and run devcheck — they do not commit, tag, or push. Wrap-up sub-agents read the working tree, commit, tag, and (when releasing) push and publish — they do not edit source. This separation lets the orchestrator review diffs before they become permanent and keeps the commit graph clean.
+
+### Normalization
+
+Independent sub-agents diverge on incidental choices — scoped vs. unscoped package names, script invocation form, README hero structure, badge ordering. When choices should be uniform across targets, plan an explicit normalization step after the fanout — don't expect alignment for free.
+
+For small N or small diffs, the orchestrator normalizes directly. For large N or non-trivial fixes, spawn a narrow-scope fanout with an explicit rule list.
+
+### Rolling concurrency
+
+Rate limits on parallel sub-agent spawning are intermittent — sometimes 15 concurrent agents work fine, sometimes 3 get throttled. Don't hard-cap; use rolling concurrency. Launch an initial batch, then as each agent completes, kick off the next in line. If a wave gets rate-limited, shrink the window for the next wave.
+
+### Cross-project naming hygiene
+
+When N targets share a phase, never name other targets in a sub-agent's prompt — even as examples. Sub-agents pattern-match on everything in their prompt, and cross-project names leak into commits, messages, and variable names. Each sub-agent's prompt references its own target only.
+
+## Verification (orchestrator)
+
+Verification runs against the goal *you* defined for the phase — not against the sub-agent's self-report. A sub-agent that reports "done" without producing the goal state is not done. The artifact checks below are the *means* of confirming the goal; pick the ones that exercise your specific goal definition.
+
+Sub-agent self-reports describe intent, not always reality. After every phase that touched the filesystem or remote services, run a read-only check against the goal:
+
+- **Files** — `ls`, `git status`, `git diff --stat`
+- **Commits** — `git log --oneline -5`
+- **Tags** — `git tag --points-at HEAD`, `git ls-remote --tags origin`
+- **GitHub** — `gh repo view --json visibility`, `gh release view v<VERSION>`, `gh issue list`, `gh issue view <N> --comments` to confirm the fix comment landed
+- **npm / registries** — `npm view <pkg>@<version>`, registry-specific checks
+- **Build state** — re-run `bun run devcheck` if the previous phase was supposed to land green
+- **Quality** — tag annotation reads as structured markdown (not flat string), subject omits the version number, no marketing adjectives, dep arrows present where applicable, issue backlinks where applicable
+
+If verification disagrees with the sub-agent's report, that's the signal to re-spawn with the actual state and the unmet goal in the prompt — not to trust the report. The goal hasn't changed; only the path needs to.
+
+## Authorization Flow
+
+| Phase type | Authorization required |
+|:---|:---|
+| Reads, analysis, file edits (working tree only) | Implicit — initial workflow approval covers these |
+| Local commits, annotated tags | Explicit at workflow start; durable through workflow end |
+| Push to remote, npm / registry publish, GH release create, Docker push | Explicit at workflow start; durable through workflow end |
+| Destructive ops (force push, tag delete, remote branch delete, etc.) | Always re-confirm, never assume |
+
+Pipeline authorization is durable through to completion. Once the user authorizes a workflow run, don't re-ask at each phase boundary — proceed automatically through gates that pass. Conditions that always require a fresh check-in: destructive ops on shared resources, external actions without sign-off, errors that need human judgment.
+
+## Workflow File Discipline
+
+Workflow files are thin by design. Each phase row in a workflow's phases table maps to a Tier 1 skill or a thin orchestration step. **Phase notes are for orchestration overrides only** — sequencing rules, fanout-specific constraints, non-obvious instructions, decisions the foundational skill leaves to the caller. Never paraphrase what a foundational skill already documents. A phase that runs a Tier 1 skill end-to-end with no orchestration override needs no phase note — just the row in the table.
+
+The same discipline applies to gotchas: workflow-specific gotchas are about the orchestration pattern itself (e.g., parallel sub-agent context exhaustion, normalization gaps). Gotchas about a Tier 1 skill's internals belong in that skill, not the workflow.
+
+## When the Workflow List Doesn't Fit
+
+For scenarios that don't map cleanly to one of the four workflow files — security audits across N servers, framework-wide migrations, design-only extensions, ad-hoc multi-step work — the universal rules and sub-agent strategy above still apply. Author a new workflow file at `workflows/<scenario>.md` when the pattern is repeatable enough to codify. Follow the shape of the existing workflow files: when applicable, Tier 1 skills referenced, pre-flight, phases table, phase notes, workflow-specific gotchas, checklist. Apply the workflow file discipline above.
+
+## Pre-flight Checklist (every workflow)
+
+Verify before kicking off the first phase. Workflow files add their own pre-flight items on top of these.
+
+- [ ] Target list captured with absolute paths
+- [ ] Intent and state signals point to a single workflow (or confirmed with user if ambiguous)
+- [ ] Selected workflow file read end-to-end
+- [ ] Phase objectives understood (the Objective column of the phases table is the goal contract — verification runs against these)
+- [ ] Plan surfaced to user: workflow, targets, phase objectives, applicable universal rules
+- [ ] User authorization captured for the workflow's commit/push/publish phases (if any apply)
+- [ ] Sub-agent capability confirmed (or fallback to linear execution noted)

package/skills/orchestrations/workflows/field-test-fix.md

@@ -0,0 +1,206 @@
+---
+name: field-test-fix
+description: >
+  Workflow: field-test one or more existing MCP server projects against the live upstream API, file GH issues for valid findings, deploy fix sub-agents per server, optionally loop until clean, then wrap up and release. Chains the `field-test`, `report-issue-local`, `tool-defs-analysis`, `code-simplifier`, `git-wrapup`, and `release-and-publish` skills. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+# Field-Test + Fix Workflow
+
+Use after reading `../SKILL.md`. Drives field-testing, issue filing, fix application, verification, and (optional) release across N MCP server projects.
+
+## When applicable
+
+- One or more existing servers need a QA pass against the live upstream API — quality gate before launch, post-release smoke test, or "find and fix bugs" instruction
+- The user wants observed bugs filed as GH issues and then fixed
+- Optionally ends in a release; can also stop at "fixed, committed locally" if release isn't authorized yet
+
+For known work (issues already tracked, handoff documents) where the discovery phase isn't needed, use `fix-wrapup-release.md` instead.
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Field-test | `skills/field-test/SKILL.md` |
+| Issue filing | `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
+| Tool definition quality (informs field-test framing) | `skills/tool-defs-analysis/SKILL.md` |
+| Fix | (No single skill — sub-agent reads issues, validates, fixes) |
+| Code simplify (optional) | `skills/code-simplifier/SKILL.md` |
+| 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
+2. **Current version** — `git describe --tags --abbrev=0`, `grep '"version"' package.json`
+3. **API keys** — `.env` files exist for servers requiring them. If missing, surface the list with registration URLs before proceeding.
+4. **Issue template + `report-issue-local` skill present** per target
+5. **`list-skills` script present** — `test -f scripts/list-skills.ts && grep -q '"list-skills"' package.json`
+6. **Repo visibility** — `gh repo view --json visibility -q '.visibility'` per target. Determines wrap-up scope.
+7. **Build** — `bun run rebuild` per target, parallel. All must pass before Phase 1.
+
+## 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 | Field-test | Per target: live tool/resource/prompt surface exercised across happy/error/edge paths; valid findings filed as GH issues against the server's own repo; noise filtered | parallel fanout per target; within a target, 1 or 3 sub-agents (see below) |
+| 2 | Issue triage | Per-target GH issue count + severity breakdown reconciled against actual GH state | orchestrator (serial) |
+| 3 | Fix | Per target: priority issues fixed in source, tests updated, `devcheck` + `test` green, each issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) |
+| 4 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout |
+| 5 | Loop decision | Orchestrator decision recorded — proceed to release, loop another field-test cycle, or pause/surface to user. Evidence-based | orchestrator (serial) |
+| 6 | Wrap-up + release | (Optional) Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) |
+| 7 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment; skipped issues remain open | orchestrator (serial) |
+
+Phase 6 is optional — stop earlier if release isn't authorized. Phase 7 only runs if Phase 6 ran.
+
+## Phase notes
+
+### Phase 1: Field-test
+
+**Default: one comprehensive sub-agent per target** that covers happy paths, error paths, and edge cases in sequence. Use three separate sub-agents only when the server has 8+ tools and a single agent would exhaust context.
+
+| Category | What to test |
+|:---|:---|
+| Happy paths | Every tool/resource/prompt with realistic input — output shape, `content[]` readability, `structuredContent` parity, field selection |
+| Error paths | Invalid inputs, missing fields, wrong types — error contract verification (code/reason), error text actionability |
+| Edge cases | Boundaries, empty results, pagination limits, special characters, domain-specific oddities — crash resistance, 0-result messaging, date boundaries |
+
+**Sub-agent isolation.** Each sub-agent gets a unique field-test ID in its helper file path: `/tmp/<project-name>-field-test-<ID>.sh`. Convention: `<SERVER-PREFIX>-<HP|ER|EC>-<5CHAR>`. The helper script is stateless — every function takes IDs as positional args.
+
+**Build skip.** Pre-flight built the project. Tell sub-agents to modify their `mcp_start` helper to skip `bun run rebuild` — just start the server. This avoids concurrent builds racing on `dist/`. Each agent starts its own server instance; ports auto-increment.
+
+**Issue filing.** Sub-agents file GH issues against the server's own repo using `report-issue-local` patterns. Constraints:
+- **Noise filter** — before filing, the sub-agent asks: "Would a maintainer coming to this cold say 'yes, this needs fixing'?" If not, skip.
+- **`gh issue create` with `--title` and `--body`** (not `--web`) — include server version, framework version, runtime, transport, repro steps, actual vs expected behavior
+- **Do NOT file against `@cyanheads/mcp-ts-core`** unless the bug is clearly in the framework — file against the server's own repo
+- **Redact secrets** — API keys, tokens, etc.
+
+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.
+
+### Phase 2: Issue triage
+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).
+
+### Phase 3: Fix
+**One sub-agent per target — hard constraint.** No file-locking system exists for concurrent edits; multiple agents touching the same server's `src/` will conflict.
+
+Each sub-agent:
+1. Reads all open issues for its target via `gh issue list` + `gh issue view N --comments` (full thread — body alone misses clarifications)
+2. **Validates each issue against source code** — a "fixed" issue is a misdiagnosed one if validation fails
+3. Implements fixes in priority order: security → bugs → UX
+4. Rebuilds after each fix or group of related fixes
+5. Field-tests each fix live (starts server, runs repro steps from the issue)
+6. Runs `bun run devcheck` and `bun run test` — exit gate
+7. Comments on each GH issue with a concise fix summary
+8. Leaves everything uncommitted
+
+**Constraints to restate:**
+- Surgical fixes only — don't refactor surrounding code unless the fix requires it
+- If a fix is disproportionate (major architecture change), note it on the issue and skip
+- Every fix verified live, not just compiled — include actual tool call output in the summary
+
+### Phase 4: Verify
+Fresh sub-agent per target, reads the full `git diff` cold. Two passes in one sub-agent:
+
+1. **Code-simplify** — read `code-simplifier`, review the full diff through that lens, apply cleanup if warranted. Skip if changes are minimal — don't run as ceremony.
+2. **Re-field-test** — spin up the server, run the repro steps from each fixed issue, include actual tool call output in the summary.
+
+Exit gate: `bun run devcheck && bun run rebuild && bun run test`.
+
+### Phase 5: Loop decision
+
+| Signal | Action |
+|:---|:---|
+| All fixes validated, devcheck + tests green | Proceed to Phase 6 (or end if release not authorized) |
+| Fix sub-agent reported skipped issues (disproportionate) | Note; proceed unless critical |
+| Fix sub-agent couldn't reach green gates | Respawn fix sub-agent with specific failure context |
+| Major architectural issues surfaced | Pause, surface to user |
+
+The orchestrator makes this call based on evidence — don't defer when the data is clear.
+
+If looping: respawn Phase 1 + Phase 3 for targets that had fixes applied; skip targets that passed clean. Diminishing returns after 2 cycles.
+
+### Phase 6: Wrap-up + release (optional)
+Each sub-agent reads both `skills/git-wrapup/SKILL.md` and `skills/release-and-publish/SKILL.md`.
+
+**Commit structure.** Fixes are NOT collapsed into a single commit. Per the universal git rules:
+1. Analyze the diff (`git diff --stat`, then spot-check actual changes)
+2. Group by file boundaries — fixes sharing a file ship in the same commit
+3. Commit each group: `fix(scope): description` (Conventional Commits)
+4. Release commit on top — version bump + changelog + regenerated artifacts as `chore(release): v<version>`
+5. Tag the release commit
+
+The tag annotation and changelog cover ALL fixes — the commit split is about git history, not release notes.
+
+**Version bump.** Default **patch** for field-test fix releases. **Minor** when enhancements are bundled in.
+
+**Tag annotation format.** Tag subject omits the version number. Structured markdown:
+
+```
+Field-test bug fixes across N tools
+
+Fixed:
+- <tool_name>: <one-line fix description> (#<issue>)
+- <tool_name>: <one-line fix description> (#<issue>)
+
+<test count>; `bun run devcheck` clean.
+```
+
+Add a `Security:` section when the changelog frontmatter sets `security: true`.
+
+**Wrap-up scope.** Determined by repo 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). |
+
+### Phase 7: Issue cleanup
+Close issues that shipped fixes — only those. Skipped issues stay open.
+
+```bash
+for n in <fixed-issue-numbers-from-phase-3>; do
+  gh issue close "$n" -R "<owner>/<repo>" --reason completed --comment "Fixed in v<version>."
+done
+```
+
+Collect specific issue numbers from Phase 3 sub-agent summaries — do not close all open issues indiscriminately.
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | 3 sub-agents per server racing on `bun run rebuild` corrupts `dist/` | Pre-flight builds once; sub-agents skip rebuild in `mcp_start` |
+| 2 | Tmp file collisions between concurrent field-test sub-agents | Unique IDs per agent in helper path: `/tmp/<project>-field-test-<ID>.sh` |
+| 3 | Sub-agents file issues against `@cyanheads/mcp-ts-core` instead of the server | Restate explicitly in every Phase 1 prompt: "Do NOT file issues against mcp-ts-core" |
+| 4 | Multiple fix sub-agents editing the same server's files | Hard constraint: 1 sub-agent per server in Phase 3 |
+| 5 | Fix sub-agent can't live-verify due to API quota exhaustion | Accept fixes where the root cause is code-evident (wrong field path, missing guard); note that live verification was blocked by quota |
+| 6 | Sub-agents file noise issues (nits, style preferences, bikeshedding) | Noise filter instruction in every Phase 1 prompt; sub-agents self-filter before filing |
+| 7 | Field-test sub-agent reports success but didn't actually exercise the tool | Sub-agent must include actual tool call output in the summary; orchestrator spot-checks |
+| 8 | Wrap-up sub-agent collapses multi-fix diff into a single commit | Phase 6 prompt enumerates the commit structure — group by file, release commit on top |
+| 9 | Wrap-up sub-agent makes unplanned intermediate commits outside the planned structure | Prompt defines the exact commit shape; sub-agents must not invent extras |
+| 10 | Loop decision deferred to user when orchestrator has enough data | Orchestrator decides on evidence |
+| 11 | MCP Registry returns 502 transiently during publish | Retry up to 2x with backoff. First attempt may fail; second usually succeeds |
+| 12 | Private repos need upstream set before first push | Agents should use `git push -u origin main` if upstream is unset |
+
+## Checklist
+
+- [ ] Pre-flight: working trees clean, API keys present, issue templates exist, all targets build clean
+- [ ] Phase 1: field-test sub-agents launched with unique IDs, build-skip, orient blocks
+- [ ] Phase 1: sub-agents tore down servers and cleaned tmp files before reporting
+- [ ] Phase 2: issue counts verified against GH state
+- [ ] Phase 3: 1 sub-agent per server (hard constraint), priority order followed, exit gate (devcheck + test) green
+- [ ] Phase 3: GH issues commented with fix details
+- [ ] Phase 4: verify pass — code-simplify (if applicable) + re-field-test, actual outputs in summary
+- [ ] Phase 5: loop decision made on evidence
+- [ ] Phase 6 (if releasing): version bumped, fix commits + release commit, annotated tag, scope matches private/public status
+- [ ] Phase 7 (if releasing): fixed issues closed; skipped issues remain open
+- [ ] Post-workflow verification: `git ls-remote --tags origin`, `npm view <pkg>@<version>` if public, GH release artifacts attached
+- [ ] Tag/release quality review: tag subject omits version number, structured markdown, no marketing adjectives, issue backlinks present

package/skills/orchestrations/workflows/fix-wrapup-release.md

@@ -0,0 +1,175 @@
+---
+name: fix-wrapup-release
+description: >
+  Workflow for landing known work (handoff document findings, tracked GH issues, observed gaps) and shipping it: fix → optional simplify and field-test verification → wrap-up → release across one or more MCP server projects. Generalizes "I have known issues to fix and ship" regardless of how the issues were surfaced. Chains the `field-test`, `report-issue-local`, `code-simplifier`, `git-wrapup`, and `release-and-publish` skills. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: workflow
+---
+
+# Fix + Wrap-up + Release Workflow
+
+Use after reading `../SKILL.md`. Use this workflow when there's a clear list of known fixes to apply and ship — sourced from a handoff document, tracked GH issues, observed gaps you've already validated, or any combination.
+
+## Trigger contexts
+
+The input varies but the workflow is the same. Read the inputs into a common shape before kicking off:
+
+| Source | Shape it as |
+|:---|:---|
+| Handoff document (numbered findings, repro steps, acceptance criteria) | Validate each finding live in Phase 1a; file each valid one as a GH issue via `report-issue-local`; skip invalidated findings |
+| GH issues already filed | Use as-is. Read each with `gh issue view N --comments` to capture the full thread (the body alone misses clarifications and decision updates) |
+| Observed gap or casual report ("I noticed this", "fix the description on tool X") | If material enough to ship in a release, file a GH issue first to capture rationale and create an audit trail. Trivial typo-fix-and-ship can skip the issue step. |
+
+The validation/filing step is the difference between "input is a hypothesis" (handoff) and "input is verified" (tracked GH issues). The rest of the workflow is identical.
+
+## When applicable
+
+- One or more existing servers have known work to land — issues, handoff findings, or specific verified bugs
+- The work is the deliverable; the workflow ends in a commit + tag and (optionally) a release
+- N = 1 (single-server handoff) and N > 1 (multi-server fix batch) both apply
+
+For unsourced QA — where the bugs are unknown until you test — use `field-test-fix.md` instead; that workflow includes the field-test discovery phase first.
+
+## Tier 1 skills referenced
+
+| Phase | Tier 1 skill(s) |
+|:---|:---|
+| Validate (handoff input only) | `skills/field-test/SKILL.md` + `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
+| Fix | (No single skill — sub-agent reads issues, validates, fixes) |
+| Verify | `skills/field-test/SKILL.md` (live verification) + `skills/code-simplifier/SKILL.md` (optional) |
+| Wrap-up | `skills/git-wrapup/SKILL.md` |
+| Release | `skills/release-and-publish/SKILL.md` |
+
+## Pre-flight
+
+Per target:
+
+1. **Identify issues** — collect GH issue numbers to fix, the handoff document, or the explicit gap description. Read each issue with `gh issue view N --comments` to capture the full thread.
+2. **Clean working tree** — `git status --short` must be empty
+3. **Current version** — `git describe --tags --abbrev=0`, `grep '"version"' package.json`
+4. **Repo visibility** — `gh repo view --json visibility -q '.visibility'`. Determines wrap-up scope.
+5. **Build** — `bun run rebuild` per target. All must pass before Phase 1.
+
+## 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 |
+|:--|:---|:---|:---|
+| 1a | Validate (conditional) | Each handoff finding field-tested live; valid ones filed as GH issues; invalidated ones reported back with reason. If zero validate, workflow stops | one sub-agent per target |
+| 1b | Fix | Per target: targeted issues fixed in source, tests updated/added, `devcheck` + `rebuild` + `test` green, each fixed issue commented with fix details, working tree dirty for review | parallel fanout (one sub-agent per target — hard constraint) |
+| 2 | Verify | Per target: full diff cold-reviewed; simplified if warranted; each fix re-exercised against the running server with actual tool output in the summary | parallel fanout |
+| 3 | Wrap-up + release | Per target: fixes split into per-file commits with a release commit on top; annotated tag; published per repo visibility; tag annotation is structured markdown with issue backlinks | parallel fanout (Bash git only) |
+| 4 | Issue cleanup | Every GH issue that shipped a fix closed with "Fixed in v\<version\>" comment | orchestrator (serial) |
+
+Phase 1a is conditional — only runs when the input is a handoff document or otherwise unvalidated. When the input is already tracked GH issues, skip directly to Phase 1b. The release portion of Phase 3 is conditional on user authorization to ship.
+
+## Phase notes
+
+### Phase 1a: Validate (handoff input)
+One sub-agent per target. The sub-agent:
+1. Field-tests each handoff claim against the running server (project-specific helpers per the `field-test` skill)
+2. For validated findings, traces the relevant source to confirm shape of fix
+3. Reads `.github/ISSUE_TEMPLATE/` first to understand the repo's issue conventions
+4. Files one GH issue per validated finding using `report-issue-local` patterns
+5. Reports back: validated (with GH issue links and one-line reason), invalidated (with why), and observations not in the original handoff
+
+**Noise filter:** every filed issue must pass "Would a maintainer coming to this cold say 'yes, this needs fixing'?"
+
+**Do not file against `@cyanheads/mcp-ts-core`** unless the bug is clearly in the framework — file against the server's own repo.
+
+**Unique field-test ID** in helper file path: `/tmp/<project>-handoff-<5CHAR>.sh`.
+
+If zero findings validate, report to the user and stop the workflow.
+
+### Phase 1b: Fix
+**One sub-agent per target — hard constraint** (no file-locking; concurrent edits to the same `src/` conflict).
+
+Each sub-agent:
+1. Reads all open issues for its target via `gh issue view N --comments` (full thread — body alone misses clarifications)
+2. **Validates each issue against source code** — the issue's analysis or proposed approach may be wrong; sub-agent applies judgment about the right fix and notes any deviation in its GH comment
+3. Prioritizes: security → crashes → bugs → enhancements → docs/chore
+4. Implements fixes using the best modern approach (the GH issue is input, not a spec)
+5. Updates or adds tests as needed
+6. Exit gate: `bun run devcheck` + `bun run rebuild` + `bun run test` all pass before reporting completion
+7. Comments on each fixed GH issue with a concise fix summary (cite file paths)
+8. Leaves everything uncommitted
+
+**Constraints to restate:**
+- Surgical fixes only — don't refactor surrounding code unless the fix requires it
+- If a fix is disproportionate (major architecture change), note it on the issue and skip
+- The exit gate is non-negotiable — do not report completion if any of devcheck/rebuild/test is red
+
+### Phase 2: Verify
+Fresh sub-agent per target, reads the full `git diff` cold. Two passes:
+
+1. **Code-simplify** — read `code-simplifier`, review the diff through that lens (over-engineering, unnecessary abstractions, redundant guards, style mismatches with surrounding code). Apply cleanup if warranted; skip if changes are minimal — don't run as ceremony.
+2. **Re-field-test** — spin up the server, run the repro steps from each fixed issue, include actual tool call output in the summary. A fix that compiles but wasn't verified against a running server is not done.
+
+Exit gate: `bun run devcheck && bun run rebuild && bun run test`.
+
+### Phase 3: Wrap-up + release
+Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`.
+
+**Orchestrator responsibility:** before spawning Phase 3 sub-agents, collect all open GH issue numbers per target (`gh issue list -R <owner>/<repo> --state open --json number,title`) and include them in each sub-agent's prompt. Phase 3 sub-agents have no context from prior phases — they need the explicit issue list to know what to close.
+
+**Commit structure.** Fixes are NOT collapsed into a single commit:
+1. Analyze the diff — understand which fixes touch which files
+2. Group by file boundaries — fixes sharing a file ship in the same commit
+3. Commit each group: `fix(scope): description` (Conventional Commits)
+4. Release commit on top: `chore(release): v<version>` — version bump + changelog + regenerated artifacts
+5. Tag the release commit
+
+The tag annotation and changelog cover ALL fixes — the commit split is about git history, not release notes.
+
+**Version bump.** Default **patch** for bug-fix releases. **Minor** when enhancements are included.
+
+**Wrap-up scope.** Determined by repo 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). |
+
+**Tag annotations** are for end users — internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in commit bodies, not the tag annotation.
+
+### Phase 4: Issue cleanup
+Close issues that shipped fixes — only those. Skipped issues stay open.
+
+```bash
+for n in <fixed-issue-numbers>; do
+  gh issue close "$n" -R "<owner>/<repo>" --reason completed --comment "Fixed in v<version>."
+done
+```
+
+## Workflow-specific gotchas
+
+| # | Gotcha | Mitigation |
+|:--|:-------|:-----------|
+| 1 | Multiple fix sub-agents editing the same server's `src/` | Hard constraint: 1 sub-agent per server in Phase 1b |
+| 2 | Fix sub-agent "fixed" an issue but the change is a band-aid | Orchestrator gate after Phase 1b reviews approach, not just "does it compile" |
+| 3 | Fix sub-agent doesn't update tests for schema changes | Exit gate requires tests pass; sub-agent must update/add tests before finishing |
+| 4 | Field-test in Phase 2 fails but sub-agent reports success | Sub-agent must include actual tool call output in summary; orchestrator spot-checks |
+| 5 | Code-simplify removes intentional complexity | Orchestrator gate after Phase 2 reviews the full diff |
+| 6 | Wrap-up sub-agent collapses multi-fix diff into one commit | Phase 3 prompt enumerates the commit structure |
+| 7 | Wrap-up sub-agent makes unplanned intermediate commits outside the planned structure | Prompt defines exact commit shape; agents must not invent extras |
+| 8 | Reading `gh issue view N` alone misses thread context where decisions were updated | Always include `--comments` |
+| 9 | MCP Registry returns 502 transiently during publish | Retry up to 2x with backoff |
+| 10 | Phase 1a sub-agent validates an issue that's actually a misunderstanding | Sub-agent must field-test, not just read the claim — live verification catches false positives |
+
+## Checklist
+
+- [ ] Pre-flight: issues identified per target (or handoff captured), working trees clean, builds pass
+- [ ] Phase 1a (if handoff): findings validated live, GH issues filed for valid findings, invalidated reported back
+- [ ] Phase 1b: fix sub-agents complete — fixes implemented, tests updated, GH issues commented, exit gate green
+- [ ] Orchestrator gate after Phase 1b: diffs reviewed, devcheck + tests green
+- [ ] Phase 2: verify sub-agents complete — code-simplify (if applicable), re-field-test with actual outputs in summary
+- [ ] Orchestrator gate after Phase 2: simplified diff reviewed, field-test claims verified
+- [ ] Phase 3: version bumped, fix commits + release commit, annotated tag per target — scope matches private/public status
+- [ ] Phase 3: published per scope (push, npm if public, MCP Registry if applicable, GH release, Docker if applicable)
+- [ ] Phase 4: fixed issues closed; skipped issues remain open
+- [ ] Post-workflow verification: `git ls-remote --tags origin`, `npm view <pkg>@<version>` if public, GH release artifacts attached
+- [ ] Tag/release quality review: tag subject omits version number, structured markdown, no marketing adjectives, issue backlinks present