@zigrivers/scaffold 3.32.1 → 3.33.1

package/content/knowledge/mcp-server/mcp-tool-design.md

@@ -0,0 +1,125 @@
+---
+name: mcp-tool-design
+description: MCP tool naming conventions, JSON Schema inputSchema design, idempotency, output content blocks, isError for tool-level errors, outputSchema, and annotations
+topics: [mcp, tools, json-schema, tool-design, error-handling]
+volatility: evolving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/server/tools
+  - url: https://json-schema.org/draft/2020-12/schema
+---
+
+Tools are the primary mechanism by which MCP servers expose executable capabilities to LLM clients. A well-designed tool is discoverable, predictable, safe to retry, and explicit about its failure modes.
+
+## Summary
+
+Each MCP tool has a `name`, optional `description`, a JSON Schema `inputSchema`, and an optional `outputSchema`. Tool calls use `tools/call`; results carry a `content` array of typed content blocks and an optional `isError` boolean. Use `isError: true` to report expected tool-level failures (API errors, invalid business inputs) as structured results rather than JSON-RPC protocol errors. Tools should be idempotent where possible, and side-effect-bearing tools should be explicitly documented as such via annotations.
+
+## Deep Guidance
+
+### Tool naming conventions
+
+Tool names must be unique within a server. Use `snake_case` for tool names — the 2025-11-25 spec revision (SEP-986) formally reinforces this convention. Names should be short verb-noun phrases that describe what the tool does: `get_weather`, `create_issue`, `search_documents`. Avoid generic names like `execute` or `run` that give the LLM no signal about the tool's purpose.
+
+The `description` field is critical — it is the primary signal the LLM uses to decide when to invoke a tool. Be specific about what the tool does, what inputs it expects, and when it should be used. A poor description leads to misuse. A good description includes the domain, the action, any preconditions, and the output shape in plain English.
+
+### JSON Schema inputSchema
+
+Every tool MUST declare an `inputSchema` as a valid JSON Schema object. MCP uses **JSON Schema 2020-12** as its default schema dialect (established in the 2025-11-25 revision). The schema serves two purposes: runtime validation and LLM guidance. Best practices:
+
+- Use `type: "object"` at the root with named `properties`.
+- List required parameters in the `required` array. Do not list optional parameters there.
+- Add a `description` to every property — the LLM reads these to understand each argument.
+- Use the most specific type possible: prefer `"type": "integer"` over `"type": "number"` when only integers make sense.
+- Use `enum` for fixed sets of valid values.
+- Use `format` hints (`"format": "uri"`, `"format": "date"`) where applicable.
+
+Example of a well-specified inputSchema:
+```json
+{
+  "type": "object",
+  "properties": {
+    "repo": {
+      "type": "string",
+      "description": "GitHub repository in owner/name format, e.g. 'acme/backend'"
+    },
+    "state": {
+      "type": "string",
+      "enum": ["open", "closed", "all"],
+      "description": "Filter issues by state. Defaults to 'open'."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "Maximum number of issues to return. Defaults to 20."
+    }
+  },
+  "required": ["repo"]
+}
+```
+
+Always validate inputs against the inputSchema in the server implementation before executing any side effects. The spec requires it, and doing so prevents malformed or injected arguments from reaching downstream systems.
+
+### Idempotency and side effects
+
+MCP tools should be designed with idempotency in mind wherever the underlying operation supports it. Read-only tools (queries, lookups) are naturally idempotent and carry the lowest risk. Mutating tools (writes, deletes, API calls with side effects) should document their non-idempotency explicitly.
+
+The `annotations` field on a tool definition carries hints for clients:
+
+```json
+{
+  "annotations": {
+    "readOnlyHint": true,
+    "idempotentHint": true,
+    "openWorldHint": false
+  }
+}
+```
+
+`readOnlyHint: true` means the tool does not modify any state. `idempotentHint: true` means calling it multiple times with the same arguments produces the same result. `openWorldHint: true` means the tool interacts with external systems beyond the local environment. Clients treat these as untrusted hints — they assist the LLM in deciding whether user confirmation is needed, but do not replace host-side confirmation flows for destructive operations.
+
+### Output content blocks
+
+Tool results return a `content` array containing one or more typed content blocks:
+
+- **TextContent**: `{ "type": "text", "text": "..." }` — the most common type; use for plain text, JSON strings, or structured prose.
+- **ImageContent**: `{ "type": "image", "data": "<base64>", "mimeType": "image/png" }` — for screenshots, charts, or generated images.
+- **AudioContent**: `{ "type": "audio", "data": "<base64>", "mimeType": "audio/wav" }` — for audio responses.
+- **ResourceLink**: `{ "type": "resource_link", "uri": "...", "name": "...", "mimeType": "..." }` — reference a resource the client can fetch separately.
+- **EmbeddedResource**: `{ "type": "resource", "resource": { "uri": "...", "mimeType": "...", "text": "..." } }` — inline resource content.
+
+Tools can return multiple content blocks in one result (e.g., a text summary plus an image). The `content` array is always present, even for empty results — return an empty array rather than null.
+
+If the tool declares an `outputSchema`, it MUST also provide structured content in a `structuredContent` field matching that schema, and SHOULD also include the serialized JSON as a TextContent block for backwards compatibility.
+
+### isError: tool errors vs protocol errors
+
+MCP distinguishes two error reporting paths:
+
+**Protocol errors** (JSON-RPC errors) are for structural/wire-level failures where the call could not be dispatched at all: unknown tool name in `tools/call`, malformed JSON-RPC structure, server crashes. These return a JSON-RPC error response with a negative integer `code`. The LLM cannot generally recover from protocol errors.
+
+**Tool execution errors** use `isError: true` in the result. Use this for any failure that occurs after the tool dispatches — including tool `inputSchema` validation failures, business validation rejections, API rate limits, resource not found, and network timeouts. Per the 2025-11-25 spec (SEP-1303), tool input validation failures MUST use `isError: true` (not `-32602`) so the model can read the error and self-correct. Return `isError: true` with a descriptive TextContent explaining what went wrong and, when possible, what the caller should do differently.
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "GitHub API rate limit exceeded. Resets at 2025-06-18T14:00:00Z. Retry after that time."
+    }
+  ],
+  "isError": true
+}
+```
+
+Never raise a JSON-RPC protocol error for domain-level failures that a well-behaved caller might encounter. Reserve protocol errors for structural dispatch failures (wrong method name, unknown tool). When in doubt, use `isError: true` — it keeps the LLM in the loop about what went wrong.
+
+### Partial failures
+
+When a tool processes multiple items and some fail, report partial results in the `content` array with a summary, and set `isError: true` only if the overall operation should be treated as failed. For best-effort multi-item tools, return results for successful items and error descriptions for failed ones, without setting `isError: true`, so the LLM can use the partial output.
+
+### List change notifications
+
+If the server's tool set can change at runtime (e.g., tools are dynamically registered), declare `tools: { listChanged: true }` in capabilities and send `notifications/tools/list_changed` when the set changes. The client will re-issue `tools/list` to refresh its cache. This is important for servers where available tools depend on user configuration or authentication state.

package/content/knowledge/mcp-server/mcp-transport-patterns.md

@@ -0,0 +1,122 @@
+---
+name: mcp-transport-patterns
+description: MCP stdio and Streamable HTTP transports, deprecated HTTP+SSE migration, session management, MCP-Protocol-Version header, and transport selection guidance
+topics: [mcp, transport, stdio, http, sse, session-management]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+---
+
+MCP defines two standard transports: **stdio** (local subprocess) and **Streamable HTTP** (network-accessible). The old HTTP+SSE transport from spec version 2024-11-05 is deprecated. Transport choice is a deployment decision that shapes your server's authentication model, scalability, and operational complexity.
+
+## Summary
+
+**stdio**: client launches server as subprocess, communicates over stdin/stdout, logs go to stderr. Best for local tools installed alongside the client. **Streamable HTTP**: server runs independently at an HTTP endpoint, clients POST JSON-RPC messages, server optionally streams responses via SSE. Best for shared/remote servers. The deprecated HTTP+SSE transport used separate GET (SSE stream) and POST (messages) endpoints — migrate to Streamable HTTP. The `MCP-Protocol-Version` header MUST be sent on all HTTP requests after initialization.
+
+## Deep Guidance
+
+### stdio transport
+
+In the stdio transport, the MCP client launches the server as a child process. All JSON-RPC messages flow over the process's standard streams:
+
+- Client writes JSON-RPC messages to server's **stdin**, one message per line, no embedded newlines.
+- Server writes JSON-RPC messages to its **stdout**, one message per line, no embedded newlines.
+- Server writes diagnostic/logging output to **stderr** only — stdout is reserved strictly for JSON-RPC protocol messages.
+
+```
+Client Process
+  ├── spawns → Server Process
+  │                ├── stdin  ← JSON-RPC messages from client
+  │                ├── stdout → JSON-RPC messages to client
+  │                └── stderr → logs (captured by client, not protocol)
+```
+
+**Key rules for stdio servers:**
+- NEVER write anything to stdout except valid JSON-RPC messages. Any stray output (debug prints, startup banners, library log messages) will corrupt the protocol stream and cause parse errors. This is the most common stdio bug.
+- Redirect all application logging to stderr (or a file). In Python: `print("msg", file=sys.stderr)`. In Node.js: `process.stderr.write(...)`. In Go: `fmt.Fprintln(os.Stderr, ...)`.
+- The server process's working directory may be undefined (could be `/` on macOS) when launched by a client. Use absolute paths for any file access or configuration loading.
+
+Shutdown: the client closes the server's stdin stream, waits for the process to exit, then sends SIGTERM after a timeout, then SIGKILL.
+
+### Streamable HTTP transport
+
+The Streamable HTTP transport runs the server as an independent HTTP service. A single MCP endpoint (e.g., `https://example.com/mcp`) handles both GET and POST:
+
+**Client → Server (POST)**: Every JSON-RPC message from client to server is a new HTTP POST. The client MUST include `Accept: application/json, text/event-stream` headers. The server responds either with `Content-Type: application/json` (single response) or `Content-Type: text/event-stream` (SSE stream for streaming/multiple messages).
+
+**Server → Client (GET)**: The client MAY open a GET SSE stream to receive server-initiated messages (notifications, server-to-client requests) without first sending a POST. The server returns `Content-Type: text/event-stream` or `405 Method Not Allowed` if not supported.
+
+**Session management**: The server MAY assign a session ID in the `Mcp-Session-Id` response header during initialization. If issued, the client MUST include `Mcp-Session-Id: <id>` on all subsequent requests. Sessions are terminated via HTTP DELETE to the MCP endpoint with the session ID header.
+
+**Security requirements**:
+- Validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks.
+- Bind to localhost only (127.0.0.1) when running locally; never 0.0.0.0 for local-only servers.
+- Implement authentication for all connections (see `mcp-authentication.md`).
+
+### MCP-Protocol-Version header
+
+After initialization, HTTP clients MUST include `MCP-Protocol-Version: <negotiated-version>` on all requests. Example: `MCP-Protocol-Version: 2025-11-25`. If a server receives no version header, it SHOULD assume `2025-03-26` for backwards compatibility. Servers MUST reject requests with unsupported versions with `400 Bad Request`. As of 2025-11-25, servers MUST also respond with HTTP 403 Forbidden when an incoming connection carries an invalid `Origin` header (previously the response code was not specified).
+
+### Deprecated HTTP+SSE transport
+
+The HTTP+SSE transport (from spec version 2024-11-05) used two separate endpoints:
+- A GET endpoint that opened a persistent SSE stream, returning an `endpoint` event with a POST URL.
+- A POST endpoint for client messages.
+
+This is **deprecated** as of spec 2025-03-26 and replaced by Streamable HTTP. For backwards compatibility:
+
+**Servers** wanting to support both old and new clients: keep the old SSE GET endpoint and old POST endpoint running alongside the new Streamable HTTP endpoint.
+
+**Clients** detecting transport version: POST an `initialize` request. If the server responds with success, it supports Streamable HTTP. If the server returns 4xx (405 or 404), issue a GET instead — if it returns an SSE stream with an `endpoint` event, it's an old HTTP+SSE server. Support both paths during a migration window.
+
+### Transport selection guidance
+
+| Scenario | Recommended transport |
+|----------|----------------------|
+| Local tool (installed alongside client) | stdio |
+| Developer machine tool (file access, CLI wrappers) | stdio |
+| Shared team server (hosted, multi-user) | Streamable HTTP |
+| Cloud-hosted integration (SaaS backend) | Streamable HTTP |
+| Containerized/serverless deployment | Streamable HTTP |
+| Mobile or browser-based host | Streamable HTTP |
+
+**Choose stdio when**: the server must run on the user's machine, the tool accesses local files or processes, you want zero-config deployment (install package, configure path), or you want the simplest possible security model (OS process isolation, no network auth needed).
+
+**Choose Streamable HTTP when**: the server is shared across multiple clients or users, you need centralized deployment and updates, the server integrates with remote APIs or databases, or you need to run the server independently of any specific client lifecycle.
+
+Custom transports are allowed by the spec — any bidirectional communication channel that preserves JSON-RPC message format and lifecycle requirements can be used. Document custom transports thoroughly.
+
+### Connection lifecycle and error handling
+
+Both transports follow the same JSON-RPC 2.0 lifecycle:
+
+1. **Initialize**: client sends `initialize` request with protocol version and capabilities; server responds with its own capabilities.
+2. **Initialized notification**: client sends `notifications/initialized` to signal readiness.
+3. **Normal operation**: bidirectional request/response and notifications.
+4. **Shutdown**: client sends `notifications/cancelled` for in-flight requests, then closes the transport.
+
+**Common transport errors and remediation**:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Parse errors on stdio | Non-JSON written to stdout (e.g., debug prints) | Redirect all non-protocol output to stderr |
+| `400 Bad Request` on HTTP | Missing or invalid `MCP-Protocol-Version` header | Ensure client sends the header after initialization |
+| `404` on HTTP | Client using old HTTP+SSE transport path | Detect and support both paths during migration |
+| Session `410 Gone` | Session expired or server restarted | Client should re-initialize and re-establish session |
+
+### Testing transport behavior
+
+```typescript
+// Test stdio transport with in-process transport for unit tests
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+const client = new Client({ name: "test-client", version: "1.0.0" });
+await client.connect(clientTransport);
+// server connects to serverTransport in parallel
+```
+
+For HTTP transport integration tests, use a real HTTP server bound to a random port (`listen(0)`) and tear it down after each test. Never share server state between tests.

package/content/knowledge/mcp-server/mcp-versioning.md

@@ -0,0 +1,115 @@
+---
+name: mcp-versioning
+description: MCP protocol version negotiation, MCP-Protocol-Version HTTP header, capability-based feature detection, server versioning strategy, and backwards compatibility
+topics: [mcp, versioning, protocol-version, backwards-compatibility, capability-negotiation]
+volatility: stable
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+---
+
+MCP uses calendar-versioned protocol strings and capability-based feature detection. Understand both mechanisms to build servers that work with current clients and remain compatible as the spec evolves.
+
+## Summary
+
+Protocol versions are date strings (e.g., `2025-11-25`). The client proposes a version in `initialize`; the server echoes it or responds with its preferred version. If versions are incompatible, the client disconnects. HTTP clients MUST include `MCP-Protocol-Version: <negotiated-version>` on all subsequent requests. Feature availability is determined by capability negotiation, not version numbers alone. For your server's own versioning, use semantic versioning; keep the `serverInfo.version` field current and stable across protocol version changes.
+
+## Deep Guidance
+
+### Protocol version strings
+
+MCP protocol versions are ISO 8601 calendar dates: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. Current production version is `2025-11-25`. Always send the latest version you support in the `initialize` request — the server will downgrade if needed.
+
+Version negotiation in the `initialize` handshake:
+1. Client sends `"protocolVersion": "2025-11-25"` (its latest supported version).
+2. If the server supports `2025-11-25`, it responds with `"protocolVersion": "2025-11-25"`.
+3. If the server only supports `2025-03-26`, it responds with `"protocolVersion": "2025-03-26"`.
+4. The client checks if it supports the server's response version. If not, it disconnects.
+
+This ensures both sides agree on a common protocol dialect before any other messages are exchanged.
+
+### MCP-Protocol-Version HTTP header
+
+After initialization, HTTP clients MUST send `MCP-Protocol-Version: <negotiated-version>` on every subsequent request:
+
+```
+POST /mcp HTTP/1.1
+Host: mcp.example.com
+Content-Type: application/json
+Accept: application/json, text/event-stream
+MCP-Protocol-Version: 2025-11-25
+Mcp-Session-Id: abc123
+```
+
+Servers use this header to handle requests differently based on protocol version when supporting multiple versions simultaneously. If a server receives no `MCP-Protocol-Version` header, the spec says to assume `2025-03-26` for backwards compatibility. Servers MUST return `400 Bad Request` for unsupported or invalid version header values.
+
+### Capability-based feature detection
+
+Do not version-gate features solely on protocol version numbers. Use capability negotiation instead. A server supporting `2025-11-25` may not declare the `prompts` capability — that means prompts are not available regardless of protocol version.
+
+The correct pattern for clients: check whether the server declared the capability before calling the corresponding methods. A client that calls `tools/list` without checking whether the server declared `tools` capability will receive a protocol error. The `initialize` response is the authoritative source of truth for what a server supports.
+
+For servers: declare only the capabilities you actually implement. Over-declaring capabilities (e.g., declaring `resources: { subscribe: true }` but not handling `resources/subscribe`) will cause client errors and poor UX.
+
+### Evolving your server's capabilities over versions
+
+When you add a new capability to your server (e.g., adding resource support to a tools-only server):
+- Add the capability to your `initialize` response immediately.
+- The capability declaration is backwards compatible — old clients that don't use resources will simply not call `resources/list`.
+- Do not bump your `serverInfo.version` for protocol-level changes; that field tracks your server's own software version.
+
+When you remove a capability (uncommon but possible):
+- Remove it from the `initialize` response.
+- Any client that was relying on it will receive a protocol error when they call the now-unsupported method.
+- Consider maintaining the capability with a deprecation notice in the server's `instructions` field before fully removing it.
+
+### Server software versioning
+
+The `serverInfo.version` in `initialize` is your server's semantic version (e.g., `"1.3.0"`), independent of the MCP protocol version. Follow semantic versioning:
+- **Patch** (1.0.x): bug fixes, no schema changes, no capability changes.
+- **Minor** (1.x.0): new tools/resources/prompts added, existing ones unchanged.
+- **Major** (x.0.0): removed or renamed tools/resources/prompts, breaking schema changes.
+
+Breaking changes in tool `inputSchema` or resource URI patterns are breaking changes for MCP clients that have auto-discovered and cached your server's schema. Treat them as major version bumps and communicate them in advance.
+
+### Supporting multiple protocol versions simultaneously
+
+If you need to serve both old (2024-11-05 HTTP+SSE) and new (2025-11-25 Streamable HTTP) clients:
+- Keep the old SSE GET endpoint and POST endpoint running alongside the new MCP endpoint.
+- Use the `MCP-Protocol-Version` header to route behavior within the Streamable HTTP path.
+- Set a deprecation date for old transport support and communicate it in the `serverInfo` description or via documentation.
+
+For servers that only need to support the latest spec, target `2025-11-25` and do not implement the deprecated HTTP+SSE transport. New clients target the current spec; support for the old transport is only needed if you have existing clients that have not yet migrated.
+
+### Spec evolution cadence
+
+The MCP spec has evolved on roughly a quarterly cadence: `2024-11-05` (initial), `2025-03-26` (Streamable HTTP introduction), `2025-06-18`, `2025-11-25` (current). Major changes between versions: `2024-11-05 → 2025-03-26` introduced Streamable HTTP, deprecating HTTP+SSE. `2025-03-26 → 2025-06-18` added `outputSchema` for tools, `structuredContent`, audio content type, `title` fields, and the `elicitation` client capability. `2025-06-18 → 2025-11-25` added OIDC Discovery 1.0 support; aligned OAuth Protected Resource Metadata to RFC 9728 (`WWW-Authenticate` header now optional with `.well-known` fallback); incremental scope consent and Client ID Metadata Documents for client registration; `icons` metadata on tools/resources/prompts; JSON Schema 2020-12 as the default dialect; input validation errors explicitly directed as Tool Execution Errors (`isError`) for model self-correction; Streamable HTTP servers MUST respond HTTP 403 for invalid Origin headers; stdio servers MAY use stderr for all logging; elicitation gains URL-mode, titled/untitled enums, and primitive default values; sampling gains `tools`/`toolChoice` support; experimental `tasks` feature for durable requests with polling. Watch the spec changelog (https://modelcontextprotocol.io) for new capabilities that may benefit your server.
+
+### Backwards compatibility checklist
+
+When releasing a new server version, verify these backwards compatibility invariants before shipping:
+
+1. **No renamed tools**: renaming a tool (e.g., `search_files` → `find_files`) is a breaking change. Existing clients with auto-approved tool calls will fail silently. Use the old name as an alias or bump major version with advance notice.
+2. **No removed required input fields**: removing a required field from `inputSchema` is non-breaking (callers can stop providing it); adding a new required field IS breaking (callers that don't provide it will receive validation errors).
+3. **No resource URI pattern changes**: changing `file://{path}` to `file://workspace/{path}` breaks all existing resource subscriptions and saved URIs. Treat as a major version change.
+4. **No prompt argument removals**: removing a declared prompt argument breaks clients that pass that argument.
+5. **No capability downgrades without communication**: removing `resources: { subscribe: true }` when clients have active subscriptions causes silent failures.
+
+For patch and minor releases, adding new optional tool parameters, new tools, new resources, or new prompts is always backwards compatible — existing callers ignore what they don't use.
+
+### Version signaling in serverInfo
+
+Use the `serverInfo.version` field as a machine-readable signal for clients that cache schemas:
+
+```json
+{
+  "serverInfo": {
+    "name": "my-mcp-server",
+    "version": "2.1.0"
+  }
+}
+```
+
+Clients can cache tool/resource schemas keyed by `(serverInfo.name, serverInfo.version)`. When the server bumps its version, clients re-fetch schemas rather than serving stale cached definitions. This pattern is especially important for IDE integrations and agent frameworks that pre-load tool definitions at startup.

package/content/methodology/custom-defaults.yml

@@ -43,6 +43,7 @@ steps:
   database-schema: { enabled: true, conditional: "if-needed" }
   review-database: { enabled: true, conditional: "if-needed" }
   api-contracts: { enabled: true, conditional: "if-needed" }
+  mcp-tool-resource-contract: { enabled: false }
   review-api: { enabled: true, conditional: "if-needed" }
   ux-spec: { enabled: true, conditional: "if-needed" }
   review-ux: { enabled: true, conditional: "if-needed" }
@@ -74,6 +75,7 @@ steps:
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }
+  materialize-plan-to-beads: { enabled: true, conditional: "if-needed" }
   # Phase 15 — Build (build) — stateless, on-demand execution steps
   single-agent-start: { enabled: true }
   single-agent-resume: { enabled: true }

package/content/methodology/deep.yml

@@ -42,6 +42,7 @@ steps:
   database-schema: { enabled: true, conditional: "if-needed" }
   review-database: { enabled: true, conditional: "if-needed" }
   api-contracts: { enabled: true, conditional: "if-needed" }
+  mcp-tool-resource-contract: { enabled: false }
   review-api: { enabled: true, conditional: "if-needed" }
   ux-spec: { enabled: true, conditional: "if-needed" }
   review-ux: { enabled: true, conditional: "if-needed" }
@@ -73,6 +74,7 @@ steps:
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }
+  materialize-plan-to-beads: { enabled: true, conditional: "if-needed" }
   # Phase 15 — Build (build) — stateless, on-demand execution steps
   single-agent-start: { enabled: true }
   single-agent-resume: { enabled: true }

package/content/methodology/mcp-server-overlay.yml

@@ -0,0 +1,88 @@
+# methodology/mcp-server-overlay.yml
+name: mcp-server
+description: >
+  MCP Server overlay — an MCP server has no UI, so the design-system and UX
+  steps are disabled. database-schema/review-database stay available
+  (if-needed) for servers that persist resources/state. The
+  mcp-tool-resource-contract step is enabled (if-needed) for specifying MCP
+  tool/resource/prompt schemas. MCP domain knowledge (protocol, SDK, transport,
+  tool/resource design, auth, testing, deployment, observability, versioning)
+  is injected into the relevant pipeline steps.
+project-type: mcp-server
+
+step-overrides:
+  # No UI surface — disable design/UX steps entirely.
+  design-system: { enabled: false }
+  ux-spec: { enabled: false }
+  review-ux: { enabled: false }
+  # Stateful servers may persist resources; keep available but skippable.
+  database-schema: { enabled: true, conditional: "if-needed" }
+  review-database: { enabled: true, conditional: "if-needed" }
+  # MCP-specific spec step — enabled for mcp-server projects.
+  mcp-tool-resource-contract: { enabled: true, conditional: "if-needed" }
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Inject MCP domain expertise into existing pipeline steps so that MCP
+# protocol, SDK, transport, tool/resource design, auth, testing, deployment,
+# observability, and versioning knowledge is available during prompt assembly.
+knowledge-overrides:
+  # Foundation
+  tech-stack:
+    append: [mcp-protocol-fundamentals, mcp-sdk-selection, mcp-transport-patterns]
+  tdd:
+    append: [mcp-testing-strategies]
+
+  # Architecture & Decisions
+  system-architecture:
+    append: [mcp-protocol-fundamentals, mcp-transport-patterns, mcp-tool-design, mcp-resource-design]
+  adrs:
+    append: [mcp-sdk-selection, mcp-transport-patterns]
+
+  # Specifications
+  api-contracts:
+    append: [mcp-tool-design, mcp-resource-design, mcp-error-handling]
+  # mcp-tool-resource-contract knowledge is already declared in the step's own
+  # frontmatter knowledge-base ([mcp-tool-design, mcp-resource-design,
+  # mcp-prompt-primitives, mcp-error-handling]); no overlay override needed.
+  database-schema:
+    append: [mcp-resource-design]
+
+  # Testing
+  add-e2e-testing:
+    append: [mcp-testing-strategies]
+
+  # Quality Gates
+  security:
+    append: [mcp-authentication]
+  review-security:
+    append: [mcp-authentication]
+  operations:
+    append: [mcp-deployment-patterns, mcp-observability, mcp-versioning]
+  review-operations:
+    append: [mcp-deployment-patterns, mcp-observability, mcp-versioning]
+
+  # Reviews
+  review-architecture:
+    append: [mcp-transport-patterns, mcp-tool-design, mcp-resource-design]
+
+# ---------------------------------------------------------------------------
+# reads-overrides
+# ---------------------------------------------------------------------------
+# Wire docs/mcp-contract.md (output of mcp-tool-resource-contract) into
+# downstream steps that need MCP auth/validation/error contracts.
+# Uses append-only so non-MCP steps are unaffected when the overlay is absent.
+reads-overrides:
+  # Security review: MCP auth/error contracts are security-relevant
+  security:
+    append: [mcp-tool-resource-contract]
+  review-security:
+    append: [mcp-tool-resource-contract]
+  # Test generation: test the tools/resources against the contract
+  create-evals:
+    append: [mcp-tool-resource-contract]
+  story-tests:
+    append: [mcp-tool-resource-contract]
+  tdd:
+    append: [mcp-tool-resource-contract]

package/content/methodology/mvp.yml

@@ -42,6 +42,7 @@ steps:
   database-schema: { enabled: false }
   review-database: { enabled: false }
   api-contracts: { enabled: false }
+  mcp-tool-resource-contract: { enabled: false }
   review-api: { enabled: false }
   ux-spec: { enabled: false }
   review-ux: { enabled: false }
@@ -73,6 +74,7 @@ steps:
   apply-fixes-and-freeze: { enabled: false }
   developer-onboarding-guide: { enabled: false }
   implementation-playbook: { enabled: true }
+  materialize-plan-to-beads: { enabled: false }
   # Phase 15 — Build (build) — stateless, on-demand execution steps
   single-agent-start: { enabled: true }
   single-agent-resume: { enabled: true }

package/content/pipeline/build/multi-agent-resume.md

@@ -119,17 +119,113 @@ Recover your context by checking the current state of work:
 
 ### Beads Recovery
 
-**If Beads is configured** (`.beads/` exists):
-- `bd list --assignee "$ARGUMENTS"` — check for tasks with `in_progress` status owned by this agent
-- If a PR shows as merged, close the corresponding task: `bd close <id>`
-- If there is in-progress work, finish it (see "Resume In-Progress Work" below)
-- Otherwise, clean up and start fresh:
-  - `git fetch origin --prune && git clean -fd`
-  - Run the install command from CLAUDE.md Key Commands
-  - Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')` (sets `assignee=$BEADS_ACTOR` + `status=in_progress`; no race window between agents).
-- Continue working until `bd ready --claim --json` returns no task.
-
-**Without Beads:**
+The implementation plan is materialized into Beads issues by
+`/scaffold:materialize-plan-to-beads` before the build phase. A resumed build
+runs the **same defensive preflight** as the start prompt — it never claims
+against an empty or stale tracker. Under multi-agent concurrency,
+materialization is **orchestrator-only** and runs **once per wave under a
+merge-slot lock**; workers never materialize and must wait for a run-stamped
+completion signal before their first claim.
+
+**Step 1 — compute `beads_usable`.** `beads_usable` is true only when **all**
+hold: `.beads/` exists, `bd` is on `PATH`, `bd version` parses to **≥ 1.0.5**
+(using a macOS/BSD-safe numeric compare — split major/minor/patch and compare
+numerically, never rely on GNU `sort -V`), and `jq` is on `PATH`. Never write
+`[ -d .beads ] && bd …` as a whole command — it returns exit 1 when `.beads/` is
+absent and breaks callers under `set -e`; use an `if`.
+
+**Step 2 — route on the decision table** (this is what prevents the "empty
+tracker looks done" bug):
+
+| Condition | Action |
+|---|---|
+| `.beads/` **absent** | Non-Beads project → drive the loop from the markdown playbook/plan (see "Markdown fallback" below). Do **not** call `bd`. |
+| `.beads/` present but `beads_usable` is false (`bd`/`jq` missing or `bd` < 1.0.5) | **Fail closed.** Stop and tell the user to install/upgrade `bd` (≥ v1.0.5) and `jq`. Do **not** markdown-fall-back — Beads may already hold execution state. |
+| `beads_usable`, plan has **no** stable IDs **and** Beads holds no plan-derived issues and no non-bootstrap claimed/closed work | Genuinely legacy plan → markdown loop, emit "re-run planning to assign stable task IDs". Do **not** claim. |
+| `beads_usable`, plan has no stable IDs **but** Beads already holds plausible build work | **Fail closed** — markdown would bypass existing execution state. |
+| `beads_usable`, contract **partially present or malformed** | **Fail closed.** Do **not** markdown-fall-back. Require planning to be re-run/fixed. |
+| `beads_usable` **and a valid stable-ID contract** | **Resume your own task; orchestrator materializes once under the lock; workers wait; then claim** (see Step 3). |
+
+**Step 3 — `beads_usable` + valid contract:**
+
+**Two distinct identities.** The merge-slot needs a **per-process unique** holder
+(e.g. `agent-$$` or a UUID) so two local agents sharing one `git user.name` don't
+both think they hold the slot. The **claim/resume actor must stay stable** per
+worktree/session — resolve `BEADS_ACTOR` → `git user.name` → `$USER` (never
+empty). Use the unique value **only** for `bd merge-slot acquire/check/release`;
+keep the stable `BEADS_ACTOR` for the resume lookup and `bd ready --claim`.
+
+1. **Resume the actor's own in-flight *plan* task first.** Before claiming
+   anything new — and using the **stable** claim actor, not the per-process lock
+   identity — check for a **plan-derived** task already `in_progress` assigned to
+   you, scoped exactly like claiming:
+   `bd list --status in_progress --assignee <actor> --has-metadata-key plan_task_id --json`.
+   If one exists, continue it (see "Resume In-Progress Work" below). Scoping to
+   `plan_task_id` prevents resuming onto an unrelated manual/bootstrap issue
+   assigned to the same actor; any such non-plan in-progress work is reported
+   separately, not resumed as build work.
+2. **Reconcile merged PRs.** If a PR shows as merged, close the corresponding
+   task: `bd close <id>`.
+3. **Orchestrator-only materialization under the merge-slot lock.** Only the wave
+   orchestrator (the first agent resuming the wave) runs the materializer;
+   workers skip to step 4. The orchestrator:
+   - **Clears/overwrites any stale completion signal before acquiring the lock**,
+     so a signal left from a previous pipeline run (or a pre-update plan) can't
+     let workers race ahead of a fresh re-materialization. The **completion
+     signal must be run-stamped** — carry a `run_id` or the current plan hash
+     (e.g. a metadata flag on the project merge-slot/bootstrap bead, or a
+     workspace marker recording `run_id` / `materialized_at`).
+   - **Acquires the lock with a real acquisition loop, not a status poll** — loop
+     on `bd merge-slot acquire` itself and re-verify ownership via
+     `bd merge-slot check --json` (a released slot is `holder: null` and never
+     auto-promotes a waiter). Guard the non-zero/queued return with `|| true` and
+     release via a `trap … EXIT INT TERM`.
+   - **Once ownership is confirmed, invokes `/scaffold:materialize-plan-to-beads`**
+     (the canonical procedure — do not duplicate the four-pass logic). It is
+     idempotent and a cheap no-op when in sync. If it returns non-zero, **fail
+     closed** (do not set the signal, do not claim, do not markdown-fall-back).
+   - On success, **sets the run-stamped completion signal**, then **releases**
+     the slot.
+4. **Workers block on the run-stamped completion signal before their first
+   claim.** A released slot (`holder: null`) does **not** prove the orchestrator
+   ran — blocking on slot release alone is insufficient (a worker could
+   acquire/release before the orchestrator started). Workers wait until a signal
+   matching **this run's** `run_id`/plan-hash is present, then proceed.
+5. **Clean up and run the scoped claim loop** (using the **stable** `BEADS_ACTOR`,
+   not the per-process lock identity):
+   - `git fetch origin --prune && git clean -fd`
+   - Run the install command from CLAUDE.md Key Commands
+   - Atomically claim the next ready **plan** task:
+     `TASK=$(bd ready --claim --has-metadata-key plan_task_id --json | jq -r '.id')`
+     - Scoping to `plan_task_id` keeps the loop from ever claiming the bootstrap
+       "initialize Beads" bead or a manually-created issue.
+     - This sets `assignee=$BEADS_ACTOR` + `status=in_progress` in a single
+       round-trip — no race window between agents.
+6. Continue until the scoped claim
+   (`bd ready --claim --has-metadata-key plan_task_id --json`) returns no ready
+   task, then run the **completion check**.
+
+**Completion check (empty `bd ready` ≠ done).** An empty scoped-ready result does
+**not** mean the build is finished. On an empty result, fetch all plan-derived
+tasks (`bd list --all --limit 0 --has-metadata-key plan_task_id --json`) and
+classify the remaining non-`closed` tasks:
+
+- **All plan tasks `closed`** → genuinely **done**; exit gracefully.
+- Otherwise classify **each** remaining non-`closed` task independently — do
+  **not** short-circuit on "any task is `in_progress`". Resolve blocker statuses
+  from an **unfiltered** `bd list --all --limit 0 --json` (manual blockers carry
+  no `plan_task_id`):
+  - **advancing** — the task is itself `in_progress`, **or** a **transitive**
+    blocker (walk the chain; bound the walk, reuse `bd dep cycles`) is
+    `in_progress`.
+  - **stalled** — not `in_progress` and no transitive blocker is `in_progress`.
+- **All remaining advancing** → exit gracefully (normal multi-agent case). **Any
+  stalled** → **stop and report the stalled subset**, grouped by why (open
+  dependency, manual `blocked`, `deferred`). Unrelated global `in_progress` work
+  that blocks none of the stalled tasks does **not** suppress the report.
+
+**Markdown fallback** (only when `.beads/` is **absent**, or for a genuinely
+legacy plan per the table — never past existing Beads state):
 - Read `docs/implementation-playbook.md` as the primary task reference.
   Fall back to `docs/implementation-plan.md` when no playbook is present.
 - If a PR shows as merged, mark the corresponding task as complete in the plan/playbook