feat: switch Python tooling to uv and tighten planning#22
Merged
Conversation
MrPointer
force-pushed
the
feature/switch-to-uv
branch
2 times, most recently
from
1e1b62c to
072fd76
Compare
Capture the accepted uv migration design before planning so the Python tooling cleanup has a reviewed architectural baseline.
Provide reusable project-local workers for Go, Zsh, docs, and test authoring so feature plans can bind execution to explicit model tiers and required skills instead of relying on the current session.
The goal is to switch from pyenv to uv for Python management, as uv becomes the industry standard nowadays, and can safely replace most of pyenv's capabilities, as well as others'.
The recent feature tried to make itself the center of the solution, but it should've been treated merely as an example.
When the split happened, the model was lazy with the rfc variant, trying to defer to the direct variant directly, but in practice, that caused the agent to get confused and produce sub-par results. It also improves how opencode spawns subagents inline, using their own recommended way instead of some hallucinated one.
For easier diagnosis of what happened, such as not spawning worker agents, or spawning them with the wrong model, the skill now performs a "preflight" step that fills the progress file with the real-time data. It also is better instructed now to pay attention to worker agents, following the plan's intention rather than deciding on its own. At last, just as with the planning skill, the bindings were slightly corrected to perform better, especially for opencode regarding subagent spawning.
They more strictly verify the master plan contains dispatch instructions, which is necessary for plans with more than 2 sub-plans, as each sub-plan is assigned a worker agent with a carefully selected model tier, in an effort to reduce costs.
The Claude runtime adapters told the planner to launch reviewers with subagent_type "general-purpose", on the rationale that this would let them inherit Write/Edit from the agent definition. The opposite is true: dispatching as general-purpose discards the reviewer's specialized system prompt and replaces its declared tool list with general-purpose's broader set. Each project-local reviewer agent is already exposed as its own subagent_type and declares Write/Edit in its frontmatter, so direct dispatch loads both the right persona and the right tools. Update all four planning runtime-claude adapters (features-direct, features-from-rfc, epics-direct, epics-from-rfc) to require named-subagent_type dispatch and explicitly forbid general-purpose. Also rewrite the misleading Explore warning in features-direct so it no longer implies Explore was a candidate launch type. Remove a Claude-specific subagent_type string that had leaked into the runtime-neutral epics-direct SKILL.md and replace it with the same runtime-adapter delegation the other planning skills use.
Keep ~/.local/bin ahead of Homebrew after shellenv runs so uv's default Python symlinks remain stable. Document the PATH precedence rule in the shell startup flow.
Use normal git instead for committing only.
MrPointer
force-pushed
the
feature/switch-to-uv
branch
from
072fd76 to
2160127
Compare
Homebrew list failures should not block installer setup when the only question is whether a single package exists. Use package-specific lookup so CI and users avoid enumerating unrelated Homebrew state before installing chezmoi.
Fedora containers can run Expect under a non-UTF-8 locale, where emoji logging causes Tcl to fail before the installer starts. Keep the automation output ASCII-only so locale differences do not break the interactive GPG CI path.
Homebrew documents --prefix --installed as the installed-formula probe. It returns a failing status when the formula is absent, and may still emit diagnostic output. Use that command and treat exit code 1 as not installed so macOS CI can fall through to installing chezmoi instead of aborting during detection.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Summary
This branch moves Python tooling away from pyenv shell integration and toward uv as an optional installer-managed tool.
Shell startup no longer initializes pyenv or inserts pyenv shims, while existing Python completions remain guarded and uv/uvx completions come through Homebrew when available.
It also strengthens the planning/execution agent workflow so multi-agent plans carry explicit model, worker, review, and TDD isolation mechanics.
The CI follow-up also hardens Homebrew package detection and the Fedora Expect harness after environment-sensitive failures surfaced in PR validation.
🔑 Key Decisions
uv Optional Tooling
Added
uvas a normal optional installer tool with a Homebrew package mapping only. This keeps the migration inside the existing optional-tools and package-resolution flow, avoids a dedicated Python provisioning subsystem, and preserves the current behavior where unsupported tools are filtered out for package managers without a mapping.Shell Runtime Cleanup
Removed pyenv-specific PATH setup, lazy initialization, and the local
pyenv-shellworkaround. Shell startup remains valid without uv, preserves guardedpip,poetry, andpipxcompletions, and keeps user-local paths ahead of Homebrew afterbrew shellenvso uv-managed Python shims can take precedence when present.RFC-Backed Migration Context
Added an accepted RFC, reviewer records, and feature anchor documenting the settled uv migration scope, non-goals, and trade-offs. The documentation makes clear that this change does not install Python versions, migrate existing pyenv/pipx/Poetry state, or add non-Homebrew uv fallback behavior.
Planning And Execution Mechanics
Expanded the planning and executing skills to require explicit execution bindings, worker dispatch mechanics, cross-sub-plan data-flow checks, and structural TDD isolation gates. This prevents multi-sub-plan plans from silently falling back to coordinator execution or relying on natural-language model selection.
OpenCode Worker Coverage
Added project-local OpenCode worker agents for Go, Zsh, docs, and test authoring across model tiers, plus an OpenCode plan-executability reviewer. These bindings make the planning workflow executable in OpenCode instead of only documenting intended model tiers.
CI Hardening Follow-Up
macOS CI exposed that Homebrew package detection should use Homebrew's documented installed-formula probe rather than package listing output. Package existence checks now run
brew --prefix --installed <package>and treat exit code 1 as not installed, allowing the installer to continue into package installation. Fedora CI exposed that Expect/Tcl can start under a non-UTF-8 locale, so the interactive GPG test script now uses ASCII-only log output.🔄 Before & After
brew shellenvbrew --prefix --installedand treats exit code 1 as not installed