opencode-agent-skills-md 1.0.0 → 1.1.0

package/openspec/changes/archive/2026-06-14-skills-core-decouple/tasks.md

@@ -1,64 +0,0 @@
-# Tasks: Skills Core Decouple
-
-## Review Workload Forecast
-
-| Field | Value |
-|-------|-------|
-| Estimated changed lines | PR1≈350; PR2≈250; PR3≈150; aggregate≈750 |
-| 400-line budget risk | Low per PR |
-| Chained PRs recommended | Yes |
-| Suggested split | PR1 core-extraction → PR2 opencode-adapter → PR3 subpath-exports |
-| Delivery strategy | force-chained |
-| Chain strategy | stacked-to-main |
-
-Decision needed before apply: No
-Chained PRs recommended: Yes
-Chain strategy: stacked-to-main
-400-line budget risk: Low
-
-### Suggested Work Units
-
-| Unit | Goal | Likely PR | Notes |
-|------|------|-----------|-------|
-| 1 | Extract portable core with import guard | PR 1 | Base=main; merge after `pnpm run typecheck` + `pnpm test` |
-| 2 | Add OpenCode host and thin adapter | PR 2 | Base=main after PR1 merge; keep root behavior unchanged |
-| 3 | Publish subpath exports and built smoke tests | PR 3 | Base=main after PR2 merge; verify build + e2e |
-
-## Phase 1: PR1 — Core Extraction
-
-- [x] 1.1 Capture a green baseline with `pnpm run typecheck` and `pnpm test` before moving files.
-- [x] 1.2 RED: add `tests/core/agnostic.test.ts` with a static walk over `dist/core/**` for zero `@opencode-ai/plugin` imports.
-- [x] 1.3 Move host-agnostic code from `src/utils.ts` and `src/skills.ts` into `src/core/{types,parse,discovery,scripts,match,content}.ts`.
-- [x] 1.4 Add `src/core/index.ts`; update `src/utils.ts` and `src/skills.ts` to re-export or consume core without behavior changes.
-- [x] 1.5 Update `rolldown.config.js` for a temporary `dist/core` entry while preserving the current plugin build. *(Superseded by PR3 3.2 — multi-entry build emits both `dist/opencode/index.js` and `dist/core/index.js` plus the legacy `dist/plugin.mjs` alias.)*
-- [x] 1.6 GREEN gate: `pnpm run typecheck` and `pnpm test` pass with the new core boundary.
-
-## Phase 2: PR2 — OpenCode Adapter
-
-- [x] 2.1 Add `src/opencode/host.ts` as the only concrete `SkillHostClient` and `SkillHostSession` implementation.
-- [x] 2.2 Add `src/opencode/tools.ts` and rewrite tool factories to compose core logic through the host.
-- [x] 2.3 Move plugin composition to `src/opencode/plugin.ts`; keep `src/plugin.ts` as a thin compatibility shim until PR3.
-- [x] 2.4 Move `src/superpowers.ts` to `src/opencode/superpowers.ts` and wire `src/opencode/index.ts` as the adapter entry.
-- [x] 2.5 Verify R5/R6 by running `tests/integration/plugin.test.ts` and `tests/e2e/startup-smoke.test.ts` unchanged.
-- [x] 2.6 GREEN gate: `pnpm run typecheck` and `pnpm test` pass before merge.
-
-## Phase 3: PR3 — Subpath Exports (public surface change)
-
-- [x] 3.1 Add `exports` map to `package.json` with `.` and `./core` subpaths (each with `types` + `import` + `default` conditions) and point `main` at `dist/opencode/index.js`.
-- [x] 3.2 Rewrite `rolldown.config.js` to multi-entry emit `dist/opencode/index.js` and `dist/core/index.js`; add `tsconfig.build.json` for `tsc --emitDeclarationOnly` so `.d.ts` files travel with the JS chunks.
-- [x] 3.3 Add `tests/core/subpath.test.ts` — resolves `opencode-agent-skills-md/core` via the package's exports field, asserts the portable API is exported, and walks the built chunk to prove no `@opencode-ai/plugin` reference leaks in.
-- [x] 3.4 Add `tests/opencode/subpath.test.ts` — resolves `opencode-agent-skills-md` (root) via the exports field, asserts the default export + `SkillsPlugin` are the same factory function, and proves module load is side-effect safe.
-- [x] 3.5 Add `pretest` hook that runs `pnpm run build` first so the subpath tests always run against fresh built artifacts.
-- [x] 3.6 Remove `src/plugin.ts` compat shim (now redundant); build entry is `src/opencode/index.ts` directly. A legacy `dist/plugin.mjs` alias is preserved via a third rolldown entry so any downstream consumer still importing the old path keeps working.
-- [x] 3.7 Update `README.md` with a "Programmatic subpath exports" section documenting both subpaths, the intended consumer (harness authors), and a code example using the core.
-- [x] 3.8 GREEN gate (final): `pnpm run typecheck` + `pnpm test` + `pnpm run build` all green; the new subpath tests pass against the freshly built artifacts.
-- [x] 3.9 Update `openspec/changes/skills-core-decouple/tasks.md` to mark all PR3 tasks done and persist the final apply-progress to engram.
-
-### PR3 Outcome
-
-- `pnpm run typecheck` — clean (0 errors)
-- `pnpm test` — 42/42 (21 unit + 3 agnostic + 3 core-subpath + 8 opencode-host + 3 opencode-subpath + 3 integration + 1 e2e)
-- `pnpm run build` — emits `dist/opencode/{index.js,index.d.ts,...}`, `dist/core/{index.js,index.d.ts,...}`, and the legacy `dist/plugin.mjs` alias
-- The `src/opencode/tools.ts` factory consts needed explicit `: ReturnType<typeof tool>` annotations to break a Zod-shape leak in the inferred return type that broke `tsc --emitDeclarationOnly` with TS2883 (non-portable inferred type). Internal change only — no behavior delta, no public API change.
-- The `package.json#exports` block needed a `default` condition on each subpath in addition to `import` so Node 24 can resolve the package via self-reference when called from a CJS context (`require.resolve`).
-- The integration test (`tests/integration/plugin.test.ts`) and the e2e test (`tests/e2e/startup-smoke.test.ts`) had their import targets updated to the new entry points (`src/opencode` and `dist/opencode/index.js` respectively).

