dsh-claude-compat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 biedongbin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/dsh-plugin-blue?style=for-the-badge" alt="DSH Plugin">
+</p>
+
+<h1 align="center">dsh-claude-compat</h1>
+
+<p align="center">
+  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/🌐_简体中文-点我阅读中文-red?style=for-the-badge" alt="简体中文"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/node-%3E%3D20-green?style=flat-square&logo=node.js&logoColor=white" alt="Node">
+  <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
+</p>
+
+<p align="center">DeepSeek Harness plugin that bridges Claude Code's <code>.claude/</code> directory into DSH natively — reuse your skills, slash commands, and rules with zero migration.</p>
+
+## What it does
+
+| `.claude/` path | Mechanism | Behavior |
+|---|---|---|
+| `skills/**/SKILL.md` | DSH skill provider | Name + description in the model-visible catalog; body loads on demand via the `skill` tool. New skills appear on the next catalog reconcile — no restart. |
+| `commands/*.md` | DSH skill provider | Same, plus user-invocable: `/command-name` works in the slash menu. |
+| `rules/*.md` | Message-stream injection | Rules are concatenated, wrapped in a `<system-reminder>` envelope, and prepended as a user-role message at the front of the message array once per session — the same channel Claude Code uses (`prependUserContext`), which models follow reliably. |
+
+`CLAUDE.md` / `AGENTS.md` are **not** touched — DSH's built-in `dsh-agent-instructions` already handles those.
+
+## Requirements
+
+- DSH with a profile (e.g. `web`)
+- A project using Claude Code conventions: `.claude/skills/`, `.claude/commands/`, `.claude/rules/`
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-claude-compat
+```
+
+Or from GitHub:
+
+```bash
+dsh plugin --profile web add github:biedongbin/dsh-claude-compat
+```
+
+Then register it in `~/.dsh/profiles/web/cordis.patch.yml` (merge into your existing patch list):
+
+```yaml
+- insert:
+    - id: claude-compat
+      name: 'dsh-claude-compat'
+      config:
+        enableSkills: true
+        enableRules: true
+```
+
+Restart DSH (`dsh web`). Done — skills show up in `/`, rules are injected into every new session.
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `enableSkills` | `true` | Register the `.claude/skills` + `.claude/commands` provider |
+| `enableRules` | `true` | Inject `.claude/rules/*.md` into the message stream |
+| `rulesMaxBytes` | `65536` | Hard cap on total injected rules text |
+| `projectRootMarkers` | `[".git"]` | Ancestor markers for project-root discovery |
+| `skillRank` | `150` | Provider rank: between DSH-native `.dsh/skills` (100) and `.agents/skills` (200) — DSH-native wins conflicts |
+| `skillSource` | `project-claude` | Source tag for catalog entries |
+
+## Notes
+
+- **Skill naming**: DSH requires kebab-case skill names. Nested skill directories are flattened (`gitnexus/gitnexus-guide` → `gitnexus-gitnexus-guide`); invalid frontmatter names fall back to the directory name.
+- **Rules granularity**: rules are read per new session (cached per session cwd). Editing a rule mid-session takes effect in the next session.
+- **Rules content**: rules are injected verbatim as instructions to the model. Only commit rules you want the model to follow — same trust level as `CLAUDE.md`.
+
+## Acknowledgments
+
+- [Linux.do](https://linux.do) — community
+- [Claude Code](https://claude.com/claude-code) — the `.claude/` conventions this plugin bridges
+- [DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh) — the runtime this plugin extends
+
+## License
+
+[MIT](LICENSE)
+
+## ⭐ Star History
+
+If this project helps you, please give it a ⭐ — it motivates us to keep improving.
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/biedongbin/dsh-claude-compat?style=for-the-badge&logo=github&color=gold" alt="GitHub Stars">
+  <img src="https://img.shields.io/github/forks/biedongbin/dsh-claude-compat?style=for-the-badge&logo=github" alt="GitHub Forks">
+  <img src="https://img.shields.io/github/watchers/biedongbin/dsh-claude-compat?style=for-the-badge&logo=github" alt="GitHub Watchers">
+</p>
+
+<div align="center">
+  <a href="https://www.star-history.com/#biedongbin/dsh-claude-compat&Date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=biedongbin/dsh-claude-compat&type=Date&theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=biedongbin/dsh-claude-compat&type=Date" />
+      <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=biedongbin/dsh-claude-compat&type=Date" width="760" />
+    </picture>
+  </a>
+</div>

package/README.zh-CN.md

@@ -0,0 +1,104 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/dsh-插件-blue?style=for-the-badge" alt="DSH 插件">
+</p>
+
+<h1 align="center">dsh-claude-compat</h1>
+
+<p align="center">
+  <a href="README.md"><img src="https://img.shields.io/badge/🌐_English-Click_me-red?style=for-the-badge" alt="English"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/node-%3E%3D20-green?style=flat-square&logo=node.js&logoColor=white" alt="Node">
+  <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
+</p>
+
+<p align="center">DeepSeek Harness 插件：把 Claude Code 的 <code>.claude/</code> 目录原生桥接进 DSH —— skills、斜杠命令、rules 零迁移直接复用。</p>
+
+## 功能
+
+| `.claude/` 路径 | 机制 | 行为 |
+|---|---|---|
+| `skills/**/SKILL.md` | DSH skill provider | 仅 name + description 进模型可见目录；正文按需加载（`skill` 工具）。新增 skill 下次 catalog 刷新即出现，无需重启。 |
+| `commands/*.md` | DSH skill provider | 同上，且用户可直接调用：斜杠菜单里 `/command-name` 可用。 |
+| `rules/*.md` | 消息流注入 | rules 全文拼接，包 `<system-reminder>` 信封，每会话一次以 user-role 消息插在消息数组最前 —— 与 Claude Code 同通道（`prependUserContext`），模型可靠遵循。 |
+
+`CLAUDE.md` / `AGENTS.md` **不碰** —— DSH 内置 `dsh-agent-instructions` 已处理。
+
+## 环境要求
+
+- DSH 及其 profile（如 `web`）
+- 使用 Claude Code 约定的项目：`.claude/skills/`、`.claude/commands/`、`.claude/rules/`
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-claude-compat
+```
+
+或从 GitHub：
+
+```bash
+dsh plugin --profile web add github:biedongbin/dsh-claude-compat
+```
+
+然后在 `~/.dsh/profiles/web/cordis.patch.yml` 注册（合并进现有 patch 列表）：
+
+```yaml
+- insert:
+    - id: claude-compat
+      name: 'dsh-claude-compat'
+      config:
+        enableSkills: true
+        enableRules: true
+```
+
+重启 DSH（`dsh web`）。完成 —— skills 出现在 `/` 菜单，rules 注入每个新会话。
+
+## 配置
+
+| 选项 | 默认值 | 说明 |
+|---|---|---|
+| `enableSkills` | `true` | 注册 `.claude/skills` + `.claude/commands` provider |
+| `enableRules` | `true` | 注入 `.claude/rules/*.md` 到消息流 |
+| `rulesMaxBytes` | `65536` | 注入 rules 总量硬上限 |
+| `projectRootMarkers` | `[".git"]` | 项目根发现的祖先标记 |
+| `skillRank` | `150` | provider 排名：介于 DSH 原生 `.dsh/skills`（100）与 `.agents/skills`（200）之间 —— 冲突时 DSH 原生优先 |
+| `skillSource` | `project-claude` | catalog 条目来源标签 |
+
+## 说明
+
+- **Skill 命名**：DSH 要求 kebab-case。嵌套 skill 目录扁平化（`gitnexus/gitnexus-guide` → `gitnexus-gitnexus-guide`）；frontmatter 名字非法时回退目录名。
+- **Rules 粒度**：每个新会话读取（按会话 cwd 缓存）。会话中改 rule，下一会话生效。
+- **Rules 内容**：rules 原文注入为模型指令。只提交你想让模型遵循的 rule —— 信任级别同 `CLAUDE.md`。
+
+## 社区鸣谢
+
+- [Linux.do](https://linux.do) —— 社区
+- [Claude Code](https://claude.com/claude-code) —— 本插件桥接的 `.claude/` 约定
+- [DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh) —— 本插件扩展的运行时
+
+## License
+
+[MIT](LICENSE)
+
+## ⭐ Star History
+
+如果这个项目对你有帮助，请给个 ⭐ —— 这是我们持续改进的动力。
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/biedongbin/dsh-claude-compat?style=for-the-badge&logo=github&color=gold" alt="GitHub Stars">
+  <img src="https://img.shields.io/github/forks/biedongbin/dsh-claude-compat?style=for-the-badge&logo=github" alt="GitHub Forks">
+  <img src="https://img.shields.io/github/watchers/biedongbin/dsh-claude-compat?style=for-the-badge&logo=github" alt="GitHub Watchers">
+</p>
+
+<div align="center">
+  <a href="https://www.star-history.com/#biedongbin/dsh-claude-compat&Date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=biedongbin/dsh-claude-compat&type=Date&theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=biedongbin/dsh-claude-compat&type=Date" />
+      <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=biedongbin/dsh-claude-compat&type=Date" width="760" />
+    </picture>
+  </a>
+</div>

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "dsh-claude-compat",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness plugin: bridge Claude Code's .claude/ directory (skills, commands, rules) into DSH native skill registry and message-stream rules injection.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "claude-code",
+    "claude",
+    "skills",
+    "slash-commands",
+    "rules"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-skill": "*",
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": { "optional": true },
+    "@deepseek-ai/dsh-skill": { "optional": true },
+    "@deepseek-ai/dsh-llm": { "optional": true },
+    "@deepseek-ai/schemastery": { "optional": true }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.js

@@ -0,0 +1,380 @@
+// dsh-claude-compat — bridge Claude Code's .claude/ into DSH.
+//
+// Two contributions to the live runtime:
+//   1. Skill provider on ctx.skills — scans <projectRoot>/.claude/skills/**/SKILL.md
+//      and <projectRoot>/.claude/commands/*.md, surfaces them as DSH skills so the
+//      `/skill-name` slash trigger, the `skill` tool, and the model-visible catalog
+//      pick them up natively. Only name+description load at discovery; the body
+//      loads on demand — same contract as the shipped filesystem provider.
+//   2. System prompt section — injects <projectRoot>/.claude/rules/*.md as ordered
+//      guidance. CLAUDE.md / AGENTS.md are already handled by dsh-agent-instructions,
+//      so we do NOT re-inject them here.
+//
+// Skill name flattening: .claude/skills/gitnexus/gitnexus-guide/SKILL.md →
+// "gitnexus-gitnexus-guide" (DSH skill names must be kebab-case; the shipped
+// provider is one-level only, we recurse up to 3 and join segments with '-').
+//
+// Commands: .claude/commands/commit-changes.md → skill "commit-changes",
+// user-invocable forced true so `/commit-changes` works in the slash menu.
+//
+// Rules text is re-read every system-prompt assembly (per model step), so rule
+// edits take effect without a DSH restart. No file watcher — the cost of
+// stat'ing a handful of small markdown files is negligible per step.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { parse } from 'yaml';
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+
+export const name = 'claude-compat';
+export const inject = ['skills'];
+
+export const Config = z.object({
+  projectRootMarkers: z.array(z.string()).default(['.git']),
+  // 150: between project-dsh (100) and project-agents (200). DSH-native skills
+  // win over Claude skills; Claude skills win over user-level.
+  skillRank: z.number().default(150),
+  skillSource: z.string().default('project-claude'),
+  rulesMaxBytes: z.number().default(65536),
+  enableRules: z.boolean().default(true),
+  enableSkills: z.boolean().default(true),
+});
+
+export function apply(ctx, config = {}) {
+  if (config.enableSkills !== false) {
+    ctx.skills.registerProvider((control) =>
+      new ClaudeCompatSkillProvider(ctx, control, config));
+  }
+  if (config.enableRules !== false) {
+    registerRulesSection(ctx, config);
+  }
+}
+
+// ─── skill provider ──────────────────────────────────────────────────────────
+
+class ClaudeCompatSkillProvider {
+  constructor(ctx, control, config) {
+    this.ctx = ctx;
+    this.name = 'claude-compat';
+    this.config = config;
+    this.skillRank = config.skillRank ?? 150;
+    this.source = config.skillSource ?? 'project-claude';
+    control.signal.addEventListener('abort', () => {}, { once: true });
+  }
+
+  async list(options) {
+    const cwd = options?.cwd;
+    if (cwd === undefined || cwd === null) return [];
+    const projectRoot = await findProjectRoot(cwd, this.config.projectRootMarkers);
+    if (projectRoot === undefined) return [];
+    const claudeDir = join(projectRoot, '.claude');
+    if (!(await pathExists(claudeDir))) return [];
+
+    const candidates = [];
+    for (const c of await discoverSkills(join(claudeDir, 'skills'), this.name, this.source, this.skillRank)) {
+      candidates.push(c);
+    }
+    for (const c of await discoverCommands(join(claudeDir, 'commands'), this.name, this.source, this.skillRank)) {
+      candidates.push(c);
+    }
+    return candidates;
+  }
+
+  async get(candidate) {
+    const locator = candidate.locator;
+    const raw = await readTextSafe(locator.path);
+    if (raw === undefined) return undefined;
+    const parsed = parseFrontmatter(raw);
+    const content = parsed === undefined ? raw.trim() : parsed.body.trim();
+    return {
+      name: candidate.name,
+      description: candidate.description,
+      ...(candidate.whenToUse !== undefined ? { whenToUse: candidate.whenToUse } : {}),
+      invocation: candidate.invocation,
+      source: candidate.source,
+      provider: this.name,
+      resourceBase: { kind: 'directory', path: locator.directory },
+      path: locator.path,
+      content,
+    };
+  }
+}
+
+// ─── discovery: .claude/skills (recursive, ≤3 levels) ────────────────────────
+
+async function discoverSkills(rootDir, providerName, source, rank) {
+  const out = [];
+  if (!(await pathExists(rootDir))) return out;
+  await walk(rootDir, '', 0);
+  return out;
+
+  async function walk(dir, prefix, depth) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' });
+    } catch { return; }
+    if (entries.some(e => e.isFile() && e.name === 'SKILL.md')) {
+      const skillPath = join(dir, 'SKILL.md');
+      const c = await parseSkillCandidateFile(skillPath, providerName, source, rank, prefix || undefined);
+      if (c !== undefined) out.push(c);
+      return; // bundle — don't descend
+    }
+    if (depth >= 3) return;
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === '__pycache__') continue;
+      const childPrefix = prefix ? `${prefix}-${entry.name}` : entry.name;
+      await walk(join(dir, entry.name), childPrefix, depth + 1);
+    }
+  }
+}
+
+// ─── discovery: .claude/commands (flat) ──────────────────────────────────────
+
+async function discoverCommands(rootDir, providerName, source, rank) {
+  const out = [];
+  if (!(await pathExists(rootDir))) return out;
+  let entries;
+  try {
+    entries = await readdir(rootDir, { withFileTypes: true, encoding: 'utf8' });
+  } catch { return out; }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const path = join(rootDir, entry.name);
+    const stem = entry.name.slice(0, -3);
+    if (!isSkillName(stem)) continue; // non-kebab names rejected by registry anyway
+    const raw = await readTextSafe(path);
+    if (raw === undefined) continue;
+    const parsed = parseFrontmatter(raw);
+    const description = parsed === undefined ? stem : (stringField(parsed.data, 'description') ?? stem);
+    out.push({
+      name: stem,
+      description,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: providerName,
+      source,
+      rank,
+      locator: { path, directory: rootDir },
+      resourceBase: { kind: 'directory', path: rootDir },
+      path,
+    });
+  }
+  return out;
+}
+
+async function parseSkillCandidateFile(path, providerName, source, rank, flatName) {
+  const raw = await readTextSafe(path);
+  if (raw === undefined) return undefined;
+  const parsed = parseFrontmatter(raw);
+  if (parsed === undefined) return undefined;
+  const fmName = stringField(parsed.data, 'name');
+  const description = stringField(parsed.data, 'description');
+  if (description === undefined) return undefined;
+  // Prefer frontmatter name when it is a valid kebab-case skill name. Some Claude
+  // skills use names with ':' or other chars DSH rejects (e.g.
+  // "salus:ai-robot-coding-env-check"); for those, fall back to the flattened
+  // directory name, which is virtually always kebab-case.
+  let name;
+  if (fmName !== undefined && isSkillName(fmName)) name = fmName;
+  else if (flatName !== undefined && isSkillName(flatName)) name = flatName;
+  if (name === undefined) return undefined;
+  let invocation;
+  try { invocation = parseInvocationPolicy(parsed.data); }
+  catch { invocation = { modelInvocable: true, userInvocable: true }; }
+  const whenToUse = stringField(parsed.data, 'whenToUse');
+  return {
+    name,
+    description,
+    ...(whenToUse !== undefined ? { whenToUse } : {}),
+    invocation,
+    provider: providerName,
+    source,
+    rank,
+    locator: { path, directory: dirname(path) },
+    resourceBase: { kind: 'directory', path: dirname(path) },
+    path,
+  };
+}
+
+// ─── rules section ───────────────────────────────────────────────────────────
+
+function registerRulesSection(ctx, config) {
+  const maxBytes = config.rulesMaxBytes ?? 65536;
+  // Cache built messages per session cwd — building reads ~13 files, and
+  // pre-step fires every step.
+  const cache = new Map();
+  ctx.on('agent/pre-step', async ({ agent, messages }, next) => {
+    const decision = await next();
+    if (decision.kind !== 'enter') return decision;
+    const present = (list) => list.some((m) => m?.source?.kind === 'claude-compat');
+    const alreadyInjected = present(messages)
+      || present(decision.messages)
+      || agent.session.surface.nodes.some((seq) => {
+        const event = agent.session.events[seq];
+        return event?.type === 'user/message'
+          && event.data?.source?.kind === 'claude-compat';
+      });
+    if (alreadyInjected) return decision;
+    // Session cwd, NOT process.cwd() — the DSH process may be launched from
+    // anywhere (e.g. the profile dir); the workspace is per-session. Same
+    // source of truth as dsh-agent-instructions.
+    const cwd = agent.session.header?.cwd ?? process.cwd();
+    if (!cache.has(cwd)) {
+      const text = buildRulesText(cwd, config, maxBytes);
+      if (text.length === 0) return decision;
+      // Claude Code's mechanism (leaked source, api.ts prependUserContext):
+      // rules as ONE user-role <system-reminder> message at the very front
+      // of the message array. Not in system prompt.
+      cache.set(cwd, createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: 'claude-compat', form: 'rules' },
+      }));
+    }
+    return {
+      kind: 'enter',
+      messages: decision.messages.toSpliced(0, 0, cache.get(cwd)),
+    };
+  });
+}
+
+function buildRulesText(cwd, config, maxBytes) {
+  const projectRoot = findProjectRootSync(cwd, config.projectRootMarkers);
+  if (projectRoot === undefined) return '';
+  const rulesDir = join(projectRoot, '.claude', 'rules');
+  const files = listMdFilesSync(rulesDir);
+  if (files.length === 0) return '';
+  const parts = [];
+  let total = 0;
+  for (const f of files) {
+    let raw;
+    try { raw = readFileSync(f, 'utf8'); } catch { continue; }
+    const basename = f.split('/').pop();
+    const chunk = `## ${basename}\n\n${raw.trim()}\n`;
+    if (total + chunk.length > maxBytes) break;
+    parts.push(chunk);
+    total += chunk.length;
+  }
+  if (parts.length === 0) return '';
+  // Exact envelope Claude Code uses in prependUserContext (api.ts):
+  // user-role <system-reminder> with "# claudeMd" framing.
+  return `<system-reminder>
+As you answer the user's questions, you can use the following context:
+# claudeMd
+${parts.join('\n')}
+      </system-reminder>`;
+}
+
+function findProjectRootSync(cwd, markers = ['.git']) {
+  let current = resolve(cwd);
+  while (true) {
+    for (const marker of markers) {
+      if (existsSync(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function listMdFilesSync(dir) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return []; }
+  const files = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const p = join(dir, name);
+    try { if (statSync(p).isFile()) files.push(p); } catch {}
+  }
+  files.sort();
+  return files;
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+async function findProjectRoot(cwd, markers = ['.git']) {
+  let current = resolve(cwd);
+  while (true) {
+    for (const marker of markers) {
+      if (await pathExists(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+async function pathExists(path) {
+  try { await stat(path); return true; } catch { return false; }
+}
+
+async function readTextSafe(path) {
+  try { return await readFile(path, { encoding: 'utf8' }); }
+  catch { return undefined; }
+}
+
+async function listMdFiles(dir) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' }); }
+  catch { return []; }
+  const files = [];
+  for (const e of entries) {
+    if (e.isFile() && e.name.endsWith('.md')) files.push(join(dir, e.name));
+  }
+  files.sort();
+  return files;
+}
+
+function parseFrontmatter(raw) {
+  const firstLineEnd = raw.indexOf('\n');
+  if (firstLineEnd < 0) return undefined;
+  if (raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return undefined;
+  const start = firstLineEnd + 1;
+  const closing = findClosingFrontmatter(raw, start);
+  if (closing === undefined) return undefined;
+  let parsed;
+  try { parsed = parse(raw.slice(start, closing.start)); }
+  catch { return undefined; }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
+  return { data: parsed, body: raw.slice(closing.bodyStart) };
+}
+
+function findClosingFrontmatter(raw, start) {
+  let lineStart = start;
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf('\n', lineStart);
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 };
+    }
+    if (nextNewline < 0) return undefined;
+    lineStart = nextNewline + 1;
+  }
+  return undefined;
+}
+
+function stringField(data, key) {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+function parseInvocationPolicy(data) {
+  const miv = data['disable-model-invocation'];
+  const uiv = data['user-invocable'];
+  return {
+    modelInvocable: !truthy(miv),
+    userInvocable: uiv === undefined ? true : truthy(uiv),
+  };
+}
+
+function truthy(v) {
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'string') {
+    const s = v.toLowerCase();
+    return s === 'true' || s === 'yes' || s === 'on' || s === '1';
+  }
+  if (typeof v === 'number') return v !== 0;
+  return false;
+}