diff --git a/docs/roadmap/llm-chat-ergonomics.md b/docs/roadmap/llm-chat-ergonomics.md index 6725c3c..8f7e43f 100644 --- a/docs/roadmap/llm-chat-ergonomics.md +++ b/docs/roadmap/llm-chat-ergonomics.md @@ -33,13 +33,24 @@ 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 best chat-host profile is recommended in docs, but not yet obvious enough + from the default live `mcp serve` path +- canonical CLI walkthroughs still need small amounts of shell glue such as + `python -c` extraction of `workspace_id` and `$(cat fix.patch)` expansion +- human-mode file reads are functional, but still need final transcript polish + for copy-paste and chat logs + ## Locked Decisions - keep the workspace product identity central; do not drift toward CI, queue, 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 -- every milestone below must update CLI, SDK, and MCP together +- capability milestones should update CLI, SDK, and MCP together +- CLI-only ergonomics are allowed when the SDK and MCP surfaces already have the + structured behavior natively - every milestone below must also update docs, help text, runnable examples, and at least one real smoke scenario @@ -50,6 +61,9 @@ More concretely, the model should not need to: 3. [`3.4.0` Tool Profiles And Canonical Chat Flows](llm-chat-ergonomics/3.4.0-tool-profiles-and-canonical-chat-flows.md) - Done 4. [`3.5.0` Chat-Friendly Shell Output](llm-chat-ergonomics/3.5.0-chat-friendly-shell-output.md) - Done 5. [`3.6.0` Use-Case Recipes And Smoke Packs](llm-chat-ergonomics/3.6.0-use-case-recipes-and-smoke-packs.md) - Done +6. [`3.7.0` Handoff Shortcuts And File Input Sources](llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md) - Planned +7. [`3.8.0` Chat-Host Onramp And Recommended Defaults](llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md) - Planned +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) - Planned Completed so far: @@ -67,6 +81,15 @@ Completed so far: cases so the stable product is now demonstrated as repeatable end-to-end stories instead of only isolated feature surfaces. +Planned next: + +- `3.7.0` removes the remaining shell glue from canonical CLI flows with shortcut flags for + identifier handoff and file-backed text inputs. +- `3.8.0` makes the recommended chat-host entrypoint obvious from the top-level docs, help text, + and shipped MCP examples without changing the `3.x` compatibility default. +- `3.9.0` makes human-mode file reads cleaner in terminals and chat logs, with explicit + content-only reads where summaries would otherwise get in the way. + ## Expected Outcome After this roadmap, the product should still look like an agent workspace, not @@ -79,4 +102,7 @@ The intended model-facing shape is: - file edits are structured and model-native - workspace discovery is human and model-friendly - 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 +- human-mode content reads are copy-paste safe - the five core use cases are documented and smoke-tested end to end diff --git a/docs/roadmap/llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md b/docs/roadmap/llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md new file mode 100644 index 0000000..5e6896f --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md @@ -0,0 +1,48 @@ +# `3.7.0` Handoff Shortcuts And File Input Sources + +Status: Planned + +## Goal + +Remove the last bits of shell plumbing from the canonical CLI workspace flows so +they feel productized instead of hand-assembled. + +## Public API Changes + +Planned additions: + +- `pyro workspace create ... --id-only` +- `pyro workspace shell open ... --id-only` +- `pyro workspace file write WORKSPACE_ID PATH --text-file PATH` +- `pyro workspace patch apply WORKSPACE_ID --patch-file PATH` + +## Implementation Boundaries + +- keep existing `--json`, `--text`, and `--patch` stable +- treat these additions as CLI-only shortcuts over already-structured behavior +- make `--text` and `--text-file` mutually exclusive +- make `--patch` and `--patch-file` mutually exclusive +- read file-backed text and patch inputs as UTF-8 text +- keep `/workspace` scoping and current patch semantics unchanged + +## Non-Goals + +- no new binary file-write story +- no new SDK or MCP surface just to mirror CLI shorthand flags +- no hidden patch normalization beyond the current patch-apply rules +- no change to the stable `workspace_id` contract + +## Acceptance Scenarios + +- README, install docs, and first-run docs can create one workspace ID without + `python -c` output parsing +- a user can apply a patch from `fix.patch` without `$(cat fix.patch)` shell + expansion +- a user can write one text file from a host file directly, without + shell-escaped inline text + +## Required Repo Updates + +- top-level workspace walkthroughs rewritten around the new shortcut flags +- CLI help text updated so the shortest happy path is copy-paste friendly +- at least one smoke scenario updated to use a file-backed patch input diff --git a/docs/roadmap/llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md b/docs/roadmap/llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md new file mode 100644 index 0000000..0feb93c --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md @@ -0,0 +1,51 @@ +# `3.8.0` Chat-Host Onramp And Recommended Defaults + +Status: Planned + +## Goal + +Make the recommended chat-host entrypoint obvious before a new integrator has +to read deep integration docs. + +## Public API Changes + +No breaking API change is required in this milestone. + +The main user-visible change is guidance: + +- `pyro mcp serve` help text should clearly call `workspace-core` the + recommended chat-host profile +- README, install docs, first-run docs, and shipped MCP configs should all lead + with `workspace-core` +- `workspace-full` should be framed as the explicit advanced/compatibility + surface for `3.x` + +## Implementation Boundaries + +- keep the `3.x` compatibility default unchanged +- do not add new profile names +- make the recommendation visible from help text and top-level docs, not only + the integrations page +- keep provider examples and MCP examples aligned on the same profile story + +## Non-Goals + +- no breaking default flip to `workspace-core` in `3.x` +- no new hidden server behavior based on client type +- no divergence between CLI, SDK, and MCP terminology for the profile ladder + +## Acceptance Scenarios + +- a new chat-host integrator sees `workspace-core` as the recommended first MCP + profile from the first help/doc pass +- the top-level docs include one tiny chat-host quickstart near the first-run + path +- shipped config examples and provider examples all align on the same profile + progression + +## Required Repo Updates + +- top-level docs updated with a minimal chat-host quickstart +- `pyro mcp serve --help` rewritten to emphasize `workspace-core` +- examples and config snippets audited so they all agree on the recommended + profile diff --git a/docs/roadmap/llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md b/docs/roadmap/llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md new file mode 100644 index 0000000..5b9901e --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md @@ -0,0 +1,50 @@ +# `3.9.0` Content-Only Reads And Human Output Polish + +Status: Planned + +## Goal + +Make human-mode content reads cleaner for chat logs, terminal transcripts, and +copy-paste workflows. + +## Public API Changes + +Planned additions: + +- `pyro workspace file read WORKSPACE_ID PATH --content-only` +- `pyro workspace disk read WORKSPACE_ID PATH --content-only` + +Behavioral polish: + +- default human-mode `workspace file read` and `workspace disk read` should + always separate content from summaries cleanly, even when the file lacks a + trailing newline + +## Implementation Boundaries + +- keep JSON output unchanged +- keep human-readable summary lines by default +- `--content-only` should print only the file content and no summary footer +- keep current regular-file-only constraints for live and stopped-disk reads + +## Non-Goals + +- no new binary dumping contract +- no removal of human summaries from the default read path +- no expansion into a generic pager or TUI reader +- no change to SDK or MCP structured read results, which are already summary-free + +## Acceptance Scenarios + +- reading a text file with no trailing newline still produces a clean transcript +- a user can explicitly request content-only output for copy-paste or shell + piping +- docs can show both summary mode and content-only mode without caveats about + messy output joining + +## Required Repo Updates + +- CLI help text updated for file and disk read commands +- stable docs and transcripts revised to use `--content-only` where it improves + readability +- tests that cover missing trailing newline cases in human mode