@tyroneross/build-loop 0.30.3

package/skills/logging-tracer/references/stack-templates.md

@@ -0,0 +1,274 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Stack Templates — Logging & Tracing
+
+## Node.js / TypeScript (Tier 1)
+
+```typescript
+// lib/logger.ts
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+const MIN_LEVEL: LogLevel = (process.env.LOG_LEVEL as LogLevel) || 'info';
+
+function log(level: LogLevel, op: string, data?: Record<string, unknown>) {
+  if (LEVELS[level] < LEVELS[MIN_LEVEL]) return;
+  const entry = { ts: Date.now(), level, op, ...data };
+  process.stderr.write(JSON.stringify(entry) + '\n');
+}
+
+async function traced<T>(op: string, fn: () => Promise<T>, ctx?: Record<string, unknown>): Promise<T> {
+  const start = Date.now();
+  try {
+    const result = await fn();
+    log('info', op, { dur_ms: Date.now() - start, ...ctx });
+    return result;
+  } catch (err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    log('error', op, { dur_ms: Date.now() - start, error: { name: e.name, message: e.message }, ...ctx });
+    throw err;
+  }
+}
+
+export { log, traced, LogLevel };
+```
+
+### Usage
+
+```typescript
+import { log, traced } from './lib/logger';
+
+// Direct log
+log('info', 'server:start', { port: 3000 });
+
+// Wrap async operation
+const user = await traced('db:getUser', () => db.user.findUnique({ where: { id } }), { userId: id });
+
+// Error handling
+try {
+  await riskyOperation();
+} catch (err) {
+  log('error', 'payment:charge', {
+    error: { name: err.name, message: err.message },
+    customerId,
+  });
+}
+```
+
+## Node.js / TypeScript (Tier 2 — File Output)
+
+```typescript
+// lib/logger.ts
+import { appendFileSync, statSync, renameSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+const MIN_LEVEL: LogLevel = (process.env.LOG_LEVEL as LogLevel) || 'info';
+
+const LOG_DIR = join(process.cwd(), 'logs');
+const LOG_FILE = join(LOG_DIR, 'app.jsonl');
+const MAX_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_ROTATED = 2;
+
+try { mkdirSync(LOG_DIR, { recursive: true }); } catch {}
+
+function write(entry: Record<string, unknown>) {
+  try {
+    appendFileSync(LOG_FILE, JSON.stringify(entry) + '\n');
+    rotate();
+  } catch {}
+}
+
+function rotate() {
+  try {
+    const stat = statSync(LOG_FILE);
+    if (stat.size < MAX_SIZE) return;
+    for (let i = MAX_ROTATED; i >= 1; i--) {
+      try { renameSync(`${LOG_FILE}.${i}`, `${LOG_FILE}.${i + 1}`); } catch {}
+    }
+    renameSync(LOG_FILE, `${LOG_FILE}.1`);
+  } catch {}
+}
+
+function log(level: LogLevel, op: string, data?: Record<string, unknown>) {
+  if (LEVELS[level] < LEVELS[MIN_LEVEL]) return;
+  write({ ts: Date.now(), level, op, ...data });
+}
+
+async function traced<T>(op: string, fn: () => Promise<T>, ctx?: Record<string, unknown>): Promise<T> {
+  const start = Date.now();
+  try {
+    const result = await fn();
+    log('info', op, { dur_ms: Date.now() - start, ...ctx });
+    return result;
+  } catch (err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    log('error', op, { dur_ms: Date.now() - start, error: { name: e.name, message: e.message }, ...ctx });
+    throw err;
+  }
+}
+
+export { log, traced };
+```
+
+## Python (Tier 1)
+
+```python
+# lib/logger.py
+import json, time, sys, os, functools
+from typing import Any
+
+LEVELS = {'debug': 0, 'info': 1, 'warn': 2, 'error': 3}
+MIN_LEVEL = os.environ.get('LOG_LEVEL', 'info')
+
+def log(level: str, op: str, **data: Any):
+    if LEVELS.get(level, 0) < LEVELS.get(MIN_LEVEL, 1):
+        return
+    entry = {'ts': int(time.time() * 1000), 'level': level, 'op': op, **data}
+    print(json.dumps(entry), file=sys.stderr)
+
+def traced(op: str, **ctx):
+    def decorator(fn):
+        @functools.wraps(fn)
+        async def async_wrapper(*args, **kwargs):
+            start = time.time()
+            try:
+                result = await fn(*args, **kwargs)
+                log('info', op, dur_ms=int((time.time() - start) * 1000), **ctx)
+                return result
+            except Exception as e:
+                log('error', op, dur_ms=int((time.time() - start) * 1000),
+                    error={'name': type(e).__name__, 'message': str(e)}, **ctx)
+                raise
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args, **kwargs):
+            start = time.time()
+            try:
+                result = fn(*args, **kwargs)
+                log('info', op, dur_ms=int((time.time() - start) * 1000), **ctx)
+                return result
+            except Exception as e:
+                log('error', op, dur_ms=int((time.time() - start) * 1000),
+                    error={'name': type(e).__name__, 'message': str(e)}, **ctx)
+                raise
+
+        import asyncio
+        if asyncio.iscoroutinefunction(fn):
+            return async_wrapper
+        return sync_wrapper
+    return decorator
+```
+
+### Usage
+
+```python
+from lib.logger import log, traced
+
+log('info', 'server:start', port=8000)
+
+@traced('db:get_user')
+async def get_user(user_id: str):
+    return await db.users.find_one({"_id": user_id})
+```
+
+## Go (Tier 1)
+
+```go
+// pkg/logger/logger.go
+package logger
+
+import (
+    "encoding/json"
+    "fmt"
+    "os"
+    "strings"
+    "time"
+)
+
+var levels = map[string]int{"debug": 0, "info": 1, "warn": 2, "error": 3}
+var minLevel = getEnvOr("LOG_LEVEL", "info")
+
+type Entry struct {
+    Ts    int64                  `json:"ts"`
+    Level string                 `json:"level"`
+    Op    string                 `json:"op"`
+    DurMs *int64                 `json:"dur_ms,omitempty"`
+    Data  map[string]interface{} `json:"data,omitempty"`
+}
+
+func Log(level, op string, data map[string]interface{}) {
+    if levels[level] < levels[minLevel] { return }
+    entry := Entry{Ts: time.Now().UnixMilli(), Level: level, Op: op, Data: data}
+    b, _ := json.Marshal(entry)
+    fmt.Fprintln(os.Stderr, string(b))
+}
+
+func Traced(op string, fn func() error) error {
+    start := time.Now()
+    if err := fn(); err != nil {
+        dur := time.Since(start).Milliseconds()
+        Log("error", op, map[string]interface{}{"dur_ms": dur, "error": err.Error()})
+        return err
+    }
+    dur := time.Since(start).Milliseconds()
+    Log("info", op, map[string]interface{}{"dur_ms": dur})
+    return nil
+}
+
+func getEnvOr(key, fallback string) string {
+    if v := os.Getenv(key); v != "" { return strings.ToLower(v) }
+    return fallback
+}
+```
+
+## Node.js (Tier 3 — OpenTelemetry)
+
+```typescript
+// lib/tracing.ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { TraceIdRatioBasedSampler, ParentBasedSampler } from '@opentelemetry/sdk-trace-base';
+
+// Prevent duplicate init in hot-reload
+const INIT_KEY = Symbol.for('otel.initialized');
+if ((globalThis as any)[INIT_KEY]) {
+  console.warn('[tracing] Already initialized, skipping');
+} else {
+  const isDev = process.env.NODE_ENV !== 'production';
+
+  const sdk = new NodeSDK({
+    resource: new Resource({ [ATTR_SERVICE_NAME]: process.env.SERVICE_NAME || 'my-app' }),
+    traceExporter: new OTLPTraceExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
+    }),
+    sampler: new ParentBasedSampler({
+      root: new TraceIdRatioBasedSampler(isDev ? 1.0 : 0.1),
+    }),
+    instrumentations: [getNodeAutoInstrumentations()],
+  });
+
+  sdk.start();
+  (globalThis as any)[INIT_KEY] = true;
+
+  process.on('SIGTERM', () => sdk.shutdown());
+}
+```
+
+### Required packages
+```
+@opentelemetry/sdk-node
+@opentelemetry/exporter-trace-otlp-http
+@opentelemetry/auto-instrumentations-node
+@opentelemetry/resources
+@opentelemetry/semantic-conventions
+```
+
+### Free backends
+- **Jaeger** (local): `docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one`
+- **SigNoz** (self-hosted): Follow docs at signoz.io
+- **Grafana Tempo** (self-hosted): Pair with Grafana for UI

package/skills/logging-tracer-bridge/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: build-loop:logging-tracer-bridge
+description: Use when the bundled logging-tracer skill signals insufficient tier-selection or codegen, or the user asks for "extended observability" or "cross-build log correlation". Optional escalation to standalone Coding Debugger for additional tracer backends and advanced placement intelligence.
+version: 0.3.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Logging-Tracer Bridge — Extended Capability Escalation
+
+As of build-loop 0.7.1 this bridge's role is **escalation, not primary coordination**. The orchestrator owns when-to-fire (Phase 1 Assess observability scan, Phase 5 Iterate reactive trigger on `evidence_gap`) and routes those phases to the bundled internal `build-loop:logging-tracer` skill, which owns tier selection, stack detection, codegen, the ephemeral-by-default policy (Mechanisms A and B), and code-placement rules.
+
+This bridge is the **secondary hop**: when the bundled logging-tracer decides it needs more than build-loop ships natively, it can invoke this bridge to delegate to standalone Coding Debugger (if installed) for extended observability tooling.
+
+## When this bridge is invoked
+
+By `build-loop:logging-tracer`, not the orchestrator. Calling sites:
+
+- `build-loop:logging-tracer` §"Extended capability" — when the project requires a tracer backend or placement intelligence beyond what build-loop ships (e.g., a downstream MCP-discoverable log sink that lives in the standalone plugin only)
+
+The orchestrator MUST NOT call this bridge directly. Orchestrator → `logging-tracer` skill → (optional) this bridge → standalone plugin.
+
+## Pre-flight (always run first)
+
+```
+if (!state.availablePlugins.codingDebugger) {
+  return { delegated: false, reason: "standalone Coding Debugger plugin not installed" }
+}
+```
+
+If false, the calling target skill continues with bundled-only capability.
+
+## Delegations available
+
+| Capability needed | Standalone Skill / MCP call |
+|---|---|
+| Extended tracer backends not in bundle | `Skill("coding-debugger:logging-tracer")` with `tier: <upstream-only>` |
+| Cross-build log correlation (e.g., correlation IDs across multiple build-loop runs) | standalone-only MCP tools |
+| Advanced placement intelligence (e.g., function-call graph aware insertion) | standalone-only assessor skills |
+
+The bridge passes through caller-supplied symptom + target-files + tier-hint, returns enriched data to `logging-tracer`. The target skill decides how to fold the extended result into its own codegen.
+
+## What this bridge does NOT do
+
+- Reimplement tier selection, stack detection, ephemeral mechanisms, or code placement — those live in `build-loop:logging-tracer`
+- Replace the orchestrator's when-to-fire policy (Phase 1 Assess scan, Phase 5 Iterate evidence_gap trigger) — that lives in `agents/build-orchestrator.md`
+- Introduce new logging dependencies without explicit user approval — that constraint stays in `logging-tracer`
+- Mutate build-loop's native `.build-loop/issues/` paths
+- Hard-fail when standalone is absent — pre-flight returns gracefully
+
+## State
+
+Optional bridge invocations are logged to `.build-loop/state.json.observability.escalations[]`:
+
+```json
+{ "ts": "ISO", "calledBy": "logging-tracer", "reason": "tier_3_otel_required", "delegated": true|false }
+```
+
+## Cross-references
+
+- `agents/build-orchestrator.md` — when-to-fire policy (Phase 1 Assess scan, Phase 5 Iterate)
+- `skills/logging-tracer/SKILL.md` — primary tier-selection / codegen / ephemeral-by-default skill
+- `skills/build-loop/fallbacks.md` §`debug` — local-only fallback when neither bundled nor standalone is reachable
+
+## History
+
+- v0.2.0 — coordination layer (orchestrator called this bridge as primary entry point for observability)
+- v0.7.0 — dissolved into `logging-tracer` skill + orchestrator (transient, in-flight architecture)
+- v0.7.1 — restored as **extended-capability escalation hop** with the architecture documented above

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: mcp-builder
+description: Use when building, packaging, or debugging an MCP server, adding MCP tools to a plugin, or working on .mcp.json, transport, or bundling. Pair with plugin-builder when the plugin exposes MCP tools.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# MCP Builder
+
+Build, bundle, and ship Model Context Protocol servers for Claude Code. Companion to `plugin-builder` — use both when the plugin exposes MCP tools.
+
+## Doc lookup — api-registry first
+
+Do **not** hardcode or fetch protocol-doc URLs from memory. Resolve them through the api-registry plugin's local doc cache:
+
+```
+/api-registry:docs mcp-spec "<your question>"        # MCP protocol spec
+/api-registry:docs mcp-ts-sdk "<your question>"      # TypeScript SDK
+/api-registry:docs mcp-python-sdk "<your question>"  # Python SDK
+/api-registry:docs anthropic-plugins-reference "<your question>"  # plugins-reference MCP section
+/api-registry:docs mcp-servers "<your question>"     # active reference servers
+```
+
+These registered services (`category: protocol`) carry authoritative `docs_url`s; api-registry answers from a dated local cache with a 7-day freshness contract and re-curates when stale. **Context7 MCP is the fallback only** — reached when no registered source exists. If the api-registry plugin is absent, fall back to the canonical URLs in the References section.
+
+## Security preflight (mandatory)
+
+Before writing any MCP server code, load `references/mcp-security.md` and run its inference + decision table. It produces a Tier 1 (always-mandatory) + Tier 2 (stage/type-gated) control checklist for *this* build. The checklist is **advisory** — it routes to the build-loop run report (Notes from judges / `state.json`), never an `AskUserQuestion` or hard gate. The `security-reviewer` agent grades the finished diff against the same matrix during Phase 4 Review-A.
+
+## Scope split with plugin-builder
+
+| Concern | Skill |
+|---|---|
+| Plugin directory layout, `plugin.json`, marketplace publishing | `plugin-builder` |
+| MCP server implementation (protocol, tools, transport) | **this skill** |
+| `.mcp.json` schema inside a plugin | both — schema lives in `plugin-builder/references/plugin-hygiene-lessons.md` |
+| Bundling strategy (`tsup` vs `tsc` vs committed `dist/`) | **this skill** |
+| Standalone MCP debugging | **this skill** |
+
+## When to build an MCP server vs a hook vs a skill
+
+| Use case | Choose |
+|---|---|
+| Expose a local database, filesystem, or API to Claude as callable tools | **MCP server** |
+| React to Claude events (post-tool, session-stop, etc.) without exposing tools | **Hook** |
+| Guide Claude with instructions/knowledge, no tool exposure | **Skill** |
+| Wrap an existing CLI so Claude can invoke it | **MCP server** (thin wrapper) or **plugin bin/** if the CLI is already stable |
+
+Don't build an MCP server when a skill + bash would suffice. The overhead is a separate process per server, JSON-RPC framing, and a config schema that's easy to get wrong.
+
+## Server scaffold (TypeScript + stdio)
+
+Use the official SDK. Stdio transport is default for Claude Code plugins.
+
+```ts
+// src/mcp/server.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'my-plugin', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'echo',
+      description: 'Echo a message back',
+      inputSchema: {
+        type: 'object',
+        properties: { message: { type: 'string' } },
+        required: ['message'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name === 'echo') {
+    return { content: [{ type: 'text', text: String(req.params.arguments?.message) }] };
+  }
+  throw new Error(`Unknown tool: ${req.params.name}`);
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[my-plugin] MCP server started'); // stderr, not stdout
+```
+
+**Rules:**
+- Log to `stderr` only. `stdout` is the JSON-RPC channel — anything else corrupts the protocol.
+- Tool names: stable identifiers. Changing them is a breaking change for users.
+- `inputSchema` is a JSON Schema. Be specific — vague schemas produce bad tool calls.
+- Keep tool descriptions <500 chars; they're loaded into every session and cost tokens.
+
+## Bundling: pick one (preferred → least preferred)
+
+### 1. `tsup` — single-file bundle (strongly preferred)
+
+```json
+// package.json
+{
+  "scripts": { "build": "tsup src/mcp/server.ts --format=esm --target=node18 --bundle" },
+  "devDependencies": { "tsup": "^8", "@modelcontextprotocol/sdk": "^1" }
+}
+```
+
+Output: one self-contained `dist/mcp/server.js` that runs without `node_modules/`. Marketplaces can ship this without dependency resolution. IBR uses this pattern.
+
+Commit `dist/` to git (don't gitignore) so the marketplace sync ships the bundle.
+
+### 2. `tsc` + committed `dist/`
+
+OK but fragile. Requires `node_modules/` at runtime, and marketplace sync skips `node_modules/`. Workarounds below.
+
+### 3. `tsc` + SessionStart hook with `${CLAUDE_PLUGIN_DATA}`
+
+Install deps into the persistent data dir the first time the plugin loads. Survives plugin updates.
+
+```json
+// hooks/hooks.json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+      }]
+    }]
+  }
+}
+```
+
+Then point the MCP at the installed deps:
+
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "my-plugin": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
+      "env": {
+        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
+      }
+    }
+  }
+}
+```
+
+Trade-off: first session is slow (installs deps); subsequent sessions are instant.
+
+### 4. Pure-stdlib Python server
+
+```python
+# src/mcp/server.py — uses only the mcp package (can be vendored or single-file)
+```
+
+Works well when you want to avoid Node entirely. Harder to bundle single-file than TypeScript — usually needs `mcp-server-stdio` as a runtime dep.
+
+## `.mcp.json` schema (the thing that breaks most often)
+
+**CORRECT** — wrap in `"mcpServers"`:
+
+```json
+{
+  "mcpServers": {
+    "my-plugin": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
+      "env": {
+        "DEBUG": "1"
+      }
+    }
+  }
+}
+```
+
+**WRONG** — flat form. Silently passes `/doctor`, fails at MCP startup. Only `/mcp` surfaces the error.
+
+```json
+{
+  "my-plugin": { "command": "node", "args": [...] }
+}
+```
+
+Real incident (2026-04-21): `bookmark`, `claude-code-debugger` both shipped flat `.mcp.json`. Both showed "MCP · ✗ failed" in `/plugin` for weeks before diagnosis. See `plugin-builder/references/plugin-hygiene-lessons.md` § 7.
+
+### Inline form (in `plugin.json`)
+
+```json
+{
+  "name": "my-plugin",
+  "mcpServers": {
+    "my-plugin": { "command": "...", "args": [...] }
+  }
+}
+```
+
+Inline form drops the outer wrapper but uses the same inner structure.
+
+## Standalone smoke test (before shipping)
+
+Always verify the server responds to `initialize` before publishing. This isolates "server broken" from "Claude Code UI stale":
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
+  CLAUDE_PLUGIN_ROOT=/path/to/your/plugin \
+  node /path/to/your/plugin/dist/mcp/server.js
+```
+
+Healthy response (single line of JSON):
+```json
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","serverInfo":{"name":"my-plugin","version":"1.0.0"},"capabilities":{"tools":{}}}}
+```
+
+If you see:
+- nothing → server exited before the handshake; check `console.error` output
+- `MODULE_NOT_FOUND` → bundling failed, `dist/` references a package that isn't bundled
+- `EACCES` → file-permission issue, usually the script isn't executable (not required for `node` but often accompanies deeper path issues)
+- `SyntaxError` → wrong target (e.g. ESM features in a CJS bundle, or vice versa)
+
+The server should then block on stdin waiting for the next message. Send `Ctrl+D` (`echo ... | node ...` closes stdin after the echo, which is why the server exits cleanly).
+
+## Debugging a failed server in Claude Code
+
+1. Run the standalone smoke test above. If it fails, the server has a real problem.
+2. If smoke test passes but `/plugin` still shows "failed", the UI status may be stale. Reload:
+   ```
+   /reload-plugins
+   ```
+3. Check `/mcp` (more detail than `/plugin`). Look for the actual launch error.
+4. Check `claude --debug` output at startup — logs every MCP init attempt.
+5. Verify `${CLAUDE_PLUGIN_ROOT}` resolves to the right cache dir, not a stale one. Look at `~/.claude/plugins/installed_plugins.json` for the `installPath` of your plugin.
+
+Common failure modes after the schema fix:
+- **No `dist/` in the cache** — bundle wasn't committed, or was gitignored.
+- **`node_modules/` missing** — using `tsc` pattern without the SessionStart-install hook.
+- **Wrong `installPath`** — `version` field says 1.0.1 but `installPath` ends in `/1.0.0/`. See `plugin-hygiene-lessons.md` § 10.
+
+## Tool design rules (for the MCP server itself)
+
+1. **Few strong tools beats many weak tools.** Claude's tool-picking degrades with each added tool. Aim for <10 tools per server unless you genuinely expose a large surface.
+2. **Idempotent by default.** Tool calls can be retried. Mutating operations should specify idempotency.
+3. **Explicit outcome in return value.** Include status + structured data. "Returned successfully" with no payload hides silent failures.
+4. **No network at startup.** Don't validate credentials in the constructor; do it in `initialize` or lazily on first tool call. Startup-time network == long `/plugin` load times.
+5. **Respect timeouts.** MCP has a default request timeout. Long-running tools should either stream progress or return quickly with a handle the client can poll.
+6. **Error messages are for the LLM.** Write errors Claude can use to self-correct: `"input 'path' must be absolute, got: './foo'"` beats `"InvalidPath"`.
+
+## References
+
+- `references/mcp-security.md` — NSA-derived stage-aware MCP security model (Tier 1 always-mandatory + Tier 2 decision table). Loaded by the Security preflight step above.
+- `plugin-builder/references/plugin-hygiene-lessons.md` — real incidents, `.mcp.json` schema war stories, packaging traps (sections 7, 8, 11, 13)
+
+**Doc sources** — resolve via `/api-registry:docs <service>` (primary path); the URLs below are the fallback only, used when the api-registry plugin is not installed:
+
+- `mcp-spec` → https://modelcontextprotocol.io/specification — protocol spec
+- `mcp-ts-sdk` → https://github.com/modelcontextprotocol/typescript-sdk — TypeScript reference SDK
+- `mcp-python-sdk` → https://github.com/modelcontextprotocol/python-sdk — Python reference SDK
+- `anthropic-plugins-reference` → https://code.claude.com/docs/en/plugins-reference#mcp-servers — Anthropic's MCP section
+- `mcp-servers` / `mcp-servers-archived` → reference server lists (the archived list flags unsupported projects)
+- https://github.com/tyroneross/interface-built-right — `tsup`-bundled example
+
+## Preflight checklist (MCP-specific, supplements plugin-builder checklist)
+
+- [ ] `.mcp.json` wraps servers in `{"mcpServers": {...}}`
+- [ ] Command uses `${CLAUDE_PLUGIN_ROOT}` for all plugin-relative paths
+- [ ] Bundled with `tsup` (single file) OR `dist/` + `${CLAUDE_PLUGIN_DATA}` install hook OR `dist/` committed with pure-stdlib
+- [ ] `dist/` is NOT gitignored
+- [ ] Server logs only to stderr (stdout reserved for protocol)
+- [ ] Standalone smoke test via `initialize` RPC passes
+- [ ] Tool count is appropriate (<10 unless necessary)
+- [ ] No startup-time network calls
+- [ ] Tool descriptions are concise (<500 chars each)
+- [ ] Versioning: bump `plugin.json` and the `Server(...)` constructor's `version` together