From d05fba6c15acbcac6935dcd650e912d974c34d9a Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Fri, 13 Mar 2026 12:06:00 -0300 Subject: [PATCH] Add next chat UX roadmap milestones Capture the next UX pass after the workspace-core readiness review so the roadmap reflects the remaining friction a new chat-host user still feels. Add milestones for trustworthy use-case smoke coverage, host-specific Claude/Codex/OpenCode MCP onramps, and the planned 4.0 default flip to workspace-core so the bare server entrypoint finally matches the recommended path. This is a docs-only roadmap update based on the live use-case review and integration validation, with the full advanced surface kept as an explicit opt-in rather than the default. --- docs/roadmap/llm-chat-ergonomics.md | 27 +++++++++ ...se-case-smoke-trust-and-recipe-fidelity.md | 54 ++++++++++++++++++ .../3.11.0-host-specific-mcp-onramps.md | 56 +++++++++++++++++++ .../4.0.0-workspace-core-default-profile.md | 55 ++++++++++++++++++ 4 files changed, 192 insertions(+) create mode 100644 docs/roadmap/llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md create mode 100644 docs/roadmap/llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md diff --git a/docs/roadmap/llm-chat-ergonomics.md b/docs/roadmap/llm-chat-ergonomics.md index dcdcebe..78f59c6 100644 --- a/docs/roadmap/llm-chat-ergonomics.md +++ b/docs/roadmap/llm-chat-ergonomics.md @@ -37,6 +37,12 @@ The remaining UX friction for a technically strong new user is now narrower: - the recommended chat-host onramp is now explicit, but human-mode file reads still need final transcript polish for copy-paste and chat logs +- the five use-case smokes now exist, but the advertised smoke pack is only as + trustworthy as its weakest scenario and exact recipe fidelity +- generic MCP guidance is strong, but Codex and OpenCode still ask the user to + translate the generic config into host-specific setup steps +- `workspace-core` is clearly the recommended profile, but `pyro mcp serve` and + `create_server()` still default to `workspace-full` for `3.x` compatibility ## Locked Decisions @@ -60,6 +66,9 @@ The remaining UX friction for a technically strong new user is now narrower: 6. [`3.7.0` Handoff Shortcuts And File Input Sources](llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md) - Done 7. [`3.8.0` Chat-Host Onramp And Recommended Defaults](llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md) - Done 8. [`3.9.0` Content-Only Reads And Human Output Polish](llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md) - Done +9. [`3.10.0` Use-Case Smoke Trust And Recipe Fidelity](llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md) +10. [`3.11.0` Host-Specific MCP Onramps](llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md) +11. [`4.0.0` Workspace-Core Default Profile](llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md) Completed so far: @@ -84,6 +93,20 @@ Completed so far: - `3.9.0` added content-only workspace file and disk reads plus cleaner default human-mode transcript separation for files that do not end with a trailing newline. +Planned next: + +- `3.10.0` makes the use-case recipe set fully trustworthy by requiring + `make smoke-use-cases` to pass cleanly, aligning recipe docs with what the + smoke harness actually proves, and removing brittle assertions against + human-mode output when structured results are already available. +- `3.11.0` adds exact host-specific onramps for Claude, Codex, and OpenCode so + a new chat-host user can copy one known-good config or command instead of + translating the generic MCP example by hand. +- `4.0.0` flips the default MCP profile from `workspace-full` to + `workspace-core` so the no-flag server entrypoint finally matches the + recommended docs path, while keeping explicit opt-in access to the full + advanced surface. + ## Expected Outcome After this roadmap, the product should still look like an agent workspace, not @@ -98,5 +121,9 @@ The intended model-facing shape is: - shells are readable in chat - CLI handoff paths do not depend on ad hoc shell parsing - the recommended chat-host profile is obvious from the first MCP example +- the documented smoke pack is trustworthy enough to use as a release gate +- major chat hosts have copy-pasteable MCP setup examples instead of only a + generic config template - human-mode content reads are copy-paste safe +- the default bare MCP server entrypoint matches the recommended narrow profile - the five core use cases are documented and smoke-tested end to end diff --git a/docs/roadmap/llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md b/docs/roadmap/llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md new file mode 100644 index 0000000..6fd61b6 --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md @@ -0,0 +1,54 @@ +# `3.10.0` Use-Case Smoke Trust And Recipe Fidelity + +Status: Planned + +## Goal + +Make the documented use-case pack trustworthy enough to act like a real release +gate for the advertised chat-first workflows. + +## Public API Changes + +No new core API is required in this milestone. + +The user-visible change is reliability and alignment: + +- `make smoke-use-cases` should pass cleanly on a supported host +- each smoke scenario should verify the same user-facing path the recipe docs + actually recommend +- smoke assertions should prefer structured CLI, SDK, or MCP results over + brittle checks against human-mode text formatting when both exist + +## Implementation Boundaries + +- fix the current repro-plus-fix drift as part of this milestone +- keep the focus on user-facing flow fidelity, not on broad internal test + harness refactors +- prefer exact recipe fidelity over inventing more synthetic smoke-only steps +- if the docs say one workflow is canonical, the smoke should exercise that same + workflow directly + +## Non-Goals + +- no new workspace capability just to make the smoke harness easier to write +- no conversion of the product into a CI/reporting framework +- no requirement that every README transcript becomes a literal byte-for-byte + golden test + +## Acceptance Scenarios + +- `make smoke-use-cases` passes end to end on a supported host +- the repro-plus-fix smoke proves the documented patch path without relying on + fragile human-output assumptions +- each use-case recipe still maps to one real guest-backed smoke target +- a maintainer can trust a red smoke result as a real user-facing regression, + not just harness drift + +## Required Repo Updates + +- use-case smoke scenarios audited and corrected to follow the canonical docs +- any brittle human-output assertions replaced with structured checks where + possible +- docs updated if a recipe or expected output changed during the alignment pass +- at least one release/readiness note should point to the smoke pack as a + trustworthy verification path once this lands diff --git a/docs/roadmap/llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md b/docs/roadmap/llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md new file mode 100644 index 0000000..db44805 --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md @@ -0,0 +1,56 @@ +# `3.11.0` Host-Specific MCP Onramps + +Status: Planned + +## Goal + +Remove the last translation step for major chat hosts by shipping exact, +copy-pasteable MCP setup guidance for the hosts users actually reach for. + +## Public API Changes + +No core runtime or workspace API change is required in this milestone. + +The main user-visible additions are host-specific integration assets and docs: + +- Claude setup should have a first-class maintained example +- Codex should have a first-class maintained example +- OpenCode should have a first-class maintained example +- the integrations docs should show the shortest working path for each host and + the same recommended `workspace-core` profile + +## Implementation Boundaries + +- keep the underlying server command the same: + `pyro mcp serve --profile workspace-core` +- treat host-specific configs as thin wrappers around the same MCP server +- cover both package-without-install and already-installed variants where that + materially improves copy-paste adoption +- keep generic MCP config guidance, but stop forcing users of major hosts to + translate it themselves + +## Non-Goals + +- no client-specific runtime behavior hidden behind host detection +- no broad matrix of every MCP-capable editor or agent host +- no divergence in terminology between host examples and the public contract + +## Acceptance Scenarios + +- a Claude user can copy one shipped example and connect without reading generic + MCP docs first +- a Codex user can copy one shipped example or exact `codex mcp add ...` command +- an OpenCode user can copy one shipped config snippet without guessing its MCP + schema shape +- the README and integrations docs point to those host-specific examples from + the first integration pass + +## Required Repo Updates + +- new shipped config examples for Codex and OpenCode +- README, install docs, and integrations docs updated to point at the new host + examples +- at least one short host-specific quickstart section or example command for + each supported host family +- runnable or documented verification steps that prove the shipped examples stay + current diff --git a/docs/roadmap/llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md b/docs/roadmap/llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md new file mode 100644 index 0000000..104fb6e --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md @@ -0,0 +1,55 @@ +# `4.0.0` Workspace-Core Default Profile + +Status: Planned + +## Goal + +Make the default MCP entrypoint match the product's recommended chat-first path +instead of preserving a wider compatibility surface by default. + +## Public API Changes + +This is an intentional breaking default change for the next major release: + +- `pyro mcp serve` should default to `workspace-core` +- `create_server()` should default to `profile="workspace-core"` +- `Pyro.create_server()` should default to `profile="workspace-core"` + +The full advanced surface remains available through explicit opt-in: + +- `pyro mcp serve --profile workspace-full` +- `create_server(profile="workspace-full")` +- `Pyro.create_server(profile="workspace-full")` + +## Implementation Boundaries + +- keep all three profile names unchanged +- do not remove `workspace-full` +- make the default flip explicit in docs, changelog, help text, and migration + notes +- keep bare `vm-run` available as the smallest one-shot profile + +## Non-Goals + +- no silent removal of advanced workspace capabilities +- no attempt to infer a profile from the client name +- no `3.x` backport that changes the current default behavior + +## Acceptance Scenarios + +- a bare `pyro mcp serve` command now exposes the recommended narrow profile +- a bare `create_server()` or `Pyro.create_server()` call matches that same + default +- advanced hosts can still opt into `workspace-full` explicitly with no loss of + functionality +- docs no longer need to explain that the recommended path and the default path + are different + +## Required Repo Updates + +- help text, public contract, README, install docs, and integrations docs + revised to reflect the new default +- migration note explaining the default change and the explicit + `workspace-full` opt-in path +- examples audited so they only mention `--profile workspace-core` when the + explicitness is useful rather than compensating for the old default