Umbrella: gaps blocking LLM MCP kit catalog (workflows, content groups, resolve policy)

[enricopiovesan]

Summary

Traverse companion: traverse-framework/traverse#865

Registry-side gap inventory so LLM MCP reference façades can discover and execute the same kit capabilities/workflows OS shells use — without expedition-only bundles or prompt “skills”.

Companion issues:

• Traverse (runtime / traverse-mcp): Gaps blocking LLM MCP reference façades (opened with this work)
• Traverse multi-OS umbrella: #826
• Prior registry umbrella (closed foundation): #69
• App-Refs consumer lane: docs/llm-reference-apps-plan.md / PR #238

Meta	Value
Kind	Tracking umbrella + child DoDs — not one mega-PR
Board	Project 3 — Registry
Evidence date	2026-07-29 (registry tree + capability contracts; index tags through index-v59)

Do not claim this umbrella as a single coding ticket. Split into Project 3 children. Runtime/MCP host work stays on Traverse.

---

Problem statement

LLM façades need a published, discoverable kit that MCP can load as source of truth:

Need	Registry today
Capability WASM for starter / doc-approval / meeting-notes	Present under capabilities/ (multiple versions; real 1.1.0 agents exist for several)
Workflows for kit pipelines as first-class published artifacts	Missing from public index — workflows/ only has examples/expedition/plan-expedition
Index entries for workflows / content groups for MCP	Index schema is capabilities-only (capabilities[]); no workflow records
LLM-oriented discovery metadata (tool titles, examples, content-group membership)	Contracts have summary/description/inputs.schema but no MCP/content-group profile
Clear “use this version for product/LLM demos” pin	Version soup: 1.0.0 (some stub digests), 1.0.1 fixtures, 1.1.0 real — easy for MCP/^1 to resolve poorly without policy

Traverse MCP currently bypasses this catalog and loads the expedition example bundle instead. Registry must publish what MCP should load.

---

Evidence (2026-07-29)

G1 — No published kit workflows in the public index

registry/workflows/examples/expedition/plan-expedition/workflow.json   ← only tree content
registry index: { capabilities: [...] }                               ← no workflows array

App-Refs / OS starter pipeline is validate → process → summarize (Spec 058). Meeting-notes is a single process capability. For LLM Mode A, MCP entrypoints should be workflow ids (or an explicit single-cap entrypoint) published here — not rediscovered from Traverse examples/.

G2 — No MCP / LLM content-group publication

Nothing in the registry defines content groups such as:

• traverse-starter → workflow + three capabilities
• meeting-notes → meeting-notes.process
• doc-approval → analyze → recommend

MCP’s list_content_groups / describe_content_group therefore cannot be registry-driven.

G3 — Capability metadata is human/contract-complete but not tool-complete

Contracts already include summary, description, inputs.schema, outputs. Gaps for LLM tool routers:

• No stable tool name / tool description profile distinct from contract prose
• No governed example requests published beside the contract (MCP today uses repo request_paths)
• No machine-readable “runtime-owned output fields” list for façade prompts (App-Refs duplicates this in markdown runbooks)
• No content_groups / mcp facet on the index record (Spec 009 covers some metadata — extend or successor needed)

G4 — Version / fixture / stub clarity for ^1 consumers

Observed on kit caps (meeting-notes example):

Version	Character
1.0.0	May still carry shared stub digest sha256:5647c39a… on some historical seeds
1.0.1	Explicit fixed-output fixture in summary/description
1.1.0	Real input-consuming agent (distinct digest)

LLM façades and MCP hosts that resolve ^1.0.0 need a documented default (highest non-yanked non-fixture, or certified channel). Fixture/stub versions must be yank/deprecate-labeled so demos do not silently return constant fields while models look “smart.”

G5 — No golden “MCP kit bundle” artifact

OS embeds use app manifests + sync. MCP needs either:

• a published kit registry bundle (capabilities + workflows + example requests as artifacts), or
• a documented sync profile (“kit-llm”) that traverse-mcp / Spec 520 prepare can consume

Neither is a first-class registry release today.

G6 — Publish DX still expert-only (inherited)

From #69 / Traverse #826: adding a new workflow or content-group record is not a one-command external publish path. LLM lane will need repeatable publish → index → consume evidence.

---

Desired end state

1. Public index (or successor schema) publishes kit workflows for starter (+ optionally doc-approval) and documents meeting-notes as capability entrypoint.
2. Published content-group (or equivalent) records MCP can list/describe.
3. Each kit capability/workflow ships example runtime request JSON as a registry artifact or documented URI.
4. Default resolve policy for LLM/MCP demos selects real agents (e.g. 1.1.0+), not fixtures/stubs.
5. A smokeable kit-llm sync/bundle profile exists for Traverse MCP to load without expedition.

