Prepare Repo Skill Env

Prepare Repo Skill Env

Purpose

Use this skill before create-repo-skill when a local repository needs a verified Python environment for live API and runtime inspection. The caller should provide or let this skill infer:

• The repository path.
• A new private environment prefix, or an existing environment that may be inspected.
• The confirmed extraction scope, backend-classified native candidate map, and backend verification plan from create-repo-skill, when applicable.

Create the environment, install only what the confirmed scope requires, and prove that the package works from the environment's Python. "Minimum" means the smallest environment set that covers every required backend in the selected scope, not CPU-only by default. Usually one GPU-capable environment can also cover CPU checks; create additional prefixes only for conflicting backend variants or an independently selected CPU fallback claim. Run the relevant Conda, micromamba, uv, Python, and pip commands directly in the terminal. Keep each material step visible and separately diagnosable; do not hide environment creation, dependency selection, installation, or verification behind a bundled setup/bootstrap script.

Prefer Conda when it is already available because it handles Python versions and compiled dependencies well. Micromamba is an equivalent prefix-based path when it is already installed. If neither is available, use an existing compatible Python with venv, or an installed uv when it can create the requested environment. Do not mutate Conda base, the Python running DisCo, or a user-owned environment without authorization.

Do not run the repo-native candidate tests/examples during environment preparation. Install their required variants and run the smallest backend smoke checks needed to prove that final native verification is feasible; the native cases themselves run after the generated skill is integrated.

The default private prefix is $DISCO_CODING_AGENT_DIR/envs/<skill-id>-inspection when that variable is set, otherwise ~/.disco/agent/envs/<skill-id>-inspection. Resolve it to a concrete absolute path before executing commands.

This skill produces private setup evidence. Environment paths, checkout paths, commands, and logs may be handed to create-repo-skill, but must not be copied into the generated public repo skill.

Required Outputs

Deliver an ok, partial, or failed environment handoff. In every case, write a private repo_env_report.json in the caller's artifact directory, or another explicit private path when invoked directly.

For success, record:

• Repository path, environment manager, prefix, and environment Python.
• Confirmed extraction scope and the dependency groups selected or skipped.
• Backend verification plan, required/optional/alternative candidates, CPU substitution decisions, hardware compatibility verdicts, and the minimum environment set selected.
• Exact environment creation, install, and verification commands with exit status and concise output/error evidence.
• Installed distribution names and successfully imported module names.
• Hardware/backend verdict when relevant.
• Any unsafe, credentialed, destructive, or long-running checks that were deliberately skipped.

Use partial only when a required backend cannot be prepared and the user explicitly authorizes skill drafting with that exact limitation. A partial handoff is not ready for full backend verification or auto-import. Without that authorization, report failed.

For failure, record the failed phase, exact command, exit status, key stderr, relevant platform/backend facts, attempted remedies, and the next viable action. State explicitly that the environment is not ready for create-repo-skill.

Reference Map

Read the relevant references before acting:

• references/install-planning.md: packaging discovery, backend verification plan interpretation, environment-manager selection, direct command templates, extraction-scope dependency choices, and install order.
• references/hardware-and-backends.md: accelerator probing, backend package choices, and compatibility failures.
• references/verification-and-failure-report.md: direct verification commands, the report contract, and handoff templates.

Workflow

1. Resolve Inputs and Mutation Boundaries

Resolve these before installation:

• repo_path: canonical local checkout path.
• environment_prefix: canonical target prefix/path.
• Confirmed included/excluded directories, selected workflows, and user requirements from create-repo-skill when available.
• Backend-classified native candidates owned by included workflows. Require backend requirement, criticality, CPU substitution, dependency variant, hardware prerequisites, preparation smoke, and final native expectation.
• The caller's backend verification plan and proposed minimum environment set. If either is missing during a create-repo-skill call, derive it from repo evidence before installation rather than defaulting silently to CPU.
• Python version supported by repo metadata and required backend wheels.
• Distribution name and import module names.
• Required extras, requirements files, build tools, and backend packages.
• Backend expectation: auto, cpu, cuda, rocm, mps, or another documented backend.
• Whether the prefix is new, private and reusable, or user-owned.
• Whether potentially breaking mutation of an existing environment is already authorized.

