prompts/.github/prompts/plan-step6.prompt.md

Step 6 Results: Resource-First Discovery and Tool Fallback Contract

This section finalizes Step 6 by defining discovery behavior for clients that can attach MCP resources and the fallback behavior for clients or chat surfaces that must rely on MCP tools.

Step Deliverable

• Update the current docs/ directory with the finalized Step 6 discovery and fallback contract content from this document.

Primary Source Baseline (Repository Docs)

Step 6 is based on the current project contracts in:

1. docs/architecture.md (resource-first architecture and catalog role)
2. docs/usage.md (operating flows, bounded loading, and fallback sequence)
3. docs/copilot.md (client capability lanes and practical fallback behavior)
4. docs/mcp_layout.md (shared content source and thin-tool fallback position)
5. docs/securing.md (read-only/public-docs security invariant)

Normative conclusions from those sources:

1. Discovery stays resource-first.
2. Tool fallback is allowed, thin, and read-only.
3. Resources and tools must resolve to the same canonical authored markdown.
4. Fallback behavior should keep context bounded and deterministic.

FastMCP Source Baseline (Authoritative References)

Step 6 fallback behavior and compatibility-layer expectations align with:

1. FastMCP server concepts
2. FastMCP resources and resource templates
3. FastMCP resources-as-tools transform
4. MCP specification: resources

Applied conclusions for this step:

1. Resource contracts remain canonical and should be surfaced directly when clients support resource attachment.
2. Tool-first compatibility layers should wrap canonical resource reads rather than creating alternate authored-content stores.
3. URI-template-backed resource identity remains stable across direct-resource and tool-compatibility access paths.

Client Tool-Naming Research Baseline

Authoritative and client-specific references to verify during implementation:

1. MCP specification: tools
2. MCP client concepts
3. FastMCP tools
4. FastMCP resources-as-tools transform
5. VS Code MCP servers
6. VS Code MCP configuration reference
7. Cursor MCP documentation
8. Claude Desktop local MCP server setup

Baseline naming conclusions:

1. MCP protocol tool identity is the server-advertised name returned by tools/list and used in tools/call.
2. FastMCP tool identity should be treated as the canonical server contract unless a tool is intentionally registered with an explicit alternate name.
3. Clients and host integrations may display, namespace, or internally route tool names with provider-specific prefixes, but those wrappers are not canonical server tool names.
4. Compatibility should be validated by observed tools/list and successful tools/call behavior in each target client rather than by assuming one global host naming convention.

Discovery Priority Contract (Normative)

Preferred sequence for skill discovery and loading:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
3. resource://skills/{skill_id}/document
4. resource://skills/{skill_id}/references/{ref_id} only when needed

Rules:

1. Start from catalog discovery before loading any skill document.
2. Do not skip straight to broad document loading when catalog metadata can narrow choices first.
3. Use resource://docs/{path*} only for direct authored-doc access outside skill-specific flows.

Fallback Activation Rule

Fallback is used only when the active client path cannot reliably attach MCP resources (for example, tool-only chat surfaces).

Rules:

1. Keep the same discovery order semantics as the resource path.
2. If resource attachment is available, prefer resources over tools.
3. Tool fallback must never become a second authoritative content source.

Tool Fallback Surface (Normative)

The fallback tool surface includes:

1. list_resources
2. read_resource
3. search_patterns
4. get_pattern_by_id
5. get_skill_document_by_id

Canonical naming rule:

1. The server-level tool contract uses the exact registered FastMCP tool names above.
2. Clients that expose provider-prefixed names (for example, namespaced wrappers) must map those names to the canonical server tool name before invocation.
3. catalog_get_skill_document_by_id is not a canonical server tool name for this contract unless an explicit alias is intentionally registered.

Compatibility alias policy:

1. Prefer canonical server tool names over aliases.
2. Add server-side aliases only when a major client cannot reliably map its wrapper name back to the canonical name.
3. Any alias must be read-only, delegate to the same payload builder as the canonical tool, and be documented as compatibility-only.
4. If aliases are added, canonical and alias tools must return byte-for-byte equivalent payloads for the same input.

Fallback order:

1. call list_resources to inspect canonical static/template resource surfaces
2. call read_resource for catalog URIs and selected skill URIs
3. use thin catalog tools only when additional metadata-first narrowing is needed

Tool behavior requirements:

1. read-only and idempotent semantics
2. deterministic ordering and bounded pagination
3. explicit not-found responses (found: false style) where applicable
4. payloads remain schema-aligned with catalog resources
5. tool invocation examples and Copilot guidance must use canonical server tool names to avoid unknown-tool errors

Major Client Compatibility Plan

Target clients and expected validation:

1. GitHub Copilot in VS Code
   • primary path: attach MCP resources when MCP Resources... is available
   • fallback path: call list_resources, read_resource, then canonical thin tools only when needed
   • validation: confirm Copilot-visible tool inventory includes or can invoke list_resources, read_resource, search_patterns, get_pattern_by_id, and get_skill_document_by_id
   • compatibility risk: host-generated wrapper names may differ from canonical FastMCP names; document any observed wrapper-to-canonical mapping