package/openspec/changes/archive/2026-06-14-skills-core-decouple/verify-report.md

@@ -1,75 +0,0 @@
-# Verification Report: skills-core-decouple
-
-**Change:** skills-core-decouple
-**Phase:** verify
-**Mode:** strict_tdd=true
-**Date:** 2026-06-14
-
----
-
-## Command Evidence
-
-| Command | Result | Evidence |
-|---------|--------|----------|
-| `pnpm run typecheck` | PASS | `tsc --noEmit` exits 0, 0 errors |
-| `pnpm test` | PASS | 42/42 tests pass (21 unit + 3 agnostic + 3 core-subpath + 8 opencode-host + 3 opencode-subpath + 3 integration + 1 e2e) |
-| `pnpm run build` | PASS | Emits `dist/opencode/index.js`, `dist/core/index.js`, `dist/_chunks/*`, and legacy `dist/plugin.mjs` alias |
-
----
-
-## Requirement Compliance Matrix
-
-| Requirement | Status | Evidence |
-|-------------|--------|----------|
-| R1 — Core module independence | **PASS** | Grep `@opencode-ai/plugin` in `src/core/**/*.ts` → 0 matches. Test `tests/core/agnostic.test.ts` passes. |
-| R2 — Boundary interface | **PASS** | `SkillHostClient` and `SkillHostSession` declared in `src/core/types.ts`. Only `src/opencode/host.ts` contains a concrete implementation. Grep across `src/` shows no other implementation. |
-| R3 — Backward-compatible root export | **PASS** | `tests/opencode/subpath.test.ts` passes: root resolves to `dist/opencode/index.js`, default export is `SkillsPlugin` factory. Tool names unchanged (`get_available_skills`, `read_skill_file`, `run_skill_script`, `use_skill`). |
-| R4 — Framework-agnostic subpath export | **PASS** | `tests/core/subpath.test.ts` passes: `opencode-agent-skills-md/core` resolves via exports field to `dist/core/index.js`. Build emits `dist/core/index.js` + `.d.ts` files. Static walk of dist proves no `@opencode-ai/plugin` reference leaks in. |
-| R5 — Discovery semantics preservation | **PASS** | `src/core/discovery.ts` `getDefaultOpencodeRoots()` defines 4-location priority (`.opencode/skills/`, `.claude/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`). First-match-wins implemented at line 130: `if (!skill || skillsByName.has(skill.name)) continue;`. `tests/integration/plugin.test.ts` passes. |
-| R6 — Public surface freeze | **PASS** | `src/opencode/tools.ts` creates 4 tool factories with unchanged names (`GetAvailableSkills`, `ReadSkillFile`, `RunSkillScript`, `UseSkill`). All `tests/integration/*` and `tests/e2e/*` pass without modification. |
-
----
-
-## Spec Scenario Compliance
-
-| Scenario | Covered By | Result |
-|----------|------------|--------|
-| core is decoupled from the OpenCode SDK | `tests/core/agnostic.test.ts` + static grep | PASS |
-| opencode host is the only concrete implementation | `src/opencode/host.ts` + grep search | PASS |
-| root export still loads the OpenCode plugin | `tests/opencode/subpath.test.ts` | PASS |
-| subpath export does not pull in the OpenCode SDK | `tests/core/subpath.test.ts` | PASS |
-| discovery priority and first-match-wins are preserved | `tests/integration/plugin.test.ts` | PASS |
-| public tool surface is unchanged | All test suites (42/42) | PASS |
-
----
-
-## Task Completion
-
-All tasks in `openspec/changes/skills-core-decouple/tasks.md` are checked `[x]`.
-
----
-
-## Findings
-
-### CRITICAL
-None.
-
-### WARNING
-None.
-
-### SUGGESTION
-None.
-
----
-
-## Final Verdict
-
-**PASS**
-
-All 6 requirements verified. All 42 tests green. Build emits both subpaths correctly. Public surface unchanged.
-
----
-
-## Next Recommended
-
-`sdd-archive` — ready to sync delta specs and close the change.

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/apply-progress.md