When called automatically by create-repo-skill, use its resolved private default prefix without asking again. During a direct invocation, ask for a prefix or propose the private default before writing there. Never infer a path outside the stated default-prefix policy.

If the prefix exists, inspect it read-only first. Imports, version queries, pip check, metadata queries, and safe CLI help are read-only. Installing, upgrading, downgrading, uninstalling, or repairing packages is mutation. Ask before mutating a user-provided environment unless the user already authorized that operation; otherwise create a new private prefix when allowed.

2. Inspect the Repository Before Choosing Commands

Read references/install-planning.md. Inspect pyproject.toml, setup.cfg, setup.py, requirements files, lockfiles, environment.yml, CI install steps, source roots, entry points, and documented install variants.

Build a concise install and backend map before running anything:

textCopy code
Selected Python: 3.11 (repo supports >=3.10; required wheels available)
Included scope: src/package, docs/gpu-inference.md, examples/infer.py
Excluded scope: training/, benchmarks/
Required candidate: examples/infer.py | cuda | required | CPU substitute: none
Optional candidate: benchmarks/throughput.py | cuda | optional | excluded
Host verdict: compatible NVIDIA GPU/driver/wheel
Environment set: one CUDA-capable prefix covering CUDA and CPU checks
Install: base package + [inference,cuda] + compatible torch CUDA wheel
Skip: [train], [all], requirements-dev.txt, benchmark dependencies
Preparation smoke: torch CUDA allocation + package backend import
Final native case: examples/infer.py with tiny fixture (run after integration)

Do not assume the repository name is the distribution or import name. Do not install all extras or every requirements file as a substitute for analysis.

3. Probe Available Managers and Hardware

Run discovery commands separately so their outcomes remain visible:

bashCopy code
command -v conda
command -v micromamba
command -v uv
command -v python3.11
command -v python3
command -v python

Use platform-equivalent commands on Windows. Query versions for tools that exist. Do not treat a missing command as a fatal error until all suitable paths have been evaluated.

Read references/hardware-and-backends.md and probe only the hardware relevant to the requested or repo-required backend. A visible GPU does not by itself require a GPU install for package inspection.

Apply the backend plan after probing:

• When an included capability has a required backend and CPU substitute: none, prepare and verify that backend whenever compatible hardware and packages are available. A CPU-only prefix is not ready for that scope.
• When CPU substitute is full and the selected CPU candidate verifies the same behavior, use the CPU path and record the evidence.
• When the backend is optional, omit it from the minimum environment when it is unavailable or outside the selected scope, but preserve an explicit unverified-capability note.
• When required hardware or a compatible dependency variant is unavailable, do not install an arbitrary GPU wheel or call the CPU environment ok. Report failed, ask to narrow scope, or produce partial only after the user accepts drafting with the required-backend limitation.
• When required backend variants conflict, create separate concrete prefixes and verify each one. Do not mutate one prefix repeatedly between incompatible CPU/CUDA/ROCm/vendor states.

If no suitable Conda/micromamba, uv, or Python runtime exists, do not invoke a bundled downloader. Explain the host change required and ask before installing a runtime or environment manager unless the user already authorized that exact kind of host-level installation. Once authorized, use the platform's normal package manager or the selected tool's documented installer with explicit, reviewable terminal commands, then resume this workflow. Do not silently curl and execute an installer.

4. Create the Required Environment Set with Direct Commands

Substitute concrete absolute paths and the selected Python version in every command. Do not execute examples with placeholder paths.

Create the primary prefix for the strongest required selected backend. A GPU-capable prefix normally also runs CPU checks. When the backend plan requires incompatible variants, derive distinct suffixes such as -cuda, -rocm, or -cpu from the caller's private prefix and record every prefix in the report.

For Conda:

bashCopy code
conda create --yes --prefix "/absolute/path/to/inspection-env" "python=3.11" pip
conda run --prefix "/absolute/path/to/inspection-env" python -c "import sys; print(sys.executable); print(sys.version)"

For an already installed micromamba:

bashCopy code
micromamba create --yes --prefix "/absolute/path/to/inspection-env" "python=3.11" pip
micromamba run --prefix "/absolute/path/to/inspection-env" python -c "import sys; print(sys.executable); print(sys.version)"

