From aeed5e19431c7b523ae0f99bc4eae5d9b00eda42 Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Sat, 14 Mar 2026 11:18:48 -0300 Subject: [PATCH] add milestones --- docs/roadmap/llm-chat-ergonomics.md | 47 +++++++++++++--- .../4.6.0-git-tracked-project-sources.md | 55 +++++++++++++++++++ ...project-source-diagnostics-and-recovery.md | 50 +++++++++++++++++ ...-first-class-chat-environment-selection.md | 52 ++++++++++++++++++ .../4.9.0-real-repo-qualification-smokes.md | 52 ++++++++++++++++++ ...5.0.0-whole-project-sandbox-development.md | 53 ++++++++++++++++++ 6 files changed, 300 insertions(+), 9 deletions(-) create mode 100644 docs/roadmap/llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md create mode 100644 docs/roadmap/llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md create mode 100644 docs/roadmap/llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md diff --git a/docs/roadmap/llm-chat-ergonomics.md b/docs/roadmap/llm-chat-ergonomics.md index 229d3da..440f528 100644 --- a/docs/roadmap/llm-chat-ergonomics.md +++ b/docs/roadmap/llm-chat-ergonomics.md @@ -36,16 +36,16 @@ More concretely, the model should not need to: - choose from an unnecessarily large tool surface when a smaller profile would work -The next gaps for the narrowed persona are now product-shaping rather than raw -capability gaps: +The next gaps for the narrowed persona are now about real-project credibility: -- 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 +- current-checkout startup is still brittle for messy local repos with unreadable, + generated, or permission-sensitive files +- the guest-backed smoke pack is strong, but it still proves shaped scenarios + better than arbitrary local-repo readiness +- the chat-host path still does not let users choose the sandbox environment as + a first-class part of host connection and server startup +- the product should not claim full whole-project development readiness until it + qualifies a real-project loop beyond fixture-shaped use cases ## Locked Decisions @@ -61,6 +61,14 @@ capability gaps: structured behavior natively - prioritize repo-aware startup, trust, and daily-loop speed before adding more low-level workspace surface area +- for repo-root auto-detection and `--project-path` inside a Git checkout, the + default project source should become Git-tracked files only +- `--repo-url` remains the clean-clone path when users do not want to trust the + local checkout as the startup source +- environment selection must become first-class in the chat-host path before the + product claims whole-project development readiness +- real-project readiness must be proven with guest-backed qualification smokes + that cover ignored, generated, and unreadable-file cases - 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, @@ -84,6 +92,11 @@ capability gaps: 14. [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md) - Done 15. [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md) - Done 16. [`4.5.0` Faster Daily Loops](llm-chat-ergonomics/4.5.0-faster-daily-loops.md) - Done +17. [`4.6.0` Git-Tracked Project Sources](llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md) - Planned +18. [`4.7.0` Project Source Diagnostics And Recovery](llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md) - Planned +19. [`4.8.0` First-Class Chat Environment Selection](llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md) - Planned +20. [`4.9.0` Real-Repo Qualification Smokes](llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md) - Planned +21. [`5.0.0` Whole-Project Sandbox Development](llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md) - Planned Completed so far: @@ -130,6 +143,14 @@ Completed so far: real `make smoke-daily-loop` verification path so the local machine warmup story is explicit before the chat host connects. +Planned next: + +- [`4.6.0` Git-Tracked Project Sources](llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md) +- [`4.7.0` Project Source Diagnostics And Recovery](llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md) +- [`4.8.0` First-Class Chat Environment Selection](llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md) +- [`4.9.0` Real-Repo Qualification Smokes](llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md) +- [`5.0.0` Whole-Project Sandbox Development](llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md) + ## Expected Outcome After this roadmap, the product should still look like an agent workspace, not @@ -155,3 +176,11 @@ The intended model-facing shape is: - 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 +- repo-root startup is robust even when the local checkout contains ignored, + generated, or unreadable files +- chat-host users can choose the sandbox environment as part of the normal + connect/start path +- the product has guest-backed qualification for real local repos, not only + shaped fixture scenarios +- it becomes credible to tell a user they can develop a real project inside + sandboxes, not just evaluate or patch one diff --git a/docs/roadmap/llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md b/docs/roadmap/llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md new file mode 100644 index 0000000..b170b21 --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md @@ -0,0 +1,55 @@ +# `4.6.0` Git-Tracked Project Sources + +Status: Planned + +## Goal + +Make repo-root startup and `--project-path` robust for messy real checkouts by +stopping the default chat-host path from trying to ingest every readable and +unreadable file in the working tree. + +## Public API Changes + +Project-aware startup should change its default local source semantics: + +- bare `pyro mcp serve` from inside a Git checkout should seed from Git-tracked + files only +- `pyro mcp serve --project-path PATH` should also use Git-tracked files only + when `PATH` is inside a Git checkout +- `--repo-url` remains the clean-clone path when the user wants a host-side + clone instead of the local checkout +- explicit `workspace create --seed-path PATH` remains unchanged in this + milestone + +## Implementation Boundaries + +- apply the new semantics only to project-aware startup sources, not every + explicit directory seed +- do not silently include ignored or untracked junk in the default chat-host + path +- preserve explicit diff, export, sync push, and reset behavior +- surface the chosen project source clearly enough that users know what the + sandbox started from + +## Non-Goals + +- no generic SCM abstraction layer +- no silent live sync between the host checkout and the guest +- no change to explicit archive seeding semantics in this milestone + +## Acceptance Scenarios + +- starting `pyro mcp serve` from a repo root no longer fails on unreadable + build artifacts or ignored runtime byproducts +- starting from `--project-path` inside a Git repo behaves the same way +- users can predict that the startup source matches the tracked project state + rather than the entire working tree + +## Required Repo Updates + +- README, install docs, integrations docs, and public contract updated to state + what local project-aware startup actually includes +- help text updated to distinguish project-aware startup from explicit + `--seed-path` behavior +- at least one guest-backed smoke scenario added for a repo with ignored, + generated, and unreadable files diff --git a/docs/roadmap/llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md b/docs/roadmap/llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md new file mode 100644 index 0000000..a758e79 --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md @@ -0,0 +1,50 @@ +# `4.7.0` Project Source Diagnostics And Recovery + +Status: Planned + +## Goal + +Make project-source selection and startup failures understandable enough that a +chat-host user can recover without reading internals or raw tracebacks. + +## Public API Changes + +The chat-host path should expose clearer project-source diagnostics: + +- `pyro doctor` should report the active project-source kind and its readiness +- `pyro mcp serve` and host helpers should explain whether they are using + tracked local files, `--project-path`, `--repo-url`, or no project source +- startup failures should recommend the right fallback: + `--project-path`, `--repo-url`, `--no-project-source`, or explicit + `seed_path` + +## Implementation Boundaries + +- keep diagnostics focused on the chat-host path rather than inventing a broad + source-management subsystem +- prefer actionable recovery guidance over long implementation detail dumps +- make project-source diagnostics visible from the same surfaces users already + touch: help text, `doctor`, host helpers, and startup errors + +## Non-Goals + +- no generic repo-health audit product +- no attempt to auto-fix arbitrary local checkout corruption +- no host-specific divergence in project-source behavior + +## Acceptance Scenarios + +- a user can tell which project source the chat host will use before creating a + workspace +- a user who hits a project-source failure gets a concrete recovery path instead + of a raw permission traceback +- host helper doctor and repair flows can explain project-source problems, not + only MCP config problems + +## Required Repo Updates + +- docs, help text, and troubleshooting updated with project-source diagnostics + and fallback guidance +- at least one smoke or targeted CLI test covering the new failure guidance +- host-helper docs updated to show when to prefer `--project-path`, + `--repo-url`, or `--no-project-source` diff --git a/docs/roadmap/llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md b/docs/roadmap/llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md new file mode 100644 index 0000000..fcb80eb --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md @@ -0,0 +1,52 @@ +# `4.8.0` First-Class Chat Environment Selection + +Status: Planned + +## Goal + +Make curated environment choice part of the normal chat-host path so full +project work is not implicitly tied to one default environment. + +## Public API Changes + +Environment selection should become first-class in the chat-host path: + +- `pyro mcp serve` should accept an explicit environment +- `pyro host connect` should accept and preserve an explicit environment +- `pyro host print-config` and `pyro host repair` should preserve the selected + environment where relevant +- named modes should be able to recommend a default environment when one is + better for the workflow, without removing explicit user choice + +## Implementation Boundaries + +- keep environment selection aligned with the existing curated environment + catalog +- avoid inventing host-specific environment behavior for the same mode +- keep the default environment path simple for the quickest evaluator flow +- ensure the chosen environment is visible from generated config, help text, and + diagnostics + +## Non-Goals + +- no custom user-built environment pipeline in this milestone +- no per-host environment negotiation logic +- no attempt to solve arbitrary dependency installation through environment + sprawl alone + +## Acceptance Scenarios + +- a user can choose a build-oriented environment such as `debian:12-build` + before connecting the chat host +- host helpers, raw server startup, and printed configs all preserve the same + environment choice +- docs can teach whole-project development without pretending every project fits + the same default environment + +## Required Repo Updates + +- README, install docs, integrations docs, public contract, and host examples + updated to show environment selection in the chat-host path +- help text updated for raw server startup and host helpers +- at least one guest-backed smoke scenario updated to prove a non-default + environment in the chat-host flow diff --git a/docs/roadmap/llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md b/docs/roadmap/llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md new file mode 100644 index 0000000..04bea7c --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md @@ -0,0 +1,52 @@ +# `4.9.0` Real-Repo Qualification Smokes + +Status: Planned + +## Goal + +Replace fixture-only confidence with guest-backed proof that the chat-host path +works against messy local repos and clean-clone startup sources. + +## Public API Changes + +No new runtime surface is required in this milestone. The main additions are +qualification smokes and their supporting fixtures. + +The new coverage should prove: + +- repo-root startup from a local Git checkout with ignored, generated, and + unreadable files +- `--repo-url` clean-clone startup +- a realistic install, test, patch, rerun, and export loop +- at least one nontrivial service-start or readiness loop + +## Implementation Boundaries + +- keep the smoke pack guest-backed and deterministic enough to use as a release + gate +- focus on realistic repo-shape and project-loop problems, not synthetic + micro-feature assertions +- prefer a small number of representative project fixtures over a large matrix + of toy repos + +## Non-Goals + +- no promise to qualify every language ecosystem in one milestone +- no cloud or remote execution qualification layer +- no broad benchmark suite beyond what is needed to prove readiness + +## Acceptance Scenarios + +- the repo has one clear smoke target for real-repo qualification +- at least one local-checkout smoke proves the new Git-tracked startup behavior +- at least one clean-clone smoke proves the `--repo-url` path +- failures in these smokes clearly separate project-source issues from runtime + or host issues + +## Required Repo Updates + +- new guest-backed smoke targets and any supporting fixtures +- roadmap, use-case docs, and release/readiness docs updated to point at the + new qualification path +- troubleshooting updated with the distinction between shaped use-case smokes + and real-repo qualification smokes diff --git a/docs/roadmap/llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md b/docs/roadmap/llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md new file mode 100644 index 0000000..ba2195a --- /dev/null +++ b/docs/roadmap/llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md @@ -0,0 +1,53 @@ +# `5.0.0` Whole-Project Sandbox Development + +Status: Planned + +## Goal + +Reach the point where it is credible to tell a user they can develop a real +project inside sandboxes, not just validate, inspect, or patch one. + +## Public API Changes + +No new generic VM breadth is required here. This milestone should consolidate +the earlier pieces into one believable full-project product story: + +- robust project-aware startup +- explicit environment selection in the chat-host path +- summaries, reset, export, and service workflows that hold up during longer + work loops +- qualification targets that prove a nontrivial development cycle + +## Implementation Boundaries + +- keep the product centered on the chat-host workspace path rather than a broad + CLI or SDK platform story +- use the existing named modes and generic workspace path where they fit, but + teach one end-to-end full-project development walkthrough +- prioritize daily development credibility over adding new low-level sandbox + surfaces + +## Non-Goals + +- no attempt to become a generic remote dev environment platform +- no scheduler, queue, or CI matrix abstractions +- no claim that every possible project type is equally well supported + +## Acceptance Scenarios + +- the docs contain one end-to-end “develop a project in sandboxes” walkthrough +- that walkthrough covers dependency install, tests, patching, reruns, review, + and export, with app/service startup when relevant +- at least one guest-backed qualification target proves the story on a + nontrivial project +- the readiness docs can honestly say whole-project development is supported + with explicit caveats instead of hedged aspirational language + +## Required Repo Updates + +- README, install docs, integrations docs, use-case docs, and public contract + updated to include the whole-project development story +- at least one walkthrough asset or transcript added for the new end-to-end + path +- readiness and troubleshooting docs updated with the actual supported scope and + remaining caveats