@@ -1,136 +0,0 @@
-# Apply Progress: Fix Skill-Loading Regression
-
-## Status: ok
-
-All chained PR tasks complete. Verification clean.
-
-## Commit Stack
-
-```
-d2c3584 test: correct dedupe assertion to allow other matches
-c1f5b27 chore: verify skill loading regression fix
-8c7de19 refactor: clean up discovery source helpers
-7e4293e fix: restore baseline skill discovery sources
-b764c15 test: add discovery breadth regression coverage
-9e975ab refactor: preserve optional skill callback seam
-fd4ab41 fix: restore use-skill callback wiring
-c64d4e7 test: add skill loading callback regression coverage
-01c4b46 chore(sdd): add fix-skill-loading-regression change artifacts
-```
-
-## Phase Summary
-
-### PR 1: Callback wiring (host-adapter)
-
-- **1.1 RED** — `c64d4e7`: failing regression tests in
-  `tests/opencode/plugin.test.ts` (3 new) and
-  `tests/integration/plugin.test.ts` (1 new).
-- **1.2 GREEN** — `fd4ab41`: added `OnSkillLoaded` type alias and
-  optional 4th arg on `createSkillTools` in `src/opencode/tools.ts`;
-  passed a 4-line callback that records the loaded skill in
-  `loadedSkillsPerSession` from `src/opencode/plugin.ts`.
-- **1.3 REFACTOR** — `9e975ab`: extracted a tiny `sendMessage` helper
-  in `tests/opencode/plugin.test.ts` to reduce ~30 lines of chat.message
-  dispatch boilerplate. Production code unchanged.
-
-### PR 2: Discovery breadth (core)
-
-- **2.1 RED** — `b764c15`: added regression nets in
-  `tests/integration/skill-discovery.test.ts` covering all four
-  priority locations (`.opencode/skills`, `.claude/skills`,
-  `~/.config/opencode/skills`, `~/.claude/skills`), first-match-wins
-  shadowing, default duplicate-warning callback, and the partial-trigger
-  R5 scenario. Added fixtures under
-  `tests/fixtures/skills/{project,home}/.claude/skills/`.
-- **2.2 GREEN** — `7e4293e`: tightened JSDoc on `getDefaultOpencodeRoots`
-  to reference pre-refactor commit `c2d8e74` and the intentional
-  maxDepth widening (commit `12de52a`).
-- **2.3 REFACTOR** — `8c7de19`: extracted `DEFAULT_DISCOVERY_MAX_DEPTH`
-  constant to remove the repeated `maxDepth: 3` magic number.
-
-### PR 3: Optional cleanup / verification
-
-- **3.1 RED/GREEN** — Coverage is complete for spec R3 (callback fires,
-  dedupe, missing-callback) and R5 (priority + first-match-wins,
-  baseline match, partial-trigger). No additional regression needed.
-- **3.2 REFACTOR** — Production code is already minimal. No
-  behavior-neutral cleanup that would reduce duplication.
-- **3.3 VERIFY** — `c1f5b27`: empty chore commit acknowledging
-  `pnpm run typecheck` clean and `pnpm test` 102/102 green.
-
-## Files Changed
-
-### Production (3 files, 33 insertions, 14 deletions)
-
-- `src/opencode/tools.ts` — added `OnSkillLoaded` type and optional
-  callback parameter on `createSkillTools`.
-- `src/opencode/plugin.ts` — wired the callback to update
-  `loadedSkillsPerSession` in the module-level Map.
-- `src/core/discovery.ts` — JSDoc clarified and `DEFAULT_DISCOVERY_MAX_DEPTH`
-  constant extracted.
-
-### Tests (2 files modified, 4 new tests)
-
-- `tests/opencode/plugin.test.ts` — added 3 regression tests covering
-  callback wiring, dedupe, and missing-callback. Extracted `sendMessage`
-  helper.
-- `tests/integration/plugin.test.ts` — added 1 end-to-end regression
-  test for the full plugin path (bootstrap → use_skill → chat.message
-  dedupe).
-
-### Fixtures (2 new files)
-
-- `tests/fixtures/skills/project/.claude/skills/claude-project-only-skill/SKILL.md`
-- `tests/fixtures/skills/home/.claude/skills/claude-user-only-skill/SKILL.md`
-
-### Change artifacts (4 new files, tracked in `01c4b46`)
-
-- `openspec/changes/fix-skill-loading-regression/{proposal,design,tasks}.md`
-- `openspec/changes/fix-skill-loading-regression/specs/core-decoupling/spec.md`
-
-## TDD Cycle Evidence
-
-| Task | Test File | Layer | Safety Net | RED | GREEN | TRIANGULATE | REFACTOR |
-|------|-----------|-------|------------|-----|-------|-------------|----------|
-| 1.1 | `tests/opencode/plugin.test.ts` | Unit | ✅ 18/18 | ✅ Written (2 fail) | ✅ Passed | ✅ 3 cases | ✅ Clean |
-| 1.1 | `tests/integration/plugin.test.ts` | Integration | ✅ 18/18 | ✅ Written (1 fail) | ✅ Passed | ➖ Single | ✅ Clean |
-| 1.2 | (production code) | — | ✅ 18/18 | ✅ Written | ✅ Passed | — | — |
-| 1.3 | (test refactor) | Unit | — | — | — | — | ✅ Helper extracted |
-| 2.1 | `tests/integration/skill-discovery.test.ts` | Integration | ✅ 22/22 | ✅ Written (regression net) | ✅ Passed | ✅ 4 cases | ✅ Clean |
-| 2.2 | (production doc update) | — | — | — | — | — | ✅ JSDoc tightened |
-| 2.3 | (production refactor) | — | — | — | — | — | ✅ Constant extracted |
-
-## Verification
-
-- `pnpm run typecheck` — clean (0 errors)
-- `pnpm test` (full suite: unit + core + opencode + integration + e2e)
-  — 102 pass / 0 fail / 0 skipped
-- `node --import tsx --test src/utils.test.ts tests/core/*.test.ts
-  tests/opencode/plugin.test.ts tests/integration/plugin.test.ts
-  tests/integration/skill-discovery.test.ts tests/e2e/*.test.ts`
-  — 89 pass / 0 fail
-
-## Notable Discoveries (for sdd-verify)
-
-- **Dedupe assertion gotcha**: An earlier draft of the dedupe test
-  asserted that zero `<skill-evaluation-required>` injections fire
-  after `use_skill`. The keyword matcher legitimately matches other
-  skills that share tokens with the query (e.g., `user-only-skill`,
-  `nested-skill`, `shared-skill` all match `"use the script skill"`
-  via the `script`/`skill`/`use` tokens). The correct regression is
-  that the loaded skill is filtered OUT of the matched list — see the
-  `for (const prompt of evaluationInjections)` loop in both test files.
-- **`getDefaultOpencodeRoots` maxDepth deviation**: Pre-refactor
-  `c2d8e74` used `maxDepth: 1` for the Claude-side roots. Commit
-  `12de52a` widened them to 3 deliberately. The current code preserves
-  the widening; the spec R5 only requires the four-location priority,
-  not the depths. The regression net locks the depth=3 choice.
-- **Plugin cache / marketplace discovery**: `c2d8e74` discovered
-  `~/.claude/plugins/cache/` and `~/.claude/plugins/marketplaces/` via
-  `claude.ts`. These are intentionally out of scope for this fix; the
-  proposal scopes the change to the four standard locations.
-- **Callback wiring shape**: `UseSkill` already accepted an optional
-  `onSkillLoaded(sessionID, skillName)` parameter before the fix.
-  `createSkillTools` simply never accepted/forwarded it. The fix is a
-  minimal signature change on `createSkillTools`; `UseSkill` and the
-  host adapter logic are unchanged.

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/archive-report.md