For venv on Unix-like systems:

bashCopy code
python3.11 -m venv "/absolute/path/to/inspection-env"
"/absolute/path/to/inspection-env/bin/python" -c "import sys; print(sys.executable); print(sys.version)"

On Windows, use the environment's Scripts/python.exe. If installed uv is the best available path, make its runtime acquisition explicit:

bashCopy code
uv venv --seed --python 3.11 "/absolute/path/to/inspection-env"
"/absolute/path/to/inspection-env/bin/python" -c "import sys; print(sys.executable); print(sys.version)"

If uv would download a Python runtime, treat that as runtime installation and apply the authorization rule from step 3.

Do not rely on shell activation. For subsequent Conda/micromamba commands use run --prefix; for venv/uv use the environment Python's absolute path. This prevents commands from accidentally using DisCo's or the user's current Python.

5. Install the Minimum Required Package Set

Execute one meaningful install phase at a time, with a finite terminal-tool timeout and observable output. A typical new Conda environment uses commands like:

bashCopy code
conda run --prefix "/absolute/path/to/inspection-env" python -m pip install -e "/absolute/path/to/repo"

For venv/uv:

bashCopy code
"/absolute/path/to/inspection-env/bin/python" -m pip install -e "/absolute/path/to/repo"

Add only evidence-backed requirements or extras:

bashCopy code
conda run --prefix "/absolute/path/to/inspection-env" python -m pip install -r "/absolute/path/to/repo/requirements-inference.txt"
conda run --prefix "/absolute/path/to/inspection-env" python -m pip install -e "/absolute/path/to/repo[inference]"

Follow repo documentation when backend foundations such as torch, JAX, TensorFlow, or a compiler/toolkit must be installed first. Do not reflexively upgrade pip/setuptools/wheel or broad dependency sets, especially in an existing environment; do so only when repo/build evidence requires it.

For every required backend candidate, install its evidence-backed dependency variant into the prefix assigned by the backend plan. Do not install a CPU-only torch/JAX/TensorFlow build into a required CUDA/ROCm environment and then count package importability as backend coverage. Conversely, do not install GPU stacks for optional or excluded candidates merely because hardware is visible.

Do not combine creation, multiple installs, and verification into one large shell command. After each phase, record the exact command, exit status, elapsed time, and relevant output in the private report. On failure, diagnose the specific phase and adjust the next visible command rather than rerunning an opaque all-in-one installer.

If metadata resolution or downloads stall, interrupt the command, distinguish network delay from compilation, and use the network guidance in references/install-planning.md. Proxy or VPN details supplied by the user are local execution context only; never bake them into the skill or generated package content.

6. Verify from the Environment Python

Read references/verification-and-failure-report.md. At minimum, run direct commands for:

• Environment Python identity and version.
• python -m pip check.
• Distribution metadata from the environment.
• Imports using the environment Python, preferably from outside the checkout and with -I when compatible, so the current directory or user site cannot make a broken install look healthy.
• Relevant CLI/API smoke checks.
• A preparation smoke check for every required backend in the backend plan, using the prefix assigned to that backend. For CUDA/ROCm/MPS or a vendor accelerator, prove framework/backend availability and a minimal device operation when safe.

Examples for Conda:

bashCopy code
conda run --prefix "/absolute/path/to/inspection-env" python -m pip check
conda run --prefix "/absolute/path/to/inspection-env" python -I -c "from importlib.metadata import version; print(version('distribution-name'))"
conda run --prefix "/absolute/path/to/inspection-env" python -I -c "import package_name; print(package_name.__file__)"

Equivalent venv commands must use the environment Python's absolute path. A successful environment creation or pip install is not verification. Fix and rerun every applicable failed gate before an ok handoff. Do not run the repo-native cases yet; record which final cases this prepared environment must support after skill integration.

7. Write the Report and Handoff

Write repo_env_report.json from the actual command results. Do not invent missing output or mark skipped gates as passed. Include at least:

jsonCopy code
{
  "schemaVersion": 2,
  "status": "ok",
  "readiness": {
    "skillDrafting": true,
    "fullBackendVerification": true,
    "backendGateEligibleForAutoImport": true
  },
  "repositoryPath": "/absolute/path/to/repo",
  "environment": {
    "manager": "conda",
    "prefix": "/absolute/path/to/inspection-env",
    "pythonExecutable": "/absolute/path/to/inspection-env/bin/python",
    "backends": ["cpu", "cuda"]
  },
  "workflowEnvironment": {
    "executable": "/absolute/path/to/inspection-env/bin/python",
    "cwd": "/absolute/path/to/repo",
    "package": "distribution-name",
    "version": "1.2.3"
  },
  "additionalEnvironments": [],
  "backendPlan": {
    "required": [
      {
        "backend": "cuda",
        "capability": "GPU inference",
        "cpuSubstitute": "none",
        "hostVerdict": "compatible",
        "dependencyVariant": "repo cuda extra plus compatible framework wheel",
        "preparationSmoke": "passed",
        "finalNativeCandidates": ["examples/infer.py"]
      }
    ],
    "optional": [],
    "alternative": []
  },
  "installPlan": {
    "python": "3.11",
    "includedScope": [],
    "excludedScope": [],
    "installedGroups": [],
    "skippedGroups": []
  },
  "commands": [],
  "verification": {},
  "warnings": [],
  "failures": []
}

environment.pythonExecutable remains private report evidence. It is not the object to pass directly to workflow agent(). The caller must use the canonical workflowEnvironment object with executable, optional cwd, distribution package, and exact version.

Use status: "ok" only when every required preparation/backend gate passes. Use status: "partial" only after explicit user acceptance, with skillDrafting: true, fullBackendVerification: false, and backendGateEligibleForAutoImport: false. Use status: "failed" when a required gate remains unresolved without that acceptance. The commands entries should identify phase, command, exit status, and concise stdout/stderr evidence; do not put credentials or secret-bearing environment variables in the report.

For every handoff, provide:

textCopy code
Environment status: <ok|partial|failed>
Ready for skill drafting: <yes|no>
Ready for full backend verification: <yes|no>
Backend gate eligible for auto-import: <yes|no>
Repository path: <repo_path>
Environment manager: <conda|micromamba|venv|uv>
Environment prefix: <environment_prefix>
Additional environment(s): <prefix/backend or none>
Temporary inspection Python: <python_executable>
Workflow environment: {"executable":"<python_executable>","cwd":"<repo_path>","package":"<distribution_name>","version":"<verified_version>"}
Installed package name(s): <distribution names>
Verified import(s): <modules>
Verification report: <repo_env_report.json>
Required backend verdict(s): <backend: preparation smoke passed/blocked>
Final native backend case(s): <candidate ids to run after skill integration>
Accepted partial limitation: <exact user-accepted block or none>
Additional notes: <extras installed, skipped unsafe checks, limitations>

create-repo-skill may continue normally from ok. It may continue drafting from partial only after preserving the accepted backend block and disabling auto-import. It must not continue from failed without repair or an explicitly narrowed extraction scope.

Non-Negotiables

• Execute environment creation, package installation, and verification as explicit terminal commands; do not route them through a bundled wrapper.
• Never install into or mutate Conda base.
• Never use DisCo's current Python as the target environment unless the user explicitly requests and authorizes that mutation.
• Never delete or recreate an existing prefix without explicit authorization.
• Never mutate a user-provided environment in a potentially breaking way without authorization; use a new private prefix when permitted.
• Never install broad extras, dev requirements, or backend packages unrelated to the confirmed extraction scope.
• Never call a CPU-only environment ok for a required CUDA/ROCm/MPS/vendor capability whose CPU substitute is partial or none.
• Never silently downgrade a required backend candidate to optional because hardware, wheels, drivers, or toolkits are unavailable.
• Never mark a partial environment eligible for auto-import. Preserve the required-backend block for final native verification and informed user acceptance.
• Never rely only on shell activation or an unqualified python/pip after environment creation.
• Never treat successful creation or installation as proof of usability.
• Never hide a failed or skipped verification gate in an ok report.
• Never wait indefinitely on a stalled resolver, download, or build. Use finite timeouts, retain useful failure evidence, and diagnose before retrying.
• Never copy private environment paths, proxy details, command logs, or setup reports into the generated public repo skill.