Develop a Cross-Platform Toolchain Manager and Vet Tools for Its Registry

## Map the Toolchain Manager's Modules and Repo Rules Before Editing Treat the repository guide as the operating contract for coding agents. Follow repository-native commands, module boundaries, contribution rules, and compatibility requirements before proposing changes. Orient work around these capabilities: - command-line parsing and subcommand dispatch; - layered configuration and environment-variable management; - tool-version resolution and installation; - task definition and execution; - pluggable backends and built-in tool implementations; - documentation, completion, and metadata generation. Locate the entry point, CLI modules, configuration modules, backend interfaces, toolset resolver, task engine, plugin system, and shared helpers before editing. Distinguish public packages from internal workspace support packages. Do not bypass an established abstraction merely because a direct implementation looks shorter. ## Add a Tool to the Registry Only With Popularity Evidence Assume that a curated shorthand registry accepts only tools that are already widely used. Working code, tests, or personal usefulness do not establish eligibility. Before touching registry mappings: 1. Ask whether the tool is widely used outside the submitter's own projects. 2. Stop if it is personal, internal, a fork, niche, or supported by only a small audience. 3. Collect current popularity evidence for every submission; never guess. 4. Check repository stars and forks, recent commits and releases, package-download counts, independent documentation, ecosystem lists, and downstream usage. 5. Apply a high admission bar: popularity measured in thousands rather than hundreds, active maintenance, third-party adoption, and ecosystem recognition. 6. Put the evidence in a concise `Popularity` section in the pull-request description. Warn clearly when the evidence is borderline or weak and ask whether the user still wants to proceed. Do not imply that rejection will include an explanation, appeal, checklist, or second chance. Never submit speculatively merely to discover whether maintainers will accept the tool. ## Choose an Install Backend, Preferring Verified Release Files Prefer backends that consume verified release artifacts without requiring a separately installed runtime. Use this decision order: 1. Prefer a curated artifact registry when it provides verification and per-version installation logic. 2. Otherwise use a direct release backend for the forge that publishes the artifacts. 3. Use an archive-distribution backend only when release backends cannot support the tool and popularity is still well established. 4. Treat language-package backends as exceptional because they depend on runtime availability, runtime version, and path ordering. 5. Reject deprecated backends and new plugin formats that violate the project's supply-chain policy. Do not choose a fragile backend merely because its package name is easy to find. If maintainers have not explicitly approved an exceptional backend for that tool, do not use it in a registry submission. Explain the non-registry alternative: users can install through an explicit backend coordinate or create a supported plugin. Keep the distinction clear: registry shorthand improves convenience; it is not required to enable installation. ## Run Builds, Tests, and Lint Through the Repo's Task Runner Use the repository task runner rather than invoking underlying tools ad hoc. Identify and use the documented tasks for: - full builds and direct execution of the debug binary; - complete, unit, and end-to-end test suites; - targeted end-to-end test files through the test task; - snapshot review and updates; - linting, automatic lint fixes, and formatting; - continuous-integration parity checks; - documentation, usage text, completions, and schema generation; - local development installation and build-artifact cleanup; - package-specific tests and linting from the correct workspace directory. Use the project's dedicated debug and trace environment variables instead of assuming a common logging variable. List available tasks when command names are uncertain. Never execute end-to-end test scripts directly when the harness owns setup, assertions, and cleanup. Do not add manual cleanup to tests when the harness guarantees isolation. Run the smallest relevant task first, then widen only when shared contracts or generated artifacts are affected. ## Add Backends and Settings Without Hand-Editing Generated Files Implement tool sources through the unified backend interface. Each backend should own version listing, request resolution, installation, and tool metadata for its ecosystem. Keep built-in tools behind the core plugin boundary and external plugins behind supported compatibility layers. Preserve hierarchical configuration loading from system to global to local scope, including environment-specific overrides. When settings definitions generate code or documentation, update the source definition and run the canonical generator. Do not hand-edit generated output as the primary change. Keep task definitions declarative, including dependencies, environment variables, and supported execution modes. Respect configuration-file compatibility formats where the project promises interoperability. Keep custom build scripts, workspace members, release profiles, and cross-compilation configuration aligned with their documented roles. When adding a backend, start from the established backend module pattern. When adding configuration, follow the typed parsing and generation path. When extending plugins, use the correct built-in or external boundary rather than inventing a parallel mechanism. ## Write type(scope) Commit Messages and Run Lint Fixes First All commits and pull-request titles must use the repository's conventional format: `type(scope): imperative description`. Use the type that reflects user-visible behavior and repository ownership: - `feat` for a new capability; - `fix` for a user-visible defect; - `refactor`, `style`, or `perf` for their corresponding code changes; - `test` for test-only work; - `docs` for documentation; - `chore` for maintenance, releases, dependencies, or infrastructure; - `security` for security work; - the dedicated registry type for every registry mapping change. Use command names for command-specific scopes and subsystem names for shared components. Use the task subsystem scope for task behavior even if implementation files use another historical name. Keep the description lowercase after the colon, imperative, concise, and specific. Install the repository's pre-commit integration once through its documented task environment. Before committing, run the automatic lint-fix task and stage any resulting intended changes. Run targeted end-to-end tests through the task runner. Do not stage unrelated formatting or generated changes. ## Retire Features in Steps: Docs, Then Warnings, Then Removal Use a staged deprecation policy: 1. Mark the feature or backend as deprecated in documentation immediately. 2. Begin runtime warnings after the documented warning interval. 3. Schedule removal after the documented removal interval. 4. Encode warning and removal dates with the project's version-date format. 5. Use the established deprecation macro so development assertions reveal overdue removals. A common schedule is documentation now, warnings after six months, and removal twelve months after warnings begin. If the replacement has already been available for a long time, warnings may start immediately. Do not silently remove compatibility without the documented warning phase. Do not leave an expired deprecation indefinitely; treat the removal assertion as required maintenance. ## Let Each Backend Resolve and Sort Tool Versions Never assume that tool versions follow semantic versioning or any other universal ordering. Expect date versions, prereleases, branches, tags, channels, named long-term-support releases, and tool-specific aliases. At a new call site: - do not use a generic semantic-version comparator to select the newest version, resolve an alias, or sort versions; - delegate request resolution to backend methods that understand that tool's version language; - use backend or toolset APIs to list installed versions in a meaningful order; - treat lockfile version strings as opaque and compare them only for equality; - resolve aliases, channels, and prefixes before writing a concrete lockfile value; - do not cite legacy comparator use as justification for expanding flawed behavior. If new code appears to need the newest installed version, stop and confirm whether the decision belongs in the backend. Incorrect fallback ordering is worse than returning no match because it can silently install or execute the wrong tool. ## Run Focused Tests per Platform and Review the Diff Before Finishing Organize unit tests near source and end-to-end tests by feature area. Use shared assertion helpers, snapshots for stable command output, backend-specific installation checks, and explicit slow-test naming. Keep platform-specific implementations in their designated modules and platform suites. Do not assume Unix executable-bit behavior on Windows. For a change, verify the narrowest relevant path first: 1. run formatting and static checks; 2. run focused unit or end-to-end tests through the harness; 3. review snapshot changes rather than accepting them blindly; 4. regenerate derived documentation or schemas when their source changes; 5. expand to broader integration checks when shared backend, configuration, task, or cross-platform contracts changed. When posting to an external pull request or discussion, disclose that the comment was generated by an AI coding assistant. Use documentation URLs that mirror the documentation directory hierarchy. Do not invent shortened paths that omit required sections. Before completion, review the diff for abstraction leaks, unsupported version ordering, skipped generators, unrelated changes, and unverified external claims.