From 9b9b83ebebd9664afb6cecb5f495531e7060d494 Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Fri, 13 Mar 2026 15:18:02 -0300 Subject: [PATCH] Add post-4.0 chat product roadmap Extend the chat ergonomics roadmap now that the core workspace and MCP path are in place for the narrowed chat-host persona. Add the next planned phase around project-aware chat startup, host bootstrap and repair, reviewable agent output, opinionated use-case modes, and faster daily loops so the roadmap keeps pushing toward a repo-aware daily tool instead of a generic VM or SDK story. Document the constraints explicitly: optimize the MCP/chat-host path first, keep disk tools secondary, and take advantage of the current no-users-yet window to make breaking product-shaping changes when needed. --- docs/roadmap/llm-chat-ergonomics.md | 43 ++++++++++++-- .../4.1.0-project-aware-chat-startup.md | 56 ++++++++++++++++++ .../4.2.0-host-bootstrap-and-repair.md | 53 +++++++++++++++++ .../4.3.0-reviewable-agent-output.md | 54 ++++++++++++++++++ .../4.4.0-opinionated-use-case-modes.md | 56 ++++++++++++++++++ .../4.5.0-faster-daily-loops.md | 57 +++++++++++++++++++ 6 files changed, 313 insertions(+), 6 deletions(-) create mode 100644 docs/roadmap/llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.3.0-reviewable-agent-output.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.5.0-faster-daily-loops.md diff --git a/docs/roadmap/llm-chat-ergonomics.md b/docs/roadmap/llm-chat-ergonomics.md index 93fa8e4..fa66522 100644 --- a/docs/roadmap/llm-chat-ergonomics.md +++ b/docs/roadmap/llm-chat-ergonomics.md @@ -8,10 +8,13 @@ interface. Current baseline is `4.0.0`: -- the stable workspace contract exists across CLI, SDK, and MCP -- one-shot `pyro run` still exists as the narrow entrypoint +- `pyro mcp serve` is now the default product entrypoint +- `workspace-core` is now the default MCP profile +- one-shot `pyro run` still exists as the terminal companion path - workspaces already support seeding, sync push, exec, export, diff, snapshots, reset, services, PTY shells, secrets, network policy, and published ports +- host-specific onramps exist for Claude Code, Codex, and OpenCode +- the five documented use cases are now recipe-backed and smoke-tested - stopped-workspace disk tools now exist, but remain explicitly secondary ## What "Trivial In Chat" Means @@ -33,9 +36,16 @@ More concretely, the model should not need to: - choose from an unnecessarily large tool surface when a smaller profile would work -The remaining UX friction for a technically strong new user is now narrower: +The next gaps for the narrowed persona are now product-shaping rather than raw +capability gaps: -- no major chat-host ergonomics gaps remain in the current roadmap +- starting from the current repo still needs to feel native from the first chat +- host setup and repair still lean on manual commands and config copying +- reviewing what the agent actually did still requires digging through several + surfaces +- the five use cases exist as docs and smokes, not yet as explicit product + modes +- daily reset and retry loops can still feel heavier than they should ## Locked Decisions @@ -43,9 +53,16 @@ The remaining UX friction for a technically strong new user is now narrower: or runner abstractions - keep disk tools secondary and do not make them the main chat-facing surface - prefer narrow tool profiles and structured outputs over more raw shell calls -- capability milestones should update CLI, SDK, and MCP together +- optimize the MCP/chat-host path first and keep the CLI companion path good + enough to validate and debug it +- lower-level SDK and repo substrate work can continue, but they should not + drive milestone scope or naming - CLI-only ergonomics are allowed when the SDK and MCP surfaces already have the structured behavior natively +- prioritize repo-aware startup, trust, and daily-loop speed before adding more + low-level workspace surface area +- breaking changes are acceptable while there are still no users and the + chat-host product is still being shaped - every milestone below must also update docs, help text, runnable examples, and at least one real smoke scenario @@ -62,6 +79,11 @@ The remaining UX friction for a technically strong new user is now narrower: 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) - Done 10. [`3.11.0` Host-Specific MCP Onramps](llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md) - Done 11. [`4.0.0` Workspace-Core Default Profile](llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md) - Done +12. [`4.1.0` Project-Aware Chat Startup](llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md) - Planned +13. [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md) - Planned +14. [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md) - Planned +15. [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md) - Planned +16. [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md) - Planned Completed so far: @@ -95,7 +117,11 @@ Completed so far: Planned next: -- no further chat-ergonomics milestones are currently planned in this roadmap. +- [`4.1.0` Project-Aware Chat Startup](llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md) +- [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md) +- [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md) +- [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md) +- [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md) ## Expected Outcome @@ -117,3 +143,8 @@ The intended model-facing shape is: - 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 +- starting from the current repo feels native from the first chat-host setup +- supported hosts can be connected or repaired without manual config spelunking +- users can review one concise summary of what the agent changed and ran +- the main workflows feel like named modes instead of one giant reference +- reset and retry loops are fast enough to encourage daily use diff --git a/docs/roadmap/llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md b/docs/roadmap/llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md new file mode 100644 index 0000000..38a86fd --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md @@ -0,0 +1,56 @@ +# `4.1.0` Project-Aware Chat Startup + +Status: Planned + +## Goal + +Make "current repo to disposable sandbox" the default story for the narrowed +chat-host user, without requiring manual workspace seeding choreography first. + +## Public API Changes + +The chat entrypoint should gain one documented project-aware startup path: + +- `pyro mcp serve` should accept an explicit local project source, such as the + current checkout +- the product path should optionally support a clean-clone source, such as a + repo URL, when the user is not starting from a local checkout +- the first useful chat turn should not depend on manually teaching + `workspace create ... --seed-path ...` before the host can do real work + +Exact flag names can still change, but the product needs one obvious "use this +repo" path and one obvious "start from that repo" path. + +## Implementation Boundaries + +- keep host crossing explicit; do not silently mutate the user's checkout +- prefer local checkout seeding first, because that is the most natural daily + chat path +- preserve existing explicit sync, export, diff, and reset primitives rather + than inventing a hidden live-sync layer +- keep the startup story compatible with the existing `workspace-core` product + path + +## Non-Goals + +- no generic SCM integration platform +- no background multi-repo workspace manager +- no always-on bidirectional live sync between host checkout and guest + +## Acceptance Scenarios + +- from a repo root, a user can connect Claude Code, Codex, or OpenCode and the + first workspace starts from that repo without extra terminal choreography +- from outside a repo checkout, a user can still start from a documented clean + source such as a repo URL +- the README and install docs can teach a repo-aware chat flow before the + manual terminal workspace flow + +## Required Repo Updates + +- README, install docs, first-run docs, integrations docs, and public contract + updated to show the repo-aware chat startup path +- help text updated so the repo-aware startup path is visible from `pyro` and + `pyro mcp serve --help` +- at least one recipe and one real smoke scenario updated to validate the new + startup story diff --git a/docs/roadmap/llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md b/docs/roadmap/llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md new file mode 100644 index 0000000..4ccf34b --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md @@ -0,0 +1,53 @@ +# `4.2.0` Host Bootstrap And Repair + +Status: Planned + +## Goal + +Make supported chat hosts feel one-command to connect and easy to repair when a +local config drifts or the product changes shape. + +## Public API Changes + +The CLI should grow a small host-helper surface for the supported chat hosts: + +- `pyro host connect claude-code` +- `pyro host connect codex` +- `pyro host print-config opencode` +- `pyro host doctor` +- `pyro host repair HOST` + +The exact names can still move, but the product needs a first-class bootstrap +and repair path for Claude Code, Codex, and OpenCode. + +## Implementation Boundaries + +- host helpers should wrap the same `pyro mcp serve` entrypoint rather than + introduce per-host runtime behavior +- config changes should remain inspectable and predictable +- support both installed-package and `uvx`-style usage where that materially + reduces friction +- keep the host helper story narrow to the current supported hosts + +## Non-Goals + +- no GUI installer or onboarding wizard +- no attempt to support every possible MCP-capable editor or chat shell +- no hidden network service or account-based control plane + +## Acceptance Scenarios + +- a new Claude Code or Codex user can connect `pyro` with one command +- an OpenCode user can print or materialize a correct config without hand-writing + JSON +- a user with a stale or broken local host config can run one repair or doctor + flow instead of debugging MCP setup manually + +## Required Repo Updates + +- new host-helper docs and examples for all supported chat hosts +- README, install docs, and integrations docs updated to prefer the helper + flows when available +- help text updated with exact connect and repair commands +- runnable verification or smoke coverage that proves the shipped host-helper + examples stay current diff --git a/docs/roadmap/llm-chat-ergonomics/4.3.0-reviewable-agent-output.md b/docs/roadmap/llm-chat-ergonomics/4.3.0-reviewable-agent-output.md new file mode 100644 index 0000000..838a28c --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.3.0-reviewable-agent-output.md @@ -0,0 +1,54 @@ +# `4.3.0` Reviewable Agent Output + +Status: Planned + +## Goal + +Make it easy for a human to review what the agent actually did inside the +sandbox without manually reconstructing the session from diffs, logs, and raw +artifacts. + +## Public API Changes + +The product should expose a concise workspace review surface, for example: + +- `pyro workspace summary WORKSPACE_ID` +- `workspace_summary` on the MCP side +- structured JSON plus a short human-readable summary view + +The summary should cover the things a chat-host user cares about: + +- commands run +- files changed +- diff or patch summary +- services started +- artifacts exported +- final workspace outcome + +## Implementation Boundaries + +- prefer concise review surfaces over raw event firehoses +- keep raw logs, diffs, and exported files available as drill-down tools +- summarize only the sandbox activity the product can actually observe +- make the summary good enough to paste into a chat, bug report, or PR comment + +## Non-Goals + +- no full compliance or audit product +- no attempt to summarize the model's hidden reasoning +- no remote storage backend for session history + +## Acceptance Scenarios + +- after a repro-fix or review-eval run, a user can inspect one summary and + understand what changed and what to review next +- the summary is useful enough to accompany exported patches or artifacts +- unsafe-inspection and review-eval flows become easier to trust because the + user can review agent-visible actions in one place + +## Required Repo Updates + +- public contract, help text, README, and recipe docs updated with the new + summary path +- at least one host-facing example showing how to ask for or export the summary +- at least one real smoke scenario validating the review surface end to end diff --git a/docs/roadmap/llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md b/docs/roadmap/llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md new file mode 100644 index 0000000..c57f951 --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md @@ -0,0 +1,56 @@ +# `4.4.0` Opinionated Use-Case Modes + +Status: Planned + +## Goal + +Stop making chat-host users think in terms of one giant workspace surface and +let them start from a small mode that matches the job they want the agent to do. + +## Public API Changes + +The chat entrypoint should gain named use-case modes, for example: + +- `pyro mcp serve --mode repro-fix` +- `pyro mcp serve --mode inspect` +- `pyro mcp serve --mode cold-start` +- `pyro mcp serve --mode review-eval` + +Modes should narrow the product story by selecting the right defaults for: + +- tool surface +- workspace bootstrap behavior +- docs and example prompts +- expected export and review outputs + +Parallel workspace use should come from opening more than one named workspace +inside the same mode, not from introducing a scheduler or queue abstraction. + +## Implementation Boundaries + +- build modes on top of the existing `workspace-core` and `workspace-full` + capabilities instead of inventing separate backends +- keep the mode list short and mapped to the documented use cases +- make modes visible from help text, host helpers, and recipe docs together +- let users opt out to the generic workspace path when the mode is too narrow + +## Non-Goals + +- no user-defined mode DSL +- no hidden host-specific behavior for the same mode name +- no CI-style pipelines, matrix builds, or queueing abstractions + +## Acceptance Scenarios + +- a new user can pick one mode and avoid reading the full workspace surface + before starting +- the documented use cases map cleanly to named entry modes +- parallel issue or PR work feels like "open another workspace in the same + mode", not "submit another job" + +## Required Repo Updates + +- help text, README, install docs, integrations docs, and use-case recipes + updated to teach the named modes +- host-specific setup docs updated so supported hosts can start in a named mode +- at least one smoke scenario proving a mode-specific happy path end to end diff --git a/docs/roadmap/llm-chat-ergonomics/4.5.0-faster-daily-loops.md b/docs/roadmap/llm-chat-ergonomics/4.5.0-faster-daily-loops.md new file mode 100644 index 0000000..01c765c --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.5.0-faster-daily-loops.md @@ -0,0 +1,57 @@ +# `4.5.0` Faster Daily Loops + +Status: Planned + +## Goal + +Make the day-to-day chat-host loop feel cheap enough that users reach for it +for normal work, not only for special high-isolation tasks. + +## Public API Changes + +The product should add an explicit fast-path for repeated local use, such as: + +- a prewarm or prepare path for the recommended environment and runtime +- a clearer fast reset or retry path for repeated repro-fix loops +- visible diagnostics for cache, prewarm, or ready-state health + +The exact command names can still move, but the user-visible story needs to be: + +- set the machine up once +- reconnect quickly +- create or reset a workspace cheaply +- keep iterating without redoing heavy setup work + +## Implementation Boundaries + +- optimize local-first loops on one machine before thinking about remote + execution +- focus on startup, create, reset, and retry latency rather than queue + throughput +- keep the fast path compatible with the repo-aware startup story and the + supported chat hosts +- prefer explicit caching and prewarm semantics over hidden long-running + daemons + +## Non-Goals + +- no cloud prewarm service +- no scheduler or queueing layer +- no daemon requirement for normal daily use + +## Acceptance Scenarios + +- after the first setup, entering the chat-host path again does not feel like + redoing the whole product onboarding +- reset and retry become cheap enough to recommend as the default repro-fix + workflow +- docs can present `pyro` as a daily coding-agent tool, not only as a special + heavy-duty sandbox + +## Required Repo Updates + +- docs updated to show the recommended daily-use fast path +- diagnostics and help text updated so the user can tell whether the machine is + already warm and ready +- at least one repeat-loop smoke or benchmark-style verification scenario + added to prevent regressions in the daily workflow