alvinunreal/clonedeps

Clonedeps Skill

You help users make a small set of important dependency source repositories locally readable to OpenCode.

This is a workflow skill, not a command wrapper. Do not use a helper script for dependency detection, ref validation, cloning, status, or cleanup. The orchestrator and @librarian do the repo-specific thinking; the orchestrator performs the approved filesystem/git operations directly.

Workflow

Step 1: Check Existing State

First check whether .slim/clonedeps.json exists.

If it exists:

1. Read it before asking librarian for a new plan.
2. Check whether each listed path exists under .slim/clonedeps/repos/.
3. Reuse existing cloned repos when they already satisfy the user's task.
4. Only ask librarian for new recommendations if the existing manifest is missing, stale, or insufficient for the current task.

Do not rescan/re-plan from scratch when the manifest already has useful entries.

Step 2: Ask Librarian for the Clone Plan

Delegate dependency discovery and source resolution to @librarian.

Use this prompt:

Understand this project first, then recommend remote source repos that would
help a developer work on it.

Read enough of the current repo to understand:
- what the project does
- its main architecture
- the important integration points
- what external systems or libraries it depends on in practice

Think like a developer trying to debug or extend this project.

Which remote repositories, if cloned locally, would actually help understand the
codebase or solve likely implementation/debugging tasks?

Do not make a dependency dump. Most dependencies are not worth cloning.
Recommend a repo only when its source code would be more useful than docs or the
current repo alone.

For each recommendation, include:
- repo name
- repo URL
- suggested ref/tag/commit if known
- why cloning this source would help
- when it would be useful
- caveats

Also include:
- current-repo files/folders to inspect first
- repos/dependencies you considered but would not clone

Keep it small. Prefer 0–3 strong recommendations over 5 weak ones. If nothing
clearly needs cloning, say so.

Librarian should return a small plan with:

• dependency name;
• current version/range if discoverable;
• official source repository URL;
• tag/commit/ref to check out;
• package subdirectory if the source is a monorepo;
• reason local source helps;
• caveats such as huge repo, missing tag, or uncertain version mapping.

Prefer at most 3-5 core dependencies. Include user-mentioned dependencies and central frameworks, SDKs, ORMs, runtime/plugin APIs, or build/runtime tools. Do not clone tiny utilities, transitive dependencies, or dev-only tools unless they are directly relevant to the active task.

Step 3: Verify and Confirm the Plan

The orchestrator owns final approval. Before cloning:

1. Verify refs manually where possible with git ls-remote.
2. Prefer pinned tags or commit SHAs. If no exact tag exists, ask librarian to find the correct module-specific tag/commit or explain the fallback.
3. Only use HTTPS GitHub/GitLab-style repository URLs by default. Reject file://, SSH URLs, local paths, URLs with embedded credentials, and private or auth-required repositories unless the user explicitly approves that case.
4. Present the plan to the user with dependency, repo URL, ref, reason, and caveats.
5. Ask for confirmation before network cloning unless the user explicitly asked to clone immediately.

Step 4: Clone Sources Manually

Create one folder per source repository under:

.slim/clonedeps/repos/<safe-repo-name>/

Derive the safe name from the repository owner/name, not from the package name. For example, https://github.com/opencode-ai/opencode.git becomes opencode-ai__opencode. Replace / with __, strip common .git suffixes, and replace other unsafe path characters with _.

If multiple packages come from the same monorepo, clone the repository once and point each manifest entry at the same repo path with different packagePath values as needed. Do not create ecosystem folders, per-package clone folders, or per-version folders. If two different source repositories normalize to the same safe name, disambiguate manually and record the chosen path in .slim/clonedeps.json.

Clone/fetch with normal git commands. For an existing clone, first verify that git remote get-url origin matches the approved repo URL. If it does not match, stop and ask whether to clean/reclone.

Safe manual git pattern:

1. git ls-remote <repoUrl> <ref> to verify the ref where practical.
2. Clone without submodules/recursive behavior.
3. Prefer shallow fetch/clone where practical.
4. Clone into a temporary directory under .slim/clonedeps/repos/, then move it into the final safe-name path after checkout succeeds.
5. Remove failed temporary clones.

Do not run dependency install/build/test scripts from cloned repositories.

Step 5: Write Local State

Write .slim/clonedeps.json so future agents know what exists:

{
  "version": "1.0.0",
  "updatedAt": "2026-05-12T00:00:00.000Z",
  "dependencies": [
    {
      "name": "@opencode-ai/plugin",
      "resolvedVersion": "1.3.17",
      "repoUrl": "https://github.com/opencode-ai/opencode.git",
      "ref": "v1.3.17",
      "path": ".slim/clonedeps/repos/opencode-ai__opencode",
      "packagePath": "packages/plugin",
      "reason": "Plugin API source used by the project"
    },
    {
      "name": "@opencode-ai/sdk",
      "resolvedVersion": "1.3.17",
      "repoUrl": "https://github.com/opencode-ai/opencode.git",
      "ref": "v1.3.17",
      "path": ".slim/clonedeps/repos/opencode-ai__opencode",
      "packagePath": "packages/sdk/js",
      "reason": "Core SDK source used to inspect runtime behavior"
    }
  ]
}

If a clone fails after earlier clones succeeded, still write state for the successful clones so future inspection is not misleading.

Do not add .slim/clonedeps.json to .gitignore. It is small, reviewable project metadata that can be committed. Only the cloned repository contents under .slim/clonedeps/repos/ should be ignored.

Step 6: Update Ignore Files

Update .gitignore with an idempotent marker block:

# BEGIN oh-my-opencode-slim clonedeps
.slim/clonedeps/repos/
# END oh-my-opencode-slim clonedeps

Update .ignore so OpenCode can read the cloned source while git still ignores it:

# BEGIN oh-my-opencode-slim clonedeps
!.slim/
!.slim/clonedeps.json
!.slim/clonedeps/
!.slim/clonedeps/repos/
!.slim/clonedeps/repos/**
.slim/clonedeps/repos/**/.git/
.slim/clonedeps/repos/**/.git/**
# END oh-my-opencode-slim clonedeps

Only edit content inside these marker blocks.

Step 7: Register Dependency Source in AGENTS.md

After successful cloning, update the repository root AGENTS.md so future agents know why the dependency source exists and where to look.

If AGENTS.md already has a ## Cloned Dependency Source section, update that section. Otherwise append this section:

Use this format and list the actual repos directly. Keep each item to one short sentence so future agents do not need an extra read just to know what is there:

## Cloned Dependency Source

Read-only dependency source repositories are available under
`.slim/clonedeps/repos/` for inspection. Do not edit these clones.

- `.slim/clonedeps/repos/<safe-name>/` — `<repo>` at `<ref>`; <one sentence on
  why this source is useful>.
- `.slim/clonedeps/repos/<safe-name-2>/` — `<repo>` at `<ref>`; <one sentence on
  why this source is useful>.

Also keep .slim/clonedeps.json updated as the structured manifest, but do not make agents read it for the basic repo list.

Cleanup

When the user asks to clean cloned dependencies, remove:

• .slim/clonedeps/repos/
• the managed clonedeps marker blocks from .gitignore and .ignore

Ask before removing .slim/clonedeps.json or the AGENTS.md section because they may be intentional project metadata.