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
|
- choose from an unnecessarily large tool surface when a smaller profile would
|
||||||
work
|
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
|
## Locked Decisions
|
||||||
|
|
||||||
- keep the workspace product identity central; do not drift toward CI, queue,
|
- keep the workspace product identity central; do not drift toward CI, queue,
|
||||||
or runner abstractions
|
or runner abstractions
|
||||||
- keep disk tools secondary and do not make them the main chat-facing surface
|
- 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
|
- 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,
|
- every milestone below must also update docs, help text, runnable examples,
|
||||||
and at least one real smoke scenario
|
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
|
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
|
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
|
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:
|
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
|
cases so the stable product is now demonstrated as repeatable end-to-end stories instead of
|
||||||
only isolated feature surfaces.
|
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
|
## Expected Outcome
|
||||||
|
|
||||||
After this roadmap, the product should still look like an agent workspace, not
|
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
|
- file edits are structured and model-native
|
||||||
- workspace discovery is human and model-friendly
|
- workspace discovery is human and model-friendly
|
||||||
- shells are readable in chat
|
- 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
|
- 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