2. Cursor
   • primary path: use the client MCP server configuration and resource/tool surfaces supported by the active Cursor version
   • fallback path: prefer resource-backed tools first, then canonical thin tools
   • validation: capture Cursor tools/list equivalent behavior and verify the canonical tool names or required host mappings
   • compatibility risk: Cursor may present MCP tools through its own UI labels or internal routing names
3. Claude Desktop
   • primary path: configure the local MCP server and inspect advertised tools/resources in Claude Desktop
   • fallback path: invoke canonical server tool names exactly as returned by tools/list
   • validation: run a local smoke prompt that reads resource://catalog/skills_index and loads one skill document through read_resource or get_skill_document_by_id
   • compatibility risk: local server configuration and transport setup may fail before tool-name compatibility is tested
4. Generic MCP clients and SDK-based tests
   • primary path: protocol-level resources/list, resources/read, tools/list, and tools/call
   • fallback path: none beyond the canonical tool contract
   • validation: automated smoke tests assert exact tool names returned by tools/list and successful calls for canonical names
   • compatibility risk: SDK/client libraries may expose helper names that differ from raw protocol names

Implementation checklist:

1. Capture each target client's advertised tool names before adding aliases.
2. Prefer fixing documentation or client-side mapping when the server already advertises canonical names correctly.
3. Add a server-side alias only for a confirmed major-client incompatibility.
4. Add regression tests for canonical names, resource-backed tools, and any intentionally supported aliases.
5. Keep public examples centered on list_resources/read_resource and canonical thin tool names.

Resources-As-Tools Compatibility Layer

Step 6 includes a resources-as-tools compatibility layer for clients that can call tools but not attach resources.

Rules:

1. It wraps canonical resource reads rather than re-implementing content transforms.
2. It preserves canonical URIs and metadata semantics.
3. It does not replace the minimal catalog tools listed above.
4. It is interoperability-driven and remains read-only.

Resource/Tool Parity Contract

Resources and fallback tools must agree on identity and routing metadata.

Parity requirements:

1. skill_id and ref_id are identical across both paths.
2. canonical URIs in payloads match Step 3 URI rules.
3. skill metadata (id, name, description, tags, capabilities, version) remains consistent.
4. document payload returned by get_skill_document_by_id resolves to the same canonical SKILL.md content as resource://skills/{skill_id}/document.

Relevance and Ranking Contract

Baseline matching behavior is metadata-first and deterministic.

Rules:

1. Search primarily over normalized skill metadata (id, name, description, tags).
2. Keep deterministic ordering and deterministic pagination behavior.
3. Keep ranking logic transparent and bounded for predictable client behavior.

Optional extension policy:

1. BM25/regex augmentation is allowed only when catalog/tool volume meaningfully harms token efficiency or precision.
2. Any augmentation must preserve canonical ids, URIs, and deterministic tie-breaking.
3. Any augmentation remains discovery-only and does not create alternate content payloads.

Context-Bounding and Clarification Policy

To prevent context bloat and improve answer quality:

1. load only the most relevant skill document by default
2. load at most two skill documents in one pass unless the user explicitly asks for more
3. if confidence is low after catalog discovery, ask one clarifying question before loading additional skill documents
4. fetch references lazily and only when required

Security and Safety Constraints

Fallback tools must preserve the project security invariant.

Rules:

1. tool surfaces stay documentation-only and read-only
2. no mutation, shell execution, secret access, or private filesystem exposure
3. all returned content remains safe to publish publicly

Integration Boundaries

Step 6 integrates with prior steps as follows:

1. Step 4 provides the validated in-memory registry.
2. Step 5 provides canonical resource registration.
3. Step 6 adds fallback discovery/read behavior that reuses the same registry and canonical markdown sources.

Separation-of-concerns rule:

1. Catalog/resource contracts remain canonical.
2. Fallback tools are interoperability adapters, not a parallel architecture.

Acceptance Criteria for Step 6 Completion

Step 6 is complete when all are true:

1. Resource-first discovery remains the documented and implemented default path.
2. list_resources and read_resource are available for tool-only clients.
3. Thin catalog tools remain minimal, read-only parity surfaces.
4. Fallback tool outputs map to canonical skill identities and URIs.
5. Context loading is bounded and clarifying-question behavior is documented for low-confidence cases.
6. No second content source is introduced; resources and tools resolve the same authored markdown.

Non-goals for Step 6

1. No write or side-effecting tools.
2. No alternate authored markdown stores or duplicated skill content pipelines.
3. No guarantee that every client session exposes MCP resource attachment UI.
4. No packaging/build contract changes (handled in Step 7).
5. No CI gate expansion details (handled in later validation/governance steps).