Add second-pass chat UX milestones
Extend the chat-ergonomics roadmap with the remaining UX work highlighted by the readiness review. Document a second pass focused on removing shell glue from canonical CLI handoff flows, making the recommended chat-host profile more obvious without changing 3.x compatibility defaults, and polishing human-mode content reads for cleaner transcripts and copy-paste behavior. Keep these milestones explicitly workspace-first and scoped to product UX, with CLI-only shortcuts allowed where the SDK and MCP surfaces already provide the structured behavior natively.
This commit is contained in:
parent
894706af50
commit
788fc4fad4
4 changed files with 176 additions and 1 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue