Skip to content

docs: upgrade llm-mcp-reference events (upgrade-llm-mcp-reference-events) #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enricopiovesan merged 1 commit into from
Aug 12, 2026
Merged

docs: upgrade llm-mcp-reference events (upgrade-llm-mcp-reference-events) #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions apps/llm-mcp-reference/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Secondary App-References tier: **LLM product façades** that call Traverse **workflows/capabilities** through MCP instead of encoding business logic in prompt “skills”.

Shared prompts/workflows follow Specs 001/002 presentation vocabulary (`idle|loading|loaded|blocked|ended|error`) and still forbid inventing business fields — see [`shared/prompts/system-boundary.md`](shared/prompts/system-boundary.md).

Plan: [`docs/llm-reference-apps-plan.md`](../../docs/llm-reference-apps-plan.md)

## Layout
Expand Down
8 changes: 5 additions & 3 deletions apps/llm-mcp-reference/shared/prompts/system-boundary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ You are a **façade** over the Traverse runtime. You do **not** invent business

1. Use MCP / Traverse tools to **discover, validate, and execute** capabilities or workflows.
2. When presenting results, only report fields returned by the runtime (for example title, tags, noteType, suggestedNextAction, status, action items). If a field is missing, say it is missing — **do not invent it**.
3. Do not re-implement starter / doc-approval / meeting-notes pipelines in natural language “skills”.
4. If the tool fails or the runtime is offline, report the tool error. Do not fabricate a successful structured result.
5. Prefer deterministic tool execution over long chain-of-thought process control.
3. When describing session progress, use Spec 001 presentation states from runtime evidence only: `idle | loading | loaded | blocked | ended | error`. Do not invent a success/`loaded` state without a completed tool/runtime result.
4. For multi-capability runs (Spec 002), report invoke/result order from tool/runtime evidence — never from local step timers or guessed stages.
5. Do not re-implement starter / doc-approval / meeting-notes pipelines in natural language “skills”.
6. If the tool fails or the runtime is offline, report the tool error. Do not fabricate a successful structured result.
7. Prefer deterministic tool execution over long chain-of-thought process control.

## Why

Expand Down
2 changes: 2 additions & 0 deletions apps/llm-mcp-reference/shared/workflows/meeting-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ OS twins: [`apps/meeting-notes/`](../../../meeting-notes/) (Web / iOS / macOS /

Discover this entrypoint through `traverse-mcp` — do **not** hard-code private crate paths. Prefer the **governed workflow/entrypoint** the server lists for `meeting-notes.process`.

Presentation chrome (Specs 001/002): keep the session at `loading` while tools run; move to `loaded` only when runtime output fields are present; use `error` on tool/runtime failure. If the workflow exposes multiple capabilities, narrate invoke/result order from evidence only.

## Prerequisites (Mode A)

1. Traverse checkout with working `traverse-mcp` (see [MCP stdio server](https://github.com/traverse-framework/Traverse/blob/main/docs/mcp-stdio-server.md)).
Expand Down
10 changes: 5 additions & 5 deletions apps/llm-mcp-reference/shared/workflows/traverse-starter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ Use the Traverse MCP server’s discovery/description tools to locate the starte

## Happy path

1. Confirm MCP server is reachable (`describe_server` / discovery).
2. Execute with a note string input (example: `"Ship the MCP façade docs tomorrow"`).
3. Render **only** runtime fields from the execution report (e.g. title, tags, noteType, suggestedNextAction, status / validation issues / summary when present).
1. Confirm MCP server is reachable (`describe_server` / discovery) — presentation `idle` until submit.
2. Execute with a note string input (example: `"Ship the MCP façade docs tomorrow"`) — while tools run, presentation is `loading` (or `blocked` only if the runtime reports a waiting-for-human condition).
3. Render **only** runtime fields from the execution report (e.g. title, tags, noteType, suggestedNextAction, status / validation issues / summary when present) — presentation `loaded` when renderable output is present, else `ended` if the runtime completed without product fields.

## Success looks like

Same as Web starter: structured fields filled by the runtime, not by the model.
Same as Web starter: structured fields filled by the runtime, not by the model. Session chrome matches Spec 001 (`idle|loading|loaded|blocked|ended|error`).

## Failure

If execution fails, show the tool error. Do not invent a title/tags payload.
If execution fails, show the tool error and presentation `error`. Do not invent a title/tags payload.
Loading