oh-my-opencode-serverlocal 0.1.0

package/src/skills/clonedeps/README.md

@@ -0,0 +1,23 @@
+# clonedeps
+
+`clonedeps` is a bundled OpenCode workflow skill for cloning a small set of
+important dependency source repositories into a local ignored workspace so agents
+can read library internals.
+
+It is orchestrator-owned. The orchestrator delegates source discovery and URL/ref
+resolution to `@librarian`, asks for approval, then performs the git and
+filesystem operations directly.
+
+There is intentionally no helper script. Dependency discovery, ref validation,
+and cloning are repo-specific enough that the orchestrator/librarian workflow is
+safer than a brittle cross-ecosystem script.
+
+Cloned repositories live under `.slim/clonedeps/repos/<safe-repo-name>/`, one
+folder per source repository, and are ignored by git. `.slim/clonedeps.json` is
+intentionally trackable project
+metadata. After cloning, the orchestrator should add or update a concise
+`## Cloned Dependency Source` section in root `AGENTS.md` that lists each
+read-only cloned repo path directly with a one-sentence purpose.
+
+If `.slim/clonedeps.json` already exists, read it first and reuse those clones
+before asking `@librarian` for new recommendations.

package/src/skills/clonedeps/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: clonedeps
+description: Clone important project dependency source code into an ignored local workspace so OpenCode can inspect library internals. Use when the user asks to clone dependencies, inspect dependency/source internals, understand SDK/framework behavior from source, debug library implementation details, or make core dependency repos locally readable. Do not use for ordinary API/docs questions where @librarian is enough.
+---
+
+# 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:
+
+```md
+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: Update Ignore Files
+
+Before cloning artifacts or cleaning cloned dependencies, inspect existing
+`.gitignore` and `.ignore`. Update the managed block in place when present;
+otherwise append it. Add only the missing exact lines below, never duplicate
+entries or modify unrelated rules. These blocks keep cloned artifacts git-local
+while the `.ignore` allowlist keeps them readable to OpenCode.
+
+`.gitignore`:
+
+```gitignore
+# BEGIN oh-my-opencode-slim clonedeps
+.slim/clonedeps/repos/
+# END oh-my-opencode-slim clonedeps
+```
+
+`.ignore`:
+
+```ignore
+# 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
+```
+
+### Step 5: Clone Sources Manually
+
+Create one folder per source repository under:
+
+```text
+.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 6: Write Local State
+
+Write `.slim/clonedeps.json` so future agents know what exists:
+
+```json
+{
+  "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 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:
+
+```markdown
+## 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.

package/src/skills/clonedeps/codemap.md

@@ -0,0 +1,32 @@
+# src/skills/clonedeps/
+
+## Responsibility
+Manages the cloning and management of read-only dependency source repositories into `.slim/clonedeps/repos/` for offline inspection. This skill provides a workflow (not a command wrapper) that guides the orchestrator and `@librarian` through cloning dependency sources so agents can inspect library internals without requiring network access.
+
+## Design
+- **Workflow skill, not a command wrapper**: No helper scripts or TypeScript utility functions. The orchestrator owns the decision-making; `@librarian` recommends sources; the orchestrator performs filesystem/git operations directly.
+- **Read-only clones**: Dependencies are cloned into `.slim/clonedeps/repos/` and should not be modified.
+- **Cache strategy**: Existing clones are reused when they satisfy the task. Only fetch when the manifest entry is missing or stale.
+- **Agent-driven**: No runtime TS helpers (no `getClonedDepPath` utility). Agents resolve paths from `.slim/clonedeps.json` if needed.
+- **Configuration**: Uses `.slim/clonedeps.json` in the project root to define which repositories are cloned and their checked-out refs.
+
+## Flow
+1. **Check existing state**: Read `.slim/clonedeps.json` (if it exists). Check whether each listed `path` exists under `.slim/clonedeps/repos/`.
+2. **Ask librarian for plan**: Delegate dependency discovery and source resolution to `@librarian`, who returns a small plan (dependency name, repo URL, ref, package subdirectory, reason).
+3. **Verify and confirm**: Orchestrator verifies refs with `git ls-remote`, avoids unsafe URLs, presents plan to user, and gets approval before cloning.
+4. **Clone sources**: Orchestrator runs git commands directly. Creates one folder per source under `.slim/clonedeps/repos/<safe-repo-name>/`. Prefers shallow clones, pinned tags, HTTPS URLs.
+5. **Write local state**: Writes `.slim/clonedeps.json` with structured manifest (version, updatedAt, dependencies array).
+6. **Update ignore files**: Adds idempotent marker blocks to `.gitignore` and `.ignore`.
+7. **Register in AGENTS.md**: Appends a `## Cloned Dependency Source` section so future agents know what exists.
+
+## Integration
+- **Consumed by**: Agents that need to inspect dependency internals (e.g., `@librarian`, `@explorer`) via the registered paths in AGENTS.md.
+- **Depends on**: Git CLI (for `git clone`, `git ls-remote`), `.slim/clonedeps.json` manifest.
+- **Outputs**: Local filesystem paths under `.slim/clonedeps/repos/` for agent inspection.
+
+## Notes
+- Cloned repositories are read-only and should not be edited.
+- The cache directory (`.slim/clonedeps/repos/`) is in the **project directory**, not the user's home directory.
+- This skill is for development and debugging; it does not affect runtime behavior.
+- `.slim/clonedeps.json` is small structured metadata that can be committed.
+- Only `.slim/clonedeps/repos/` is gitignored.