---

Suggested child tickets (Project 3)

Ticket ID	Focus	Depends on
publish-kit-workflows	Publish traverse-starter (and doc-approval) workflow records + index schema support	Spec for workflow-in-index (may need Specify)
publish-mcp-content-groups	Content-group records for starter / meeting-notes / doc-approval	Schema + MCP consumer contract
kit-example-runtime-requests	Publish example request JSON artifacts per entrypoint	Workflow/capability ids stable
llm-default-resolve-policy	Deprecate/yank fixtures/stubs from default ^1 demo path; document certified versions	Index + deprecated.json discipline
mcp-kit-bundle-profile	Document/release bundle or sync profile for Traverse MCP kit Mode A	Traverse mcp-kit-catalog-source
mcp-tool-metadata-facet	Optional contract/index facet: tool title, examples, runtime-owned fields	Spec 009 successor or additive

---

Definition of Done (close this umbrella)

• Child tickets created on Project 3 (or Won’t Fix with rationale) covering G1–G5
• At least one Ready/Specify ticket for kit workflow publish + index exposure
• Traverse companion issue linked; MCP catalog child explicitly depends on registry publish
• Documented resolve policy so LLM demos do not land on fixture/stub WASM by accident
• Validation: index release includes kit workflow (or documented interim bundle) and a consumer command can list them without reading Traverse examples/expedition

---

Validation

# Registry
python scripts/ci/build_index.py   # or project-standard index build
# Assert: kit workflow ids present OR kit bundle manifest published
# Assert: fixture/stub versions flagged deprecated/yanked per policy
bash scripts/ci/repository_checks.sh   # if applicable

# Cross-repo (after Traverse MCP child)
# MCP list_entrypoints includes traverse-starter / meeting-notes from registry kit — not expedition-only

---

Non-goals

• Implementing traverse-mcp itself (Traverse)
• Hosted multi-tenant MCP gateway
• Replacing claude-skills authoring guidance
• Expanding the catalog beyond kit domains in the first children

---

References

Area	Pointer
Kit capabilities	capabilities/traverse-starter/, capabilities/meeting-notes/, capabilities/doc-approval/
Workflows tree today	workflows/examples/expedition/plan-expedition/
Index pipeline	Spec 003-index-release-pipeline; Spec 009-contract-metadata-in-index
Prior umbrella	#69
App-Refs LLM plan	reference-apps #238
Traverse MCP SoT today	Traverse crates/traverse-mcp expedition bundle

[enricopiovesan]

Traverse companion (runtime/MCP): traverse-framework/traverse#865

Also related: traverse-framework/traverse#826 and App-Refs traverse-framework/reference-apps#238

[enricopiovesan]

Related, separate effort: #103 (capability-level discovery — a searchable GitHub Pages catalog + a search_capabilities MCP tool in traverse-mcp, decided via /brainstorm 2026-07-29). Different scope from this umbrella (which is workflow/content-group-focused for kit/OS-shell MCP consumers) — kept as its own tracked effort deliberately, but noting here so whichever lands second reuses the other's search infrastructure instead of rebuilding it. See docs/decision-log.md entry 40 for the full reasoning.

[enricopiovesan]

Resolved via docs/decision-log.md entry 44 (merged in #123, adding spec 001 FR-013/014/015): every real decision blocking this umbrella's children is now settled.

• Workflows become first-class index citizens (FR-013); a workflow's own capability-membership list is the "content group" answer -- no separate record type. meeting-notes.process gets a small entrypoint marker instead.
• The fixture/stub deprecation discipline this repo already follows by hand is now an explicit rule (FR-014) -- verified directly that every fixture/stub version across all 6 kit capabilities is already deprecated, so ^1 resolution already lands on real logic today.
• runtime_owned_output_fields (FR-015) covers the one genuinely new need from the tool-metadata-facet ask; tool title and example requests are already covered by summary and use_cases.
• mcp-kit-bundle-profile resolved as a documented sync convention, not a new artifact type.

Registry-side children created: #124 (workflow-index implementation), #125 (example-request artifacts), #126 (kit-llm sync-profile docs). Traverse's own companion issue is explicitly out of scope for this pass -- registry-side only, per this session's cross-repo authorization pattern.

This umbrella's own DoD (create child tickets, document a resolve policy) is met. Closing.