@cyanheads/mcp-ts-core 0.9.9 → 0.9.11

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

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