package/src/skills/codemap/README.md

@@ -0,0 +1,59 @@
+# Codemap Skill
+
+Repository understanding and hierarchical codemap generation.
+
+## Overview
+
+Codemap helps orchestrators map and understand codebases by:
+
+1. Selecting relevant code/config files using LLM judgment
+2. Creating `.slim/codemap.json` for change tracking
+3. Generating empty `codemap.md` templates for fixers to fill in
+
+Legacy `.slim/cartography.json` state is migrated to `.slim/codemap.json` automatically.
+
+## Commands
+
+```bash
+# Initialize mapping
+node codemap.mjs init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
+
+# Check what changed
+node codemap.mjs changes --root /repo
+
+# Update hashes
+node codemap.mjs update --root /repo
+```
+
+## Outputs
+
+### .slim/codemap.json
+
+```json
+{
+  "metadata": {
+    "version": "1.0.0",
+    "last_run": "2026-01-25T19:00:00Z",
+    "include_patterns": ["src/**/*.ts"],
+    "exclude_patterns": ["node_modules/**"]
+  },
+  "file_hashes": {
+    "src/index.ts": "abc123..."
+  },
+  "folder_hashes": {
+    "src": "def456..."
+  }
+}
+```
+
+### codemap.md (per folder)
+
+Empty templates created in each folder for fixers to fill with:
+- Responsibility
+- Design patterns
+- Data/control flow
+- Integration points
+
+## Installation
+
+Installed automatically via oh-my-opencode-slim installer when custom skills are enabled.

package/src/skills/codemap/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: codemap
+description: Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping
+---
+
+# Codemap Skill
+
+You help users understand and map repositories by creating hierarchical codemaps.
+
+## When to Use
+
+- User asks to understand/map a repository
+- User wants codebase documentation
+- Starting work on an unfamiliar codebase
+
+## Workflow
+
+### Step 1: Check for Existing State
+
+**First, check if `.slim/codemap.json` exists in the repo root.**
+
+If it does not exist, check for legacy state at `.slim/cartography.json`.
+
+If legacy state exists: move `.slim/cartography.json` to `.slim/codemap.json`, then continue with change detection.
+
+If `.slim/codemap.json` exists: Skip to Step 3 (Detect Changes) - no need to re-initialize.
+
+If neither file exists: Continue to Step 2 (Initialize).
+
+### Step 2: Initialize (Only if no state exists)
+
+1. **Analyze the repository structure** - List files, understand directories
+2. **Infer patterns** for **core code/config files ONLY** to include:
+   - **Include**: `src/**/*.ts`, `package.json`, etc.
+   - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
+     - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
+     - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
+     - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
+   - Respect `.gitignore` automatically
+3. **Run codemap.mjs init**:
+
+```bash
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs init \
+  --root ./ \
+  --include "src/**/*.ts" \
+  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
+```
+
+This creates:
+- `.slim/codemap.json` - File and folder hashes for change detection
+- Empty `codemap.md` files in all relevant subdirectories
+
+4. **Delegate codemap writing to Fixer agents** - Spawn one fixer per folder to read code and create or update its specific `codemap.md` file.
+
+### Step 3: Detect Changes (If state already exists)
+
+1. **Run codemap.mjs changes** to see what changed:
+
+```bash
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs changes \
+  --root ./
+```
+
+2. **Review the output** - It shows:
+   - Added files
+   - Removed files
+   - Modified files
+   - Affected folders
+
+3. **Only update affected codemaps** - Spawn one fixer per affected folder to update its `codemap.md`.
+4. **Run update** to save new state:
+
+```bash
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs update \
+  --root ./
+```
+
+### Step 4: Finalize Repository Atlas (Root Codemap)
+
+Once all specific directories are mapped, the Orchestrator must create or update the root `codemap.md`. This file serves as the **Master Entry Point** for any agent or human entering the repository.
+
+1.  **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose.
+2.  **Aggregate Sub-Maps**: Create a "Repository Directory Map" section. For every folder that has a `codemap.md`, extract its **Responsibility** summary and include it in a table or list in the root map.
+3.  **Cross-Reference**: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.
+
+### Step 5: Register Codemap in AGENTS.md
+
+**OpenCode auto-loads `AGENTS.md` into agent context on every session.** To ensure agents automatically discover and use the codemap, update (or create) `AGENTS.md` at the repo root:
+
+1. If `AGENTS.md` already exists and already contains a `## Repository Map` section, **skip this step** - the reference is already set up.
+2. If `AGENTS.md` exists but has no `## Repository Map` section, **append** the section below.
+3. If `AGENTS.md` doesn't exist, **create** it with the section below.
+
+```markdown
+## Repository Map
+
+A full codemap is available at `codemap.md` in the project root.
+
+Before working on any task, read `codemap.md` to understand:
+- Project architecture and entry points
+- Directory responsibilities and design patterns
+- Data flow and integration points between modules
+
+For deep work on a specific folder, also read that folder's `codemap.md`.
+```
+
+This is idempotent - repeated codemap runs will detect the existing section and skip. No duplication.
+
+## Codemap Content
+
+Fixers are responsible for writing `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
+
+- **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
+- **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
+- **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
+- **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.
+
+Example codemap:
+
+```markdown
+# src/agents/
+
+## Responsibility
+Defines agent personalities and manages their configuration lifecycle.
+
+## Design
+Each agent is a prompt + permission set. Config system uses:
+- Default prompts (orchestrator.ts, explorer.ts, etc.)
+- User overrides from ~/.config/opencode/oh-my-opencode-slim.json
+- Permission wildcards for skill/MCP access control
+
+## Flow
+1. Plugin loads → calls getAgentConfigs()
+2. Reads user config preset
+3. Merges defaults with overrides
+4. Applies permission rules (wildcard expansion)
+5. Returns agent configs to OpenCode
+
+## Integration
+- Consumed by: Main plugin (src/index.ts)
+- Depends on: Config loader, skills registry
+```
+
+Example **Root Codemap (Atlas)**:
+
+```markdown
+# Repository Atlas: oh-my-opencode-slim
+
+## Project Responsibility
+A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and multiplexer-assisted child sessions.
+
+## System Entry Points
+- `src/index.ts`: Plugin initialization and OpenCode integration.
+- `package.json`: Dependency manifest and build scripts.
+- `oh-my-opencode-slim.json`: User configuration schema.
+
+## Directory Map (Aggregated)
+| Directory | Responsibility Summary | Detailed Map |
+|-----------|------------------------|--------------|
+| `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
+| `src/features/` | Core logic for tmux integration and session state. | [View Map](src/features/codemap.md) |
+| `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |
+```

package/src/skills/codemap/codemap.md

@@ -0,0 +1,36 @@
+# src/skills/codemap/
+
+## Responsibility
+
+- Provide a command-style skill package that standardizes repository mapping workflows for unfamiliar codebases.
+- Define the task contract used by Orchestrator/fixer agents via `SKILL.md` and operational guidance via `README.md`.
+- Generate and evolve change-aware codemap state artifacts (`.slim/codemap.json`) and scaffold placeholders (`codemap.md`).
+
+## Design
+
+- Contract layer: `SKILL.md` (machine prompt contract) + `README.md` (human-facing operation notes).
+- Execution layer: `scripts/codemap.mjs` exports deterministic helper functions:
+  - `parseArgs(argv)`
+  - `cmdInit`, `cmdChanges`, `cmdUpdate`
+  - `selectFiles`, `computeFileHash`, `computeFolderHash`, `createEmptyCodemap`
+  - `loadState`, `saveState`, `migrateLegacyState`
+- Persistence model: JSON state at `.slim/codemap.json` with `metadata`, `file_hashes`, and `folder_hashes`.
+- Testing layer: `scripts/codemap.test.ts` validates pattern matching, hash determinism, and migration behavior.
+- The script intentionally avoids network and mutates only filesystem-local state and codemap templates.
+
+## Flow
+
+- Entry point `main(argv)` parses command and arguments (`init|changes|update`, `--root`, `--include`, `--exclude`, `--exception`) and dispatches via strict branches.
+- `cmdInit()` computes include/exclude candidate sets using `selectFiles()` and writes:
+  1) `.slim/codemap.json` via `saveState()`
+  2) one `codemap.md` per discovered folder via `createEmptyCodemap()`.
+- `cmdChanges()` reloads state (`loadState()` + `migrateLegacyState()`), recomputes current hashes, emits added/removed/modified diffs and affected folder list, and exits non-zero if state is absent.
+- `cmdUpdate()` recomputes full state from existing metadata and persists it, used after targeted fixers finish updates.
+- `codemap` skill invocation path in SKILL workflow is explicit: Step 1 checks `.slim/codemap.json` or `.slim/cartography.json`, then Step 2/3 selects init or incremental path.
+
+## Integration
+
+- Installed under OpenCode through `src/cli/custom-skills.ts` as `name: 'codemap'`, `sourcePath: 'src/skills/codemap'`.
+- `src/cli/install.ts` copies this directory into the user skill directory; OpenCode executes `scripts/codemap.mjs` from that context.
+- `src/hooks/filter-available-skills/index.ts` applies agent-level skill gating via names from `getSkillPermissionsForAgent()`.
+- `scripts/verify-release-artifact.ts` includes codemap skill metadata and runtime checks as required packaged files.