thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions

add milestones

Browse source
This commit is contained in:
Thales Maciel 2026-03-14 11:18:48 -03:00
parent 663241d5d2
commit aeed5e1943
No known key found for this signature in database
GPG key ID: 33112E6833C34679
6 changed files with 300 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

47
docs/roadmap/llm-chat-ergonomics.md
View file

@ -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

55
docs/roadmap/llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md Normal file
View file

@ -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

50
docs/roadmap/llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md Normal file
View file

@ -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`

52
docs/roadmap/llm-chat-ergonomics/4.8.0-first-class-chat-environment-selection.md Normal file
View file

@ -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

52
docs/roadmap/llm-chat-ergonomics/4.9.0-real-repo-qualification-smokes.md Normal file
View file

@ -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

53
docs/roadmap/llm-chat-ergonomics/5.0.0-whole-project-sandbox-development.md Normal file
View file

@ -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