opencode-agent-skills-md 1.0.1 → 1.1.0

package/plans/005-stop-swallowing-errors.md

@@ -1,246 +0,0 @@
-# Plan 005: Surface swallowed discovery and parse errors
-
-> **Executor instructions**: Follow this plan step by step. Run every
-> verification command and confirm the expected result before moving to the
-> next step. If anything in the "STOP conditions" section occurs, stop and
-> report — do not improvise. When done, update the status row for this plan
-> in `plans/README.md`.
->
-> **Drift check (run first)**: `git diff --stat fb45791..HEAD -- packages/core/src/discovery.ts packages/core/src/parse.ts packages/opencode-agent-skills-md/src/host.ts`
-> If any in-scope file changed since this plan was written, compare the
-> "Current state" excerpts against the live code before proceeding; on a
-> mismatch, treat it as a STOP condition.
-
-## Status
-
-- **Priority**: P2
-- **Effort**: S
-- **Risk**: LOW
-- **Depends on**: none
-- **Category**: correctness
-- **Planned at**: commit `fb45791`, 2026-06-29
-
-## Why this matters
-
-Four locations in the core and host packages silently swallow filesystem and
-parse errors with bare `catch {}` blocks. When a discovery root is
-inaccessible (permission denied), a SKILL.md file is corrupted, or a session
-context lookup fails, the failure produces no diagnostic output. Users see
-"no skills found" with no path to debug. Adding `debugLog` calls in these
-catch blocks makes failures discoverable when
-`OPENCODE_AGENT_SKILLS_DEBUG=1` is set, without changing the current
-graceful-degradation behavior.
-
-## Current state
-
-### 1. `packages/core/src/discovery.ts:87` — outer catch in `findSkillsRecursive`
-
-```ts
-  } catch { }
-```
-
-This wraps the entire `fs.access` + `walkDir` call. If `baseDir` exists but
-is unreadable, the error is invisible.
-
-### 2. `packages/core/src/discovery.ts:219` — inner catch in `listSkillFiles`
-
-```ts
-        } catch { }
-```
-
-This wraps `fs.stat` per entry. If a file in the skill directory can't be
-stat'd, the entry is silently skipped.
-
-### 3. `packages/core/src/parse.ts:91` — catch on `fs.readFile`
-
-```ts
-const content = await fs.readFile(skillPath, 'utf-8').catch(() => null);
-```
-
-If a SKILL.md can't be read, returns `null` with no diagnostic.
-
-Note: `parse.ts:107` (`try { parseYamlFrontmatter(...) } catch { return null; }`)
-is excluded — `parseYamlFrontmatter` already logs errors via `debugLog` at
-`parse.ts:38`.
-
-### 4. `packages/opencode-agent-skills-md/src/host.ts:97` — catch in `getSessionContext`
-
-```ts
-      } catch {
-        // Fall through to undefined - mirrors the legacy behaviour
-      }
-```
-
-If the session lookup fails, the error is swallowed. This is important for
-privacy (session data should not leak in error messages), but a debug log
-is safe.
-
-Excluded by design:
-- `walk.ts:100-103` per-entry isolation is documented as intentional.
-- `parse.ts:25-26` YAML fallback to `{}` is documented as intentional.
-- `discovery.ts:165-168` duplicate skill handling is documented as intentional.
-
-Conventions:
-- `debugLog` is imported in `discovery.ts` (not yet, but `parse.ts` imports it)
-- The import is `import { debugLog } from "./debug"` from `packages/core/src/`
-
-## Commands you will need
-
-| Purpose   | Command                  | Expected on success |
-|-----------|--------------------------|---------------------|
-| Typecheck | `pnpm run typecheck`     | exit 0, no errors   |
-| Tests     | `pnpm test`              | all pass            |
-
-## Scope
-
-**In scope** (the only files you should modify):
-- `packages/core/src/discovery.ts` — add `debugLog` import and calls in catch blocks
-- `packages/core/src/parse.ts` — add `debugLog` to the `readFile` catch at line 91
-- `packages/opencode-agent-skills-md/src/host.ts` — add `debugLog` to the `getSessionContext` catch at line 97
-
-**Out of scope** (do NOT touch):
-- `walk.ts` — per-entry isolation is by-design
-- `parse.ts` YAML error handling — already logs via `debugLog`
-- `packages/core/src/scripts.ts` — catches there are intentional
-- Any test files — the existing tests must pass unchanged
-
-## Git workflow
-
-- Branch: `advisor/005-stop-swallowing-errors`
-- Commit per file (or single commit for all three)
-- Do NOT push or open a PR unless instructed.
-
-## Steps
-
-### Step 1: Add `debugLog` imports where missing
-
-Check which files already import `debugLog`:
-
-- `packages/core/src/discovery.ts` — does NOT import `debugLog`. Add:
-  ```ts
-  import { debugLog } from "./debug";
-  ```
-
-- `packages/core/src/parse.ts` — ALREADY imports `debugLog` at line 12. No change needed.
-
-- `packages/opencode-agent-skills-md/src/host.ts` — does NOT import `debugLog`. Add:
-  ```ts
-  import { debugLog } from "opencode-agent-skills-md-core";
-  ```
-
-### Step 2: Add `debugLog` to `findSkillsRecursive` catch in `discovery.ts:87`
-
-Old:
-```ts
-  } catch { }
-```
-
-New:
-```ts
-  } catch (error) {
-    debugLog("findSkillsRecursive: cannot access baseDir", baseDir, error);
-  }
-```
-
-**Verify**: `grep -A2 'debugLog.*findSkillsRecursive' packages/core/src/discovery.ts` → matches
-
-### Step 3: Add `debugLog` to `listSkillFiles` stat error in `discovery.ts:219`
-
-Old:
-```ts
-        } catch { }
-```
-
-New:
-```ts
-        } catch (error) {
-          debugLog("listSkillFiles: cannot stat", fullPath, error);
-        }
-```
-
-**Verify**: `grep -A2 'debugLog.*listSkillFiles' packages/core/src/discovery.ts` → matches
-
-### Step 4: Add `debugLog` to `parseSkillFile` file read in `parse.ts:91`
-
-Old:
-```ts
-const content = await fs.readFile(skillPath, 'utf-8').catch(() => null);
-```
-
-New:
-```ts
-const content = await fs.readFile(skillPath, 'utf-8').catch((error) => {
-  debugLog("parseSkillFile: cannot read", skillPath, error);
-  return null;
-});
-```
-
-**Verify**: `grep -A3 'parseSkillFile.*cannot read' packages/core/src/parse.ts` → matches
-
-### Step 5: Add `debugLog` to `getSessionContext` catch in `host.ts:97`
-
-Old:
-```ts
-      } catch {
-        // Fall through to undefined - mirrors the legacy behaviour
-      }
-```
-
-New:
-```ts
-      } catch (error) {
-        debugLog("getSessionContext: session lookup failed", sessionID, error);
-        // Fall through to undefined - mirrors the legacy behaviour
-      }
-```
-
-**Verify**: `grep 'debugLog.*getSessionContext' packages/opencode-agent-skills-md/src/host.ts` → matches
-
-### Step 6: Typecheck
-
-**Verify**: `pnpm run typecheck` → exit 0, no errors
-
-### Step 7: Run tests
-
-**Verify**: `pnpm test` → exit 0, all tests pass
-
-## Test plan
-
-No new tests needed — the `debugLog` function is gated behind
-`OPENCODE_AGENT_SKILLS_DEBUG` and has no side effects when not set.
-Existing tests that exercise the error paths will continue to pass
-(same behavior) but will now log when the env var is set.
-
-To manually verify, run with debug logging:
-```bash
-OPENCODE_AGENT_SKILLS_DEBUG=true pnpm test 2>&1 | grep '\[opencode-agent-skills-md\]'
-```
-
-## Done criteria
-
-Machine-checkable. ALL must hold:
-
-- [ ] `packages/core/src/discovery.ts` imports `debugLog` and calls it in both catch blocks with context
-- [ ] `packages/core/src/parse.ts` logs via `debugLog` when `readFile` fails for a SKILL.md
-- [ ] `packages/opencode-agent-skills-md/src/host.ts` imports `debugLog` and calls it in the `getSessionContext` catch
-- [ ] `pnpm run typecheck` exits 0
-- [ ] `pnpm test` exits 0
-- [ ] No files outside the in-scope list are modified (`git status`)
-- [ ] `plans/README.md` status row updated
-
-## STOP conditions
-
-Stop and report back (do not improvise) if:
-
-- The import path for `debugLog` differs between the core and plugin packages (it does: core uses `"./debug"`, plugin uses `"opencode-agent-skills-md-core"`).
-- A step's verification fails twice after a reasonable fix attempt.
-- The fix appears to require touching an out-of-scope file.
-- Adding `error` to the log output leaks any sensitive information (in `host.ts`, the `error` may contain session data — log only the error type, not the full error object).
-
-## Maintenance notes
-
-- If a more structured logging system replaces `debugLog` in the future,
-  these catch blocks will emit through the new system automatically.
-- The `host.ts` catch in `getSessionContext` should avoid logging the full
-  error object if it might contain session payload data. If unsure, log
-  only `(error as Error).name` and `(error as Error).message`.

package/plans/006-preserve-jsonc-commas.md

@@ -1,144 +0,0 @@
-# Plan 006: Preserve commas inside JSONC string values
-
-> **Executor instructions**: Follow this plan step by step. Run every
-> verification command before moving on. If a STOP condition occurs, stop
-> and report instead of improvising. When done, update the status row for
-> this plan in `plans/README.md`.
->
-> **Drift check (run first)**:
-> `git diff --stat 9c57cb0..HEAD -- packages/opencode-agent-skills-md/src/cli/config.ts packages/opencode-agent-skills-md/tests/cli-commands.test.ts`
-> If any in-scope file changed since this plan was written, compare the
-> Current state excerpts below against live code first. Any mismatch is a
-> STOP condition.
-
-## Status
-
-- **Priority**: P1
-- **Effort**: S
-- **Risk**: LOW
-- **Depends on**: none
-- **Category**: bug
-- **Planned at**: commit `9c57cb0`, 2026-07-03
-
-## Why this matters
-
-`parseJsonc()` currently strips trailing commas with a regex applied to the
-entire post-comment text. That regex does not respect string boundaries, so a
-valid string value containing `,}` or `,]` is silently mutated before
-`JSON.parse()` runs. This is a real data-corruption bug in the CLI config
-loader, and the fix is narrow.
-
-## Current state
-
-- `packages/opencode-agent-skills-md/src/cli/config.ts` — CLI config parsing helpers used by install, uninstall, status, and doctor.
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts` — existing characterization tests for `parseJsonc()` and other CLI helpers.
-
-Relevant excerpts:
-
-- `packages/opencode-agent-skills-md/src/cli/config.ts:204-255`
-  - `stripJsoncComments()` already tracks `inString` and `escaped` while removing comments.
-  - It ends with: `return out.replace(/,(\s*[}\]])/g, "$1");`
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts:272-319`
-  - Existing tests cover empty input, comments, escaped quotes, and ordinary trailing commas.
-  - There is no test proving commas inside string literals survive unchanged.
-
-Conventions to match:
-
-- CLI helper tests live in `packages/opencode-agent-skills-md/tests/cli-commands.test.ts`.
-- Keep the implementation minimal and local; do not introduce a new parser dependency.
-- Preserve the current graceful behavior: comments are stripped, trailing commas still work, malformed JSON still throws.
-
-## Commands you will need
-
-| Purpose | Command | Expected on success |
-|---|---|---|
-| Typecheck | `pnpm run typecheck` | exit 0 |
-| Targeted tests | `pnpm -F opencode-agent-skills-md exec node --import tsx --test tests/cli-commands.test.ts` | all pass |
-| Full tests | `pnpm test` | all pass |
-
-## Scope
-
-**In scope** (the only files you should modify):
-- `packages/opencode-agent-skills-md/src/cli/config.ts`
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts`
-
-**Out of scope**:
-- Any CLI command behavior beyond config parsing correctness
-- Any release workflow or docs change
-- Any new dependency
-
-## Git workflow
-
-- Branch: `advisor/006-preserve-jsonc-commas`
-- Commit style: conventional commits, for example `fix(cli): preserve commas inside JSONC strings`
-- Do NOT push or open a PR unless instructed
-
-## Steps
-
-### Step 1: Add a failing regression test for string-preservation
-
-Extend `describe("parseJsonc", ...)` in `packages/opencode-agent-skills-md/tests/cli-commands.test.ts`.
-
-Add at least these cases:
-
-- A string containing `,}` such as `{"doc":"keep ,} inside string","plugin":["a",],}`
-- A string containing `,]` such as `{"doc":"keep ,] inside string","list":[1,2,],}`
-- A nested mixed case with both string patterns and structural trailing commas
-
-The assertions must prove both:
-- trailing commas are still removed structurally
-- string content is unchanged byte-for-byte
-
-**Verify**: `pnpm -F opencode-agent-skills-md exec node --import tsx --test tests/cli-commands.test.ts` → the new test fails before the fix
-
-### Step 2: Replace regex-based trailing-comma stripping with a string-aware pass
-
-Modify `stripJsoncComments()` in `packages/opencode-agent-skills-md/src/cli/config.ts`.
-
-Target shape:
-
-- Keep the existing comment-stripping loop
-- Replace the final regex with a second character-by-character pass (or fold it inline)
-- Track `inString` and `escaped` state
-- Remove commas only when the next non-whitespace token is `}` or `]` and the parser is not inside a string literal
-
-Do not change `parseJsonc()` public behavior.
-
-**Verify**: `pnpm -F opencode-agent-skills-md exec node --import tsx --test tests/cli-commands.test.ts` → all tests pass
-
-### Step 3: Run repo verification
-
-**Verify**:
-- `pnpm run typecheck` → exit 0
-- `pnpm test` → exit 0
-- `git status --short` → only the two in-scope files plus `plans/README.md`
-
-## Test plan
-
-Extend `packages/opencode-agent-skills-md/tests/cli-commands.test.ts` inside the existing `describe("parseJsonc", ...)`. Model new cases after the existing block at lines 272-319. Cover:
-- happy path trailing comma removal still works
-- regression: `,}` inside a string is preserved
-- regression: `,]` inside a string is preserved
-- nested mixed case with both strings and structural trailing commas
-
-## Done criteria
-
-- [ ] `parseJsonc()` preserves commas inside string literals
-- [ ] Existing trailing-comma behavior still works
-- [ ] `pnpm run typecheck` exits 0
-- [ ] `pnpm test` exits 0
-- [ ] No files outside scope are modified
-- [ ] `plans/README.md` status row updated
-
-## STOP conditions
-
-Stop and report back (do not improvise) if:
-- The `parseJsonc` implementation no longer ends in a regex-based trailing comma removal step.
-- Fixing the bug appears to require a new parser dependency.
-- The regression test cannot be made to fail before the implementation change.
-- Verification fails twice after a reasonable fix attempt.
-
-## Maintenance notes
-
-- Keep this logic near `stripJsoncComments()`; splitting into many helpers is unnecessary unless the function becomes unreadable.
-- Future changes to config parsing should always add regression tests for string-boundary handling.

package/plans/007-write-before-purge.md

@@ -1,144 +0,0 @@
-# Plan 007: Write config before purging plugin-owned directories
-
-> **Executor instructions**: Follow this plan step by step. Run every
-> verification command before moving on. If a STOP condition occurs, stop
-> and report instead of improvising. When done, update the status row for
-> this plan in `plans/README.md`.
->
-> **Drift check (run first)**:
-> `git diff --stat 9c57cb0..HEAD -- packages/opencode-agent-skills-md/src/cli/uninstall.ts packages/opencode-agent-skills-md/tests/cli-commands.test.ts`
-> If any in-scope file changed since this plan was written, compare the
-> Current state excerpts below against live code first. Any mismatch is a
-> STOP condition.
-
-## Status
-
-- **Priority**: P1
-- **Effort**: S
-- **Risk**: LOW
-- **Depends on**: none
-- **Category**: bug
-- **Planned at**: commit `9c57cb0`, 2026-07-03
-
-## Why this matters
-
-`runUninstall({ purge: true })` currently deletes the plugin cache/config
-directories before it attempts the config write. If the later write fails, the
-global OpenCode config can still claim the plugin is installed while the
-plugin-owned directories are already gone. The bug is about operation ordering.
-
-## Current state
-
-- `packages/opencode-agent-skills-md/src/cli/uninstall.ts` — uninstall command implementation
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts` — existing uninstall coverage with in-memory `CliFs`
-
-Relevant excerpts:
-
-- `packages/opencode-agent-skills-md/src/cli/uninstall.ts:98-110`
-  - purge candidates are computed and, for real `--purge`, deleted before the no-op/write path
-- `packages/opencode-agent-skills-md/src/cli/uninstall.ts:145-149`
-  - config backup and `writeAtomically()` happen later
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts:1048-1065`
-  - existing `--purge (real)` test only asserts the command returns `wrote`; there is no regression test for a config-write failure after purge begins
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts:70-156`
-  - `createMemoryFs()` supports failure injection for `write` and `rename`
-
-Conventions to match:
-
-- Keep `purgeDir()` best-effort
-- Preserve `--dry-run` output and current return shapes
-- Reorder operations instead of adding rollback machinery
-
-## Commands you will need
-
-| Purpose | Command | Expected on success |
-|---|---|---|
-| Typecheck | `pnpm run typecheck` | exit 0 |
-| Targeted tests | `pnpm -F opencode-agent-skills-md exec node --import tsx --test tests/cli-commands.test.ts` | all pass |
-| Full tests | `pnpm test` | all pass |
-
-## Scope
-
-**In scope** (the only files you should modify):
-- `packages/opencode-agent-skills-md/src/cli/uninstall.ts`
-- `packages/opencode-agent-skills-md/tests/cli-commands.test.ts`
-
-**Out of scope**:
-- Install command behavior
-- Purge path redesign or rollback framework
-- Any changes to `CliFs` shape
-
-## Git workflow
-
-- Branch: `advisor/007-write-before-purge`
-- Commit style: conventional commits, for example `fix(cli): write uninstall config before purge`
-- Do NOT push or open a PR unless instructed
-
-## Steps
-
-### Step 1: Add a regression test for write-failure ordering
-
-Extend `describe("runUninstall", ...)` in `packages/opencode-agent-skills-md/tests/cli-commands.test.ts`.
-
-Add a test that:
-
-- starts with a config containing the plugin entry
-- injects a write or rename failure via `setFailNext()`
-- calls `runUninstall({ purge: true }, ...)`
-- asserts the thrown error propagates
-- asserts the original config file content is unchanged
-
-Because the purge path uses `node:fs.rmSync` directly, do not assert real directory deletion in the in-memory FS. The point is to pin that the config write must be attempted before purge side effects happen.
-
-**Verify**: `pnpm -F opencode-agent-skills-md exec node --import tsx --test tests/cli-commands.test.ts` → the new test fails before the reorder
-
-### Step 2: Reorder `runUninstall()` side effects
-
-Modify `packages/opencode-agent-skills-md/src/cli/uninstall.ts`.
-
-Target shape:
-
-- Keep dry-run planning unchanged
-- Keep no-op handling unchanged
-- Build the post-uninstall config object as today
-- If config removal is needed, do backup + atomic write first
-- Only after a successful write, perform best-effort purge of plugin-owned dirs
-
-Do not add fallback writes, retries, or rollback code.
-
-**Verify**: `pnpm -F opencode-agent-skills-md exec node --import tsx --test tests/cli-commands.test.ts` → all tests pass
-
-### Step 3: Run repo verification
-
-**Verify**:
-- `pnpm run typecheck` → exit 0
-- `pnpm test` → exit 0
-- `git status --short` → only the two in-scope files plus `plans/README.md`
-
-## Test plan
-
-Extend `packages/opencode-agent-skills-md/tests/cli-commands.test.ts`. Model after existing uninstall tests and the existing write-failure helpers. Cover:
-- regression: `purge: true` plus write failure leaves config unchanged
-- existing `--dry-run` and success paths remain green
-
-## Done criteria
-
-- [ ] `runUninstall()` writes config before purging
-- [ ] Write failure leaves the config intact
-- [ ] `pnpm run typecheck` exits 0
-- [ ] `pnpm test` exits 0
-- [ ] No files outside scope are modified
-- [ ] `plans/README.md` status row updated
-
-## STOP conditions
-
-Stop and report back (do not improvise) if:
-- `runUninstall()` no longer has a distinct write phase and purge phase.
-- The regression requires changing `CliFs` or adding a purge abstraction.
-- The fix appears to require changing public return types or console output format.
-- Verification fails twice after a reasonable fix attempt.
-
-## Maintenance notes
-
-- Purge remains best-effort by design; the important invariant is that config state is committed first.
-- If uninstall ever gains transactional semantics later, revisit install/uninstall symmetry together rather than expanding this fix.

package/plans/008-reuse-walkdir-for-list-skill-files.md

@@ -1,164 +0,0 @@
-# Plan 008: Reuse the shared walker in `listSkillFiles`
-
-> **Executor instructions**: Follow this plan step by step. Run every
-> verification command before moving on. If a STOP condition occurs, stop
-> and report instead of improvising. When done, update the status row for
-> this plan in `plans/README.md`.
->
-> **Drift check (run first)**:
-> `git diff --stat 9c57cb0..HEAD -- packages/core/src/discovery.ts packages/core/src/walk.ts packages/core/tests/discovery.test.ts`
-> If any in-scope file changed since this plan was written, compare the
-> Current state excerpts below against live code first. Any mismatch is a
-> STOP condition.
-
-## Status
-
-- **Priority**: P2
-- **Effort**: S
-- **Risk**: LOW
-- **Depends on**: none
-- **Category**: tech-debt
-- **Planned at**: commit `9c57cb0`, 2026-07-03
-
-## Why this matters
-
-`listSkillFiles()` reimplements recursive traversal instead of using the shared
-`walkDir()` utility that already defines the repo's skip rules and
-error-isolation behavior. That duplication means `listSkillFiles()` can descend
-into hidden directories, `.git`, and `node_modules`, and it pays an extra
-`stat()` per entry. The fix is a small consolidation onto the existing
-abstraction.
-
-## Current state
-
-- `packages/core/src/discovery.ts` — skill discovery helpers, including `listSkillFiles()`
-- `packages/core/src/walk.ts` — shared recursive walker already used by `findSkillsRecursive()` and `findScripts()`
-- `packages/core/tests/discovery.test.ts` — existing walker/discovery tests; no direct `listSkillFiles()` coverage
-
-Relevant excerpts:
-
-- `packages/core/src/discovery.ts:202-233`
-  - `listSkillFiles()` uses a private `recurse()` function
-  - calls `fs.readdir(..., { withFileTypes: true })`
-  - then immediately calls `fs.stat(fullPath)` for every entry
-  - does not apply `walkDir()` skip rules
-- `packages/core/src/walk.ts:4-16`
-  - `walkDir()` owns shared traversal rules: hidden dirs, `node_modules`, `.git` are skipped
-  - per-entry failures are isolated
-- `packages/core/tests/discovery.test.ts:82-161`
-  - direct tests already pin `walkDir()` skip behavior
-- `packages/core/tests/discovery.test.ts:163-252`
-  - `findSkillsRecursive()` already proves the walker-based pattern
-
-Conventions to match:
-
-- Keep the core package host-agnostic and dependency-free
-- Prefer the smallest correct refactor
-- Preserve sorted output and graceful handling of missing directories
-
-## Commands you will need
-
-| Purpose | Command | Expected on success |
-|---|---|---|
-| Typecheck | `pnpm run typecheck` | exit 0 |
-| Targeted tests | `pnpm -F opencode-agent-skills-md-core exec node --import tsx --test tests/discovery.test.ts` | all pass |
-| Full tests | `pnpm test` | all pass |
-
-## Scope
-
-**In scope** (the only files you should modify):
-- `packages/core/src/discovery.ts`
-- `packages/core/tests/discovery.test.ts`
-
-**Out of scope**:
-- `packages/core/src/walk.ts` behavior changes
-- `findScripts()` performance cleanup
-- Plugin package source changes
-
-## Git workflow
-
-- Branch: `advisor/008-reuse-walkdir-for-list-skill-files`
-- Commit style: conventional commits, for example `refactor(core): reuse walkDir in listSkillFiles`
-- Do NOT push or open a PR unless instructed
-
-## Steps
-
-### Step 1: Add direct characterization tests for `listSkillFiles()`
-
-Extend `packages/core/tests/discovery.test.ts` with a dedicated `describe("listSkillFiles", ...)`.
-
-Build a temp skill tree that includes:
-- `SKILL.md`
-- visible nested files that should be returned
-- `.hidden/`
-- `node_modules/`
-- `.git/`
-- a nested depth boundary case
-
-Assert:
-- `SKILL.md` is excluded
-- visible files are returned as sorted relative paths
-- hidden, `.git`, and `node_modules` contents are not returned
-- missing base directory returns `[]`
-
-Model setup style after the existing `walkDir` and `findSkillsRecursive` tests.
-
-**Verify**: `pnpm -F opencode-agent-skills-md-core exec node --import tsx --test tests/discovery.test.ts` → the new tests fail before the refactor
-
-### Step 2: Rewrite `listSkillFiles()` onto `walkDir()`
-
-Modify `packages/core/src/discovery.ts`.
-
-Target shape:
-
-- import and reuse `walkDir()` instead of the bespoke `recurse()` implementation
-- in the visitor:
-  - ignore directories
-  - ignore `SKILL.md`
-  - compute relative paths from `skillPath`
-  - push file paths only for visible files the walker surfaces
-- keep sorted return order
-- preserve graceful behavior when `skillPath` does not exist
-
-Do not change other discovery helpers in this plan.
-
-**Verify**: `pnpm -F opencode-agent-skills-md-core exec node --import tsx --test tests/discovery.test.ts` → all tests pass
-
-### Step 3: Run repo verification
-
-**Verify**:
-- `pnpm run typecheck` → exit 0
-- `pnpm test` → exit 0
-- `git status --short` → only the two in-scope files plus `plans/README.md`
-
-## Test plan
-
-Extend `packages/core/tests/discovery.test.ts`. Reuse the same temp-directory style already used by `walkDir` / `findSkillsRecursive`. Cover:
-- sorted visible file listing
-- exclusion of `SKILL.md`
-- exclusion of hidden, `.git`, and `node_modules`
-- missing directory returns `[]`
-- maxDepth still limits traversal
-
-## Done criteria
-
-- [ ] `listSkillFiles()` reuses `walkDir()`
-- [ ] `listSkillFiles()` no longer has custom recursive traversal
-- [ ] Direct tests cover skip rules and `SKILL.md` exclusion
-- [ ] `pnpm run typecheck` exits 0
-- [ ] `pnpm test` exits 0
-- [ ] No files outside scope are modified
-- [ ] `plans/README.md` status row updated
-
-## STOP conditions
-
-Stop and report back (do not improvise) if:
-- `listSkillFiles()` has already been moved out of `discovery.ts`
-- Reusing `walkDir()` would require changing `walkDir()` semantics
-- The characterization tests cannot be made to fail before the refactor
-- Verification fails twice after a reasonable fix attempt.
-
-## Maintenance notes
-
-- If `findScripts()` later gets the same consolidation or perf cleanup, do that as a separate plan.
-- Keep `walkDir()` as the single source of truth for shared traversal rules; avoid reintroducing bespoke recursion.