harness-tools/skills/develop/package-source/SKILL.md

name, description, compatibility, metadata

name	description	compatibility	metadata
package-source	Install, update, or fetch third-party package source with the project's package manager and opensrc. Use whenever adding, installing, updating, upgrading, or restoring dependencies with npm, pnpm, yarn, bun, pip, uv, poetry, or cargo, and whenever another skill needs package source that is missing from the OpenSrc cache. Always synchronize relevant source into /srv/data/opensrc after dependency changes.	Requires opensrc CLI and a writable cache at /srv/data/opensrc, exposed through ~/.opensrc.	argument-hint <install-or-fetch-only> <packages>

Package Source

Keep locally searchable upstream source synchronized with the packages used by a project. This skill has two modes:

• Dependency-change mode: install or update packages as requested, then cache the exact resolved source with OpenSrc.
• Fetch-only mode: download source for research without changing the project's manifests, lockfiles, installed packages, or environments.

OpenSrc data belongs in /srv/data/opensrc/, normally exposed as ~/.opensrc -> /srv/data/opensrc.

Choose the mode

Use dependency-change mode when the user or another workflow is adding, installing, updating, upgrading, or restoring project dependencies.

Use fetch-only mode when code-research or another skill asks for missing upstream source. Fetch-only mode must not invoke a package manager install command or modify the project.

If the caller does not make the mode clear, infer it from intent: “install/add/update/upgrade” changes dependencies; “inspect/research/fetch source” does not.

Shared preflight

1. Identify the project root.
2. Read project instructions such as AGENTS.md or CLAUDE.md.
3. Detect the project's existing package manager from manifests, lockfiles, and repository conventions. Do not introduce a different package manager.
4. Verify opensrc is available.
5. Verify ~/.opensrc resolves to /srv/data/opensrc. Stop before creating a second cache if it does not.
6. Identify the registry package names and exact versions relevant to the operation.

Never print tokens or credential values. Cached upstream checkouts are read-only research material; never implement project changes inside /srv/data/opensrc.

Dependency-change mode

1. Make the requested dependency change

Use the project's established package manager and preserve its normal manifest and lockfile behavior. Examples include:

• npm: npm install <package>
• pnpm: pnpm add <package>
• Yarn: yarn add <package>
• Bun: bun add <package>
• uv: uv add <package>
• Poetry: poetry add <package>
• pip/requirements: follow the repository's existing requirements workflow
• Cargo: cargo add <crate>

These are examples, not permission to guess. Respect workspace flags, development/runtime dependency scope, exact-version policies, and commands already used by the repository.

After the package manager succeeds, determine what package names and versions actually changed from the manifest/lockfile diff. Do not assume the requested range is the resolved version.

2. Synchronize source

For npm packages, let OpenSrc resolve versions from the project's lockfile:

opensrc fetch --cwd "$PROJECT_ROOT" <package> [<package>...]

For Python and Rust, OpenSrc does not resolve versions from project lockfiles automatically. Read the resolved versions and fetch explicit specs:

opensrc fetch pypi:<package>@<resolved-version>
opensrc fetch crates:<crate>@<resolved-version>

Batch packages from the same operation into one command when practical. Fetch every direct third-party package added or updated by the operation. Fetch a transitive dependency too when the task depends on its implementation.

For a restore command that installs an existing lockfile without changing it, prewarm source for the direct dependencies relevant to the current task. If the user explicitly asks to cache all direct dependencies, enumerate the manifest and fetch all resolvable direct packages in batches.

3. Verify

Resolve each synchronized checkout with opensrc path, then canonicalize it with readlink -f and confirm the resolved path is under /srv/data/opensrc. OpenSrc may print a logical ~/.opensrc/... path because the default cache entrypoint is the compatibility symlink:

readlink -f "$(opensrc path --cwd "$PROJECT_ROOT" <npm-package>)"
readlink -f "$(opensrc path pypi:<package>@<resolved-version>)"
readlink -f "$(opensrc path crates:<crate>@<resolved-version>)"

Then run the project's normal dependency-change verification, such as its lockfile check, typecheck, build, or focused tests.

Report separately:

• dependency changes made to the project
• exact package source cached by OpenSrc
• verification performed
• packages OpenSrc could not resolve

Fetch-only mode

Fetch-only mode exists so research can lazy-load missing source safely.

1. Determine the package version used by the project from its manifest and lockfile.
2. Check opensrc list --json for that package/version.
3. If the exact source is already cached, return its path without fetching again.
4. If it is missing, fetch it with the correct project context or explicit version.
5. Return the path printed by opensrc path.

For npm:

opensrc fetch --cwd "$PROJECT_ROOT" <package>
opensrc path --cwd "$PROJECT_ROOT" <package>

For Python and Rust:

opensrc fetch pypi:<package>@<resolved-version>
opensrc path pypi:<package>@<resolved-version>

opensrc fetch crates:<crate>@<resolved-version>
opensrc path crates:<crate>@<resolved-version>

For an upstream repository that is not a registry dependency:

opensrc fetch owner/repository
opensrc path owner/repository

Fetch-only mode must leave git status --short unchanged. If it does not, stop and report the unexpected project mutation.

Cache policy

The cache is shared across projects:

• Do not run opensrc clean as part of normal work.
• Do not remove cached source when a dependency is removed from one project; another project may still need it.
• Do not edit cached checkouts.
• Do not manually copy repositories into the cache; let OpenSrc maintain sources.json and its directory layout.
• Multiple cached versions are expected and should be preserved.

Failure handling

• If OpenSrc cannot map a registry package to source, report its exact error and continue the dependency operation only if the package-manager portion itself succeeded.
• If an expected version tag is unavailable, do not silently fetch the latest version. Report the mismatch to the caller.
• If private source requires credentials, ask the user to configure the relevant credential outside the conversation; never request or expose a token.
• If package installation fails, do not fetch a guessed version. Fix or report the install failure first.
• If cache configuration has drifted from /srv/data/opensrc, stop and repair or confirm the storage setup before downloading.