@cyanheads/mcp-ts-core 0.9.0 → 0.9.2

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.4"
+  version: "2.5"
   audience: external
   type: debug
 ---
@@ -27,115 +27,117 @@ This skill drives an HTTP server because curl + JSON-RPC is the most reliable ha
 
 ### 1. Start the server
 
-Write the helper to `/tmp/mcp-field-test.sh` once, then source it in every subsequent Bash call. Helper keeps PID / URL / session id in a per-`$PWD` state file (`/tmp/mcp-field-test-<hash>.env`) so state survives across tool invocations and concurrent field-tests in different project trees don't clobber each other.
+Generate a 10-character alphanumeric ID (e.g. `9DJ73-K103L`) and write the helper to `/tmp/<project-name>-field-test-<ID>.sh`. Use that exact path in every subsequent Bash call. **Two agents in the same project tree must pick different IDs** — that's what keeps their helper files, server logs, and call scratch from colliding.
+
+The helper itself is **stateless** — every function takes the IDs it needs (server `pid`, server `url`, MCP `sid`, server log path) as positional args. `mcp_start` prints them; the agent threads them through every later call. No env vars, no shared state files.
 
 ```bash
-cat > /tmp/mcp-field-test.sh <<'HELPER_EOF'
+# Pick your ID — example below uses 9DJ73-K103L. Substitute your own.
+# (Helper path also encodes the project name so /tmp/ stays grep-friendly.)
+cat > /tmp/<project-name>-field-test-9DJ73-K103L.sh <<'HELPER_EOF'
 #!/bin/bash
-# Field-test helper: manage an MCP HTTP server + JSON-RPC session across shell calls.
+# Field-test helper: stateless wrappers around an MCP HTTP server + JSON-RPC
+# session. Every function takes the IDs it needs as positional args — the agent
+# threads pid/url/sid/log through each call rather than relying on a state
+# file or env vars (the Bash tool wipes shell state between calls, and a
+# pointer file would race the same way two agents race on shared state).
+# See https://github.com/cyanheads/mcp-ts-core/issues/90, #144.
+#
 # Surfaces failures aggressively — field test is for finding things that fail,
 # so the helper auto-tails logs and prints HTTP status/body on errors instead
 # of swallowing them.
-#
-# State and log paths are namespaced by an 8-char hash of $PWD so concurrent
-# field-tests across different project trees don't clobber each other (see
-# https://github.com/cyanheads/mcp-ts-core/issues/90).
-PREFIX="/tmp/mcp-field-test-$(printf '%s' "$PWD" | shasum | cut -c1-8)"
-STATE_FILE="${PREFIX}.env"
-BUILD_LOG="${PREFIX}-build.log"
-SERVER_LOG="${PREFIX}-server.log"
-[ -f "$STATE_FILE" ] && . "$STATE_FILE"
 
+# Usage: mcp_start /path/to/server
+# Builds, starts the HTTP server in the background, waits for the listen line,
+# and prints: ready pid=<n> url=<u> port=<n> log=<path>
+# Capture these — every later helper takes them as args.
 mcp_start() {
   local dir="${1:-$PWD}"
-  echo "building $dir ..."
-  if ! (cd "$dir" && bun run rebuild) >"$BUILD_LOG" 2>&1; then
-    echo "BUILD FAILED — last 30 lines of $BUILD_LOG:"
-    tail -30 "$BUILD_LOG"
+  local build_log; build_log=$(mktemp /tmp/mcp-field-test-build.XXXXXX)
+  echo "building $dir ..." >&2
+  if ! (cd "$dir" && bun run rebuild) >"$build_log" 2>&1; then
+    echo "BUILD FAILED — last 30 lines of $build_log:" >&2
+    tail -30 "$build_log" >&2
     return 1
   fi
-  echo "starting server ..."
-  (cd "$dir" && bun run start:http) >"$SERVER_LOG" 2>&1 &
+  rm -f "$build_log"
+  local server_log; server_log=$(mktemp /tmp/mcp-field-test-server.XXXXXX)
+  echo "starting server ..." >&2
+  (cd "$dir" && bun run start:http) >"$server_log" 2>&1 &
   local pid=$!
   local line=""
   for _ in $(seq 1 40); do
-    line=$(grep -Eo 'listening at http://[^" ]+/mcp' "$SERVER_LOG" | head -1)
+    line=$(grep -Eo 'listening at http://[^" ]+/mcp' "$server_log" | head -1)
     [ -n "$line" ] && break
     sleep 0.25
   done
   if [ -z "$line" ]; then
-    echo "server failed to start within 10s — last 30 lines of $SERVER_LOG:"
-    tail -30 "$SERVER_LOG"
+    echo "server failed to start within 10s — last 30 lines of $server_log:" >&2
+    tail -30 "$server_log" >&2
     kill "$pid" 2>/dev/null
+    rm -f "$server_log"
     return 1
   fi
   local url="${line#listening at }"
   local port; port=$(echo "$url" | sed -E 's|.*:([0-9]+)/.*|\1|')
-  cat > "$STATE_FILE" <<EOF
-export MCP_PID=$pid
-export MCP_URL=$url
-export MCP_PORT=$port
-EOF
-  . "$STATE_FILE"
-  echo "ready pid=$pid url=$url"
+  echo "ready pid=$pid url=$url port=$port log=$server_log"
 }
 
+# Usage: mcp_init <url>
+# Runs `initialize`, sends `notifications/initialized`, prints: ready sid=<id>
 mcp_init() {
-  [ -z "$MCP_URL" ] && { echo "run mcp_start first"; return 1; }
-  local hdr="${PREFIX}-init-headers.txt"
-  local body_file="${PREFIX}-init-body.txt"
-  local status
-  status=$(curl -sS -D "$hdr" -o "$body_file" -w '%{http_code}' -X POST "$MCP_URL" \
+  local url="$1"
+  [ -z "$url" ] && { echo "usage: mcp_init <url>" >&2; return 1; }
+  local hdr; hdr=$(mktemp)
+  local body_file; body_file=$(mktemp)
+  local code
+  code=$(curl -sS -D "$hdr" -o "$body_file" -w '%{http_code}' -X POST "$url" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
-    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.3"}}}')
+    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.5"}}}')
   local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
   if [ -z "$sid" ]; then
-    echo "init failed — HTTP $status, no Mcp-Session-Id header returned"
-    echo "--- response body ---"
-    cat "$body_file"
-    echo "--- response headers ---"
-    cat "$hdr"
+    echo "init failed — HTTP $code, no Mcp-Session-Id header returned" >&2
+    echo "--- response body ---" >&2
+    cat "$body_file" >&2
+    echo "--- response headers ---" >&2
+    cat "$hdr" >&2
+    rm -f "$hdr" "$body_file"
     return 1
   fi
-  cat > "$STATE_FILE" <<EOF
-export MCP_PID=$MCP_PID
-export MCP_URL=$MCP_URL
-export MCP_PORT=$MCP_PORT
-export MCP_SID=$sid
-EOF
-  . "$STATE_FILE"
-  curl -sS -X POST "$MCP_URL" \
+  curl -sS -X POST "$url" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Mcp-Session-Id: $sid" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
-  echo "session=$sid (HTTP $status)"
+  rm -f "$hdr" "$body_file"
+  echo "ready sid=$sid (HTTP $code)"
 }
 
-# Usage: mcp_call METHOD [JSON_PARAMS]
+# Usage: mcp_call <url> <sid> <method> [JSON_PARAMS]
 # Prints the JSON-RPC response. SSE framing is stripped when present; on
 # non-SSE responses the raw body is printed instead so plain-JSON error
 # replies (HTTP 4xx/5xx) still surface. Pipe to `jq`.
 mcp_call() {
-  [ -z "$MCP_SID" ] && { echo "run mcp_init first"; return 1; }
-  local method="$1"; local params="${2:-}"
+  local url="$1"; local sid="$2"; local method="$3"; local params="${4:-}"
+  [ -z "$url" ] || [ -z "$sid" ] || [ -z "$method" ] && { echo "usage: mcp_call <url> <sid> <method> [params]" >&2; return 1; }
   local body
   if [ -z "$params" ]; then
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s"}' "$RANDOM" "$method")
   else
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s","params":%s}' "$RANDOM" "$method" "$params")
   fi
-  local resp_file="${PREFIX}-call-body.txt"
-  local status
-  status=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$MCP_URL" \
+  local resp_file; resp_file=$(mktemp)
+  local code
+  code=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$url" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
-    -H "Mcp-Session-Id: $MCP_SID" \
+    -H "Mcp-Session-Id: $sid" \
     -d "$body")
-  if [ "$status" -ge 400 ]; then
-    echo "HTTP $status from $method — response:" >&2
+  if [ "$code" -ge 400 ]; then
+    echo "HTTP $code from $method — response:" >&2
     cat "$resp_file" >&2
+    rm -f "$resp_file"
     return 1
   fi
   local sse; sse=$(sed -n 's/^data: //p' "$resp_file")
@@ -144,46 +146,49 @@ mcp_call() {
   else
     cat "$resp_file"
   fi
+  rm -f "$resp_file"
 }
 
-# Tail the server log. Useful when a call surprises you — pino startup banner,
-# definition lint diagnostics, request handler errors, upstream calls, and
-# rate-limit warnings live in the per-session server log.
-# Usage: mcp_log [N]   (default: 50 lines)
+# Usage: mcp_log <server-log-path> [N]   (default: 50 lines)
+# Tail the per-server log printed by mcp_start. Useful when a call surprises
+# you — pino startup banner, definition lint diagnostics, request handler
+# errors, upstream calls, and rate-limit warnings all land here.
 mcp_log() {
-  local n="${1:-50}"
-  tail -n "$n" "$SERVER_LOG"
+  local log="$1"; local n="${2:-50}"
+  [ -z "$log" ] && { echo "usage: mcp_log <log-path> [n]" >&2; return 1; }
+  tail -n "$n" "$log"
 }
 
+# Usage: mcp_stop <pid> [server-log-path]
+# Kills the background server. Removes the server log if a path is given.
 mcp_stop() {
-  if [ -z "$MCP_PID" ]; then
-    rm -f "$STATE_FILE"
-    echo "no PID to stop"
-    return 0
-  fi
-  kill "$MCP_PID" 2>/dev/null
+  local pid="$1"; local log="${2:-}"
+  [ -z "$pid" ] && { echo "usage: mcp_stop <pid> [log-path]" >&2; return 1; }
+  kill "$pid" 2>/dev/null
   for _ in $(seq 1 12); do
-    kill -0 "$MCP_PID" 2>/dev/null || break
+    kill -0 "$pid" 2>/dev/null || break
     sleep 0.25
   done
-  if kill -0 "$MCP_PID" 2>/dev/null; then
-    echo "PID $MCP_PID didn't exit on SIGTERM — sending SIGKILL"
-    kill -9 "$MCP_PID" 2>/dev/null
+  if kill -0 "$pid" 2>/dev/null; then
+    echo "PID $pid didn't exit on SIGTERM — sending SIGKILL"
+    kill -9 "$pid" 2>/dev/null
     sleep 0.5
   fi
-  if kill -0 "$MCP_PID" 2>/dev/null; then
-    echo "WARNING: PID $MCP_PID still alive after SIGKILL"
+  if kill -0 "$pid" 2>/dev/null; then
+    echo "WARNING: PID $pid still alive after SIGKILL"
   else
-    echo "stopped pid=$MCP_PID"
+    echo "stopped pid=$pid"
   fi
-  rm -f "$STATE_FILE"
+  [ -n "$log" ] && rm -f "$log"
 }
 HELPER_EOF
 
-. /tmp/mcp-field-test.sh
+. /tmp/<project-name>-field-test-9DJ73-K103L.sh
 mcp_start /absolute/path/to/server   # replace with the target server
 ```
 
+Capture `pid`, `url`, `port`, `log` from the `mcp_start` output — every later call takes them as positional args. Two agents running concurrently in the same project tree each pick their own ID, so their helper paths, server logs, and call scratch never share a name.
+
 **Notes**
 
 - `MCP_HTTP_PORT` is a *starting* port — the server auto-increments if taken. Helper parses the real URL from the log (`HTTP transport listening at ...`).
@@ -193,19 +198,19 @@ mcp_start /absolute/path/to/server   # replace with the target server
 ### 2. Initialize the session
 
 ```bash
-. /tmp/mcp-field-test.sh
-mcp_init
+. /tmp/<project-name>-field-test-<ID>.sh
+mcp_init <url-from-mcp_start>
 ```
 
-Runs `initialize`, captures the session id, sends `notifications/initialized`.
+Runs `initialize`, sends `notifications/initialized`, prints `sid=<id>` to capture for `mcp_call`.
 
 ### 3. Surface the catalog
 
 ```bash
-. /tmp/mcp-field-test.sh
-mcp_call tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema}'
-mcp_call resources/list | jq '.result.resources[] | {uri, name, mimeType}'
-mcp_call prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
+. /tmp/<project-name>-field-test-<ID>.sh
+mcp_call <url> <sid> tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema}'
+mcp_call <url> <sid> resources/list | jq '.result.resources[] | {uri, name, mimeType}'
+mcp_call <url> <sid> prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
 ```
 
 Present a compact catalog to the user: each definition's name + 1-line description. Flag vague or missing descriptions as you go — those feed into the report. Use this to build the test plan.
@@ -262,7 +267,7 @@ Use `TaskCreate` — one task per definition. Mark complete as you go. Don't bat
 
 For each call, capture: input sent, response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
 
-When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/mcp-field-test.sh && mcp_log` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in the per-session server log (read via `mcp_log`) rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone.
+When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/<project-name>-field-test-<ID>.sh && mcp_log <log>` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in the per-server log (read via `mcp_log`) rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone.
 
 **Interpreting responses**
 
@@ -275,11 +280,12 @@ When a call surprises you — slow, hangs, returns terse output, surfaces an unh
 ### 6. Tear down
 
 ```bash
-. /tmp/mcp-field-test.sh
-mcp_stop
+. /tmp/<project-name>-field-test-<ID>.sh
+mcp_stop <pid> <log>
+rm -f /tmp/<project-name>-field-test-<ID>.sh
 ```
 
-Kills the background server, clears state. Do this *before* writing the report so nothing leaks into the next session.
+Kills the background server, removes the server log, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session.
 
 ### 7. Report
 

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "2.1"
+  version: "2.2"
   audience: external
   type: workflow
 ---
@@ -202,6 +202,8 @@ In **Mode B**, the user already ran rebuild + test before invoking this skill, b
 
 Fix anything that fails. Re-run until clean.
 
+**Transitive advisory triage.** If `bun audit` (inside devcheck) reports a vulnerability in a transitive dep, run `bun run audit:refresh` before treating it as real. Bun's `bun update` is sticky on transitive resolutions — it keeps lockfile entries even when a parent's range allows a newer patched version. `audit:refresh` deletes `bun.lock`, reinstalls, and re-audits; if the advisory disappears, it was a stale-lockfile false positive (commit the refreshed lockfile). If it survives, it's real — patch via `package.json` `overrides` or nudge upstream.
+
 ### 8. Summary
 
 Present a concise numbered summary to the user:

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

@@ -0,0 +1,123 @@
+---
+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.0"
+  audience: external
+  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 |
+   | **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 |
+   | **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.
+
+## 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 |
+| **Release pass** | `references/release-pass.md` | Existing server(s) have committed/staged work that needs to ship as a new version — verification → README polish → wrapup (version + changelog + commit + tag) → publish (npm / MCP Registry / GHCR via `release-and-publish`) → optional GH issue closure |
+
+Scenarios chain naturally: a maintenance pass often runs into a release pass; a greenfield build-out's final phase is effectively a release pass. Pick the reference for the current scope and chain explicitly if more work follows.
+
+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." |
+
+## 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 two: 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.