@@ -1,77 +0,0 @@
-# Archive Report: fix-skill-loading-regression
-
-## Change Metadata
-
-| Field | Value |
-|-------|-------|
-| Change name | `fix-skill-loading-regression` |
-| Archived date | 2026-06-17 |
-| Archive path | `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/` |
-| Spec domain | `core-decoupling` |
-| Delivery strategy | force-chained |
-| Chain strategy | stacked-to-main |
-
-### Commits (9 total, per tasks.md)
-
-```
-d2c3584 test: correct dedupe assertion to allow other matches
-c1f5b27 chore: verify skill loading regression fix
-8c7de19 refactor: clean up discovery source helpers
-7e4293e fix: restore baseline skill discovery sources
-b764c15 test: add discovery breadth regression coverage
-9e975ab refactor: preserve optional skill callback seam
-fd4ab41 fix: restore use-skill callback wiring
-c64d4e7 test: add skill loading callback regression coverage
-01c4b46 chore(sdd): add fix-skill-loading-regression change artifacts
-```
-
-## Spec Delta Summary
-
-### MODIFIED Requirements
-
-| Requirement | Domain | Action | Details |
-|-------------|--------|--------|---------|
-| R3 — Backward-Compatible Root Export | core-decoupling | MODIFIED | Strengthened to assert observable skill loading: `onSkillLoaded` callback fires once per session, `SKILL.md` injected once per session, session dedupe via `loadedSkillsPerSession`. Added 3 new scenarios: callback fires, session dedupe, missing callback safe. |
-| R5 — Discovery Semantics Preservation | core-decoupling | MODIFIED | Strengthened to pin the surfaced skill set to pre-refactor baseline commit `c2d8e74`. Added 2 new scenarios: matches pre-refactor skill set, partial-trigger regression. |
-
-### Unchanged Requirements
-R1 (Core Module Independence), R2 (Boundary Interface Location), R4 (Framework-Agnostic Subpath Export), R6 (Public Surface Freeze) — unchanged by this delta.
-
-## Verification Result
-
-**PASS** — `verify-report.md` (2026-06-17)
-- 9/9 tasks complete
-- 102/102 tests green (unit: 42, core: 20, opencode: 22, integration: 17, e2e: 1)
-- Typecheck: clean
-- TDD compliance: 7/7 checks passed
-- CRITICAL issues: none
-- 7/7 spec scenarios compliant (R3: 4/4, R5: 3/3)
-
-## Artifacts
-
-### Archived Change
-- `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/proposal.md`
-- `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/design.md`
-- `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/specs/core-decoupling/spec.md` (delta)
-- `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/tasks.md`
-- `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/verify-report.md`
-- `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/apply-progress.md`
-
-### Source of Truth Updated
-- `openspec/specs/core-decoupling/spec.md` — R3 and R5 updated in place
-
-## Lessons Learned
-
-1. **Callback seam was pre-existing but unwired**: `UseSkill` already accepted `onSkillLoaded?` before the fix; `createSkillTools` simply never accepted or forwarded it. The fix was a minimal 2-line production change — a good reminder that "broken" behavior is often a missing wire, not a missing feature.
-
-2. **Dedupe assertion nuance**: The correct regression target for session dedupe is that the *loaded* skill is filtered from `<skill-evaluation-required>` injections — not that zero injections fire (other skills may match the same query tokens). Getting this wrong produces false negatives in the test.
-
-3. **maxDepth deviation from baseline was deliberate**: Pre-refactor `c2d8e74` used `maxDepth: 1` for Claude-side roots; `12de52a` widened to 3 deliberately. The JSDoc now documents this intentionally and the regression net locks `maxDepth: 3` in place.
-
-4. **Discovery breadth vs. semantic search**: The refactor kept trigger-aware search, tags, Zod validation, and path safety — only the broad/semantic embedding matcher was removed. The fix restores breadth by widening `getDefaultOpencodeRoots` to the four standard locations without reintroducing embeddings.
-
-5. **Plugin/marketplace discovery out of scope**: The `c2d8e74` baseline also surfaced `~/.claude/plugins/cache/` and `~/.claude/plugins/marketplaces/`. The proposal correctly scoped the fix to the four standard locations only, leaving marketplace discovery as future work.
-
-## SDD Cycle Complete
-
-This change was fully planned (`sdd-propose`), specified (`sdd-spec`), designed (`sdd-design`), task-planned (`sdd-tasks`), implemented (`sdd-apply`), verified (`sdd-verify`), and archived (`sdd-archive`). The delta spec has been merged into `openspec/specs/core-decoupling/spec.md`. The archived change at `openspec/changes/archive/2026-06-17-fix-skill-loading-regression/` is the immutable audit trail.

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/design.md

@@ -1,89 +0,0 @@
-# Design: Fix Skill-Loading Regression
-
-## Technical Approach
-
-Restore the two regressions captured in Engram #1734 (`bugfix/skill-loading-regression`) and #1736 (`bugfix/skill-loading-regression-plan`) with the smallest host-adapter changes. First, thread the existing `onSkillLoaded` callback from `SkillsPlugin` through `createSkillTools()` into `UseSkill()` so a successful `use_skill` call updates session loaded-skill state again. Second, align `discoverAllSkills()` default source coverage with the pre-refactor baseline (`c2d8e74`) while keeping the current core/host split, search engine, tag filtering, trigger-aware ranking, Zod parsing, and path-safety checks intact. This design implements the proposal and gives the pending `core-decoupling` R3/R5 spec delta concrete code targets.
-
-Strict TDD order: add failing regression tests first, implement the minimum wiring/discovery fix, then refactor only if duplication appears.
-
-## Architecture Decisions
-
-### Decision: Restore loaded-skill state through the existing callback seam
-
-| Option | Tradeoff | Decision |
-|---|---|---|
-| Update `loadedSkillsPerSession` directly inside `UseSkill` | Couples tool code to plugin session state | Rejected |
-| Pass `onSkillLoaded` from `plugin.ts` → `createSkillTools()` → `UseSkill()` | Small signature change, preserves core/host boundaries | Chosen |
-
-Rationale: the callback already exists in `UseSkill`; the regression is that `createSkillTools()`/`SkillsPlugin` stopped threading it.
-
-### Decision: Restore discovery breadth in `core/discovery.ts`, not in search or host code
-
-| Option | Tradeoff | Decision |
-|---|---|---|
-| Reintroduce old semantic matcher | Larger rollback, discards current trigger/tag work | Rejected |
-| Expand default discovery roots/source handling to match baseline coverage | Narrow fix, keeps current search/ranking stack | Chosen |
-
-Rationale: discovery breadth is a source-enumeration concern. `searchSkills()`, trigger scoring, Zod validation, and safe file access stay unchanged.
-
-## Data Flow
-
-```text
-chat.message
-  -> getSkillSummaries() / matchSkillsByKeyword()
-  -> synthetic skill-evaluation prompt
-  -> model calls use_skill
-  -> createSkillTools().UseSkill()
-  -> host.injectContent(<skill ...>)
-  -> onSkillLoaded(sessionID, skillName)
-  -> loadedSkillsPerSession.add(skillName)
-  -> later chat.message skips already-loaded skills
-
-discoverAllSkills(directory)
-  -> baseline-aligned default roots
-  -> findSkillsRecursive()
-  -> parseSkillFile() [Zod]
-  -> Map<string, Skill> first-match-wins
-```
-
-## File Changes
-
-| File | Action | Description |
-|---|---|---|
-| `src/opencode/tools.ts` | Modify | Add an optional `onSkillLoaded` parameter to `createSkillTools()` and pass it into `UseSkill()` without changing tool behavior otherwise. |
-| `src/opencode/plugin.ts` | Modify | Provide the callback that records loaded skills per session and keep keyword matching / synthetic injection behavior unchanged. |
-| `src/core/discovery.ts` | Modify | Reconcile default discovery roots/source handling with baseline `c2d8e74`, preserving first-match-wins and duplicate warnings. |
-| `tests/integration/plugin.test.ts` | Modify | Add RED/GREEN regression coverage for baseline discovery breadth and end-to-end tool loading behavior. |
-| `tests/opencode/plugin.test.ts` | Modify | Add focused host-adapter regression coverage proving `use_skill` updates loaded-skill session state and prevents duplicate re-suggestion. |
-
-## Interfaces / Contracts
-
-```ts
-type OnSkillLoaded = (sessionID: string, skillName: string) => void;
-
-export function createSkillTools(
-  host: OpencodeSkillHost,
-  $: PluginInput["$"],
-  directory: string,
-  onSkillLoaded?: OnSkillLoaded
-): SkillTools;
-```
-
-`getDefaultOpencodeRoots(directory)` remains the canonical discovery-source definition. The fix may adjust its returned roots/depths to match the pre-refactor baseline, but it must continue returning `DiscoveryPath[]` and must not move host-specific knowledge into search or parsing modules.
-
-## Testing Strategy
-
-| Layer | What to Test | Approach |
-|---|---|---|
-| Unit/host | `use_skill` marks a skill as loaded again | In `tests/opencode/plugin.test.ts`, call `use_skill`, then send a matching message and assert no duplicate matched-skill injection is produced for that session. |
-| Integration | Discovery returns the baseline-visible skill set | In `tests/integration/plugin.test.ts`, extend the temp workspace as needed and compare discovered labels/names against the pre-refactor source expectations. |
-| Integration | Tool wiring still injects skill content | Reuse the mock host client to assert `<skill ...>` injection still happens while the callback seam is restored. |
-| E2E | N/A | No separate UI harness; session bookkeeping is the local proxy for icon-visible behavior. |
-
-## Migration / Rollout
-
-No migration required. Rollout is a normal bugfix; if the change grows past the 400-line review budget, keep the delivery split aligned with the force-chained stacked PR strategy.
-
-## Open Questions
-
-- [ ] None; verify the exact restored source set against `c2d8e74` during RED test authoring.

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/proposal.md

@@ -1,65 +0,0 @@
-# Proposal: Fix Skill-Loading Regression
-
-## Intent
-
-After the core-decoupling / discovery-filtering refactor, the plugin no longer visibly loads skills as before. Two regressions: (1) `onSkillLoaded` is no longer wired through `createSkillTools`/`UseSkill`, so loaded-skill state and the TUI icon never update; (2) discovery narrowed to literal-token search over local roots, so skills the old broad/semantic matcher surfaced no longer appear — blocking the follow-up `use_skill` call. This restores observable behavior while keeping the refactor's architectural wins.
-
-## Scope
-
-### In Scope
-- Re-wire `onSkillLoaded` through `createSkillTools` → `UseSkill` in `src/opencode/tools.ts` / `src/opencode/plugin.ts`
-- Restore pre-refactor discovery breadth in `src/core/discovery.ts` (surface the same skill set as baseline commit `c2d8e74`)
-- Regression tests in `tests/integration/plugin.test.ts` and `tests/opencode/plugin.test.ts`
-- Strengthen `core-decoupling` spec R3/R5 with skill-loading + discovery-breadth scenarios
-
-### Out of Scope
-- Reintroducing the old semantic embedding matcher (kept: trigger-aware search, tags, Zod validation, path safety, core/host split)
-- A new standalone skill-loading domain spec
-- TUI/host icon changes beyond callback wiring
-
-## Capabilities
-
-### New Capabilities
-- None
-
-### Modified Capabilities
-- `core-decoupling`: R3 (Backward-Compatible Root Export) and R5 (Discovery Semantics Preservation) are violated by the refactor. The delta strengthens both to assert observable skill loading (`onSkillLoaded` fires, `SKILL.md` injected, icon appears) and discovery breadth (same skill set as pre-refactor), plus regression scenarios.
-
-## Approach
-
-Smallest change restoring correctness: (1) thread `onSkillLoaded` back through the OpenCode tool factory so `use_skill` updates host loaded-skill state; (2) widen `discoverAllSkills()` to the pre-refactor source set so literal-token search no longer drops skills. Keep the new search stack; tests confirm the same skills surface. TDD: red regression test first, then green.
-
-## Affected Areas
-
-| Area | Impact | Description |
-|------|--------|-------------|
-| `src/opencode/tools.ts` | Modified | Re-wire `onSkillLoaded` in `createSkillTools`/`UseSkill` |
-| `src/opencode/plugin.ts` | Modified | Pass loaded-state callback into tool factory |
-| `src/core/discovery.ts` | Modified | Restore pre-refactor discovery breadth |
-| `tests/integration/plugin.test.ts` | New | Regression: skill surfaces + callback fires |
-| `tests/opencode/plugin.test.ts` | New | Regression: loaded-state update + icon |
-| `openspec/specs/core-decoupling/spec.md` | Modified (via delta) | Strengthen R3/R5 |
-
-## Risks
-
-| Risk | Likelihood | Mitigation |
-|------|------------|------------|
-| Widening discovery re-introduces duplicate / first-match bugs | Low | R5 first-match-wins tests already exist; extend them |
-| Fix scope grows beyond callback + discovery | Med | Delivery strategy `force-chained` → split into stacked PRs at the 400-line budget |
-| Literal-token search still misses edge skills after breadth fix | Low | Regression test mirrors the pre-refactor fixture set from `c2d8e74` |
-
-## Rollback Plan
-
-Revert the fix commits; the refactor stays intact (regression returns but the build stays green). Changes are isolated to `src/opencode/{tools,plugin}.ts` + `src/core/discovery.ts`, so rollback is a clean `git revert` of the fix PR(s).
-
-## Dependencies
-
-- Reference baseline: commit `c2d8e74` (pre-refactor `src/plugin.ts` / `src/tools.ts`)
-- Engram observations: #1734 (discovery), #1736 (decision), #664 (config)
-
-## Success Criteria
-
-- [ ] `use_skill` visibly loads a skill: `SKILL.md` injected, `onSkillLoaded` fires, TUI icon appears
-- [ ] `discoverAllSkills()` surfaces the same skill set as `c2d8e74` for the fixture locations
-- [ ] `pnpm run typecheck` clean; `pnpm test` (integration + opencode layers) green
-- [ ] `core-decoupling` delta spec R3/R5 scenarios pass

package/openspec/changes/archive/2026-06-17-fix-skill-loading-regression/specs/core-decoupling/spec.md

@@ -1,77 +0,0 @@
-# Delta for Core Decoupling
-
-## Purpose
-
-This delta strengthens `core-decoupling` R3 and R5 after the refactor introduced two regressions: (1) `onSkillLoaded` was dropped from the tool factory wiring, so `use_skill` no longer updates host loaded-skill state or injects `SKILL.md`; (2) `discoverAllSkills()` narrowed to literal-token search and dropped skills the pre-refactor matcher surfaced. Scope matches the proposal: no new requirements, no new spec domain — only R3 and R5 are tightened with regression scenarios.
-
-## MODIFIED Requirements
-
-### Requirement: Backward-Compatible Root Export (R3)
-
-Importing `opencode-agent-skills-md` (the package root) SHALL return the OpenCode plugin with the same shape and behavior as before this change. The four tool names (`use_skill`, `read_skill_file`, `run_skill_script`, `get_available_skills`) SHALL resolve. Additionally, `use_skill` SHALL visibly load a skill: the `onSkillLoaded` callback registered with `createSkillTools` SHALL fire exactly once per successful load per session, the loaded skill's `SKILL.md` content SHALL be injected into the agent context exactly once per session per skill, and the host SHALL observe the loaded-skill state update (TUI icon visible). The callback SHALL be threaded from `src/opencode/plugin.ts` → `createSkillTools` → `UseSkill`.
-
-(Previously: only asserted the four tool names resolve; did not cover observable skill loading or session-level dedupe.)
-
-#### Scenario: root export still loads the OpenCode plugin
-
-- GIVEN a consumer imports the package via its root export
-- WHEN the consumer resolves the four tool names from the returned plugin object
-- THEN all four tool names (`use_skill`, `read_skill_file`, `run_skill_script`, `get_available_skills`) are present
-- AND the test-skill load assertion in `tests/integration/startup-smoke.test.ts` passes
-
-#### Scenario: use_skill fires the onSkillLoaded callback
-
-- GIVEN the host registered an `onSkillLoaded` callback via `createSkillTools`
-- WHEN the agent calls `use_skill("test-skill")` on an unloaded skill
-- THEN the callback is invoked exactly once with the loaded skill identifier
-- AND the loaded skill's `SKILL.md` content is present in the agent context
-- AND the host's loaded-skill state reflects the new skill
-
-#### Scenario: use_skill does not re-inject the same skill in one session
-
-- GIVEN the agent has already loaded a given skill via `use_skill` in the current session
-- WHEN the agent calls `use_skill` with the same skill name again in the same session
-- THEN `onSkillLoaded` is NOT re-fired for that skill
-- AND the `SKILL.md` content is NOT re-injected into the context
-
-#### Scenario: missing callback does not break the load
-
-- GIVEN no `onSkillLoaded` is registered with `createSkillTools`
-- WHEN the agent calls `use_skill("any-skill")`
-- THEN the skill still loads and `SKILL.md` content is injected
-- AND no thrown error or unhandled rejection occurs
-
-### Requirement: Discovery Semantics Preservation (R5)
-
-When the OpenCode adapter delegates to the core's `discoverAllSkills()`, the adapter SHALL observe the same four-location priority and first-match-wins semantics defined by the existing skill behavior. The set of skills surfaced for the baseline fixture locations SHALL match the set surfaced by pre-refactor commit `c2d8e74`. An integration test that mirrors `tests/integration/*` SHALL pass against the new boundary.
-
-(Previously: asserted priority and first-match-wins but did not pin the surface skill set to the pre-refactor baseline; literal-token search was permitted to drop skills.)
-
-#### Scenario: discovery priority and first-match-wins are preserved
-
-- GIVEN skill fixtures exist under `.opencode/skills/`, `.claude/skills/`, `~/.config/opencode/skills/`, and `~/.claude/skills/`
-- WHEN the OpenCode adapter calls `discoverAllSkills()`
-- THEN the returned list follows the four-location priority
-- AND duplicate skill names resolve to the first matching location
-- AND the new integration test in `tests/core/` passes
-
-#### Scenario: discoverAllSkills matches the pre-refactor skill set
-
-- GIVEN the same fixture tree used by pre-refactor commit `c2d8e74`
-- WHEN the OpenCode adapter calls `discoverAllSkills()`
-- THEN every skill the baseline surfaced is also surfaced now
-- AND no skill the baseline surfaced is missing from the result
-
-#### Scenario: literal-token search does not drop the pre-refactor skill set
-
-- GIVEN a skill whose trigger tokens are partial substrings of the user's query (not exact match)
-- WHEN the user searches via the literal-token path in `discoverAllSkills()`
-- THEN that skill appears in the result
-- AND the four-location priority remains consistent with first-match-wins
-
-## Notes
-
-- No `ADDED Requirements`, no `REMOVED Requirements`, no `RENAMED Requirements`. R1, R2, R4, R6 are unchanged.
-- The new R3 scenario "missing callback does not break the load" preserves the host-agnostic split (core must not assume a callback).
-- The new R5 scenarios pin the pre-refactor skill set so widening discovery does not silently re-narrow.
-- All scenarios are written to be TDD-friendly: each maps to one or two test cases in `tests/integration/plugin.test.ts` and `tests/opencode/plugin.test.ts`.