@nitra/cursor 1.36.0 → 1.38.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.38.0] - 2026-05-31
+
+### Added
+
+- worktree: кросплатформний CLI n-cursor worktree (add/remove/list/prune) — виконавець конвенції .worktrees/ з інвентарним файлом-описом; тонкий skill worktree; pure-doc правило worktree
+
+## [1.37.0] - 2026-05-31
+
+### Changed
+
+- skills: meta.json замість auto.md (+ worktree-прапорець з вшиванням у SKILL.md і забороною паралелі)
+
 ## [1.36.0] - 2026-05-31
 
 ### Added

package/README.md

@@ -68,6 +68,12 @@
 npx @nitra/cursor
 npx @nitra/cursor fix
 npx @nitra/cursor fix bun ga
+
+# Керування git-worktree (.worktrees/ + інвентарний файл-опис)
+npx @nitra/cursor worktree add <branch> "<опис>"
+npx @nitra/cursor worktree list
+npx @nitra/cursor worktree remove <branch> [--force]
+npx @nitra/cursor worktree prune
 ```
 
 Команда `check` запускає programmatic перевірки з каталогу `scripts/` пакету. Якщо в корені репозиторію вже є `.n-cursor.json`, перед перевірками виконується зчитування конфігу — зокрема додається або виправляється поле `$schema`, якщо воно відсутнє або не збігається з очікуваним URL.
@@ -114,7 +120,7 @@ npm/
 ```
 npm/rules/<id>/
 ├── <id>.mdc              # текст правила (після синку — .cursor/rules/n-<id>.mdc)
-├── auto.md               # умова автоактивації скілу (опційно)
+├── meta.json             # метадані скілу: auto (автоактивація) + worktree
 ├── js/                  # JS для `npx @nitra/cursor fix`
 │   └── <concern>/
 │       ├── check.mjs     # діагностика — повертає список violations

package/bin/n-cursor.js

@@ -88,6 +88,8 @@ import {
   RULE_MIGRATIONS
 } from '../scripts/auto-rules.mjs'
 import { detectAutoSkills } from '../scripts/auto-skills.mjs'
+import { readSkillMetaRaw } from '../scripts/lib/skill-meta.mjs'
+import { injectWorktreeNotice } from '../scripts/lib/worktree-notice.mjs'
 import { runPostToolUseFixCli } from '../scripts/post-tool-use-fix.mjs'
 import { discoverCheckRulesFromCursorRules } from '../scripts/lib/discover-check-rules-from-cursor.mjs'
 import { listRuleIds } from '../scripts/lib/list-rule-ids.mjs'
@@ -101,6 +103,7 @@ import { syncClaudeConfig } from '../scripts/sync-claude-config.mjs'
 import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
 import { runRenameYamlExtensionsCli } from './rename-yaml-extensions.mjs'
 import { runSkillsCli } from '../scripts/skills-cli.mjs'
+import { runWorktreeCli } from '../scripts/worktree-cli.mjs'
 import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
 import { runLintCli } from '../scripts/lib/run-lint-cli.mjs'
 import { formatTimingSummary } from '../scripts/lib/timing-summary.mjs'
@@ -762,10 +765,15 @@ async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
       process.stdout.write(`  ⬇  ${id} → ${SKILLS_DIR}/${destDirName} ... `)
       try {
         await mkdir(destDir, { recursive: true })
+        const meta = readSkillMetaRaw(srcDir)
+        const worktree = meta?.worktree === true
         const files = await readdir(srcDir)
         for (const file of files) {
-          if (file === 'auto.md') continue
-          const content = await readFile(join(srcDir, file), 'utf8')
+          if (file === 'meta.json') continue
+          let content = await readFile(join(srcDir, file), 'utf8')
+          if (file === 'SKILL.md') {
+            content = injectWorktreeNotice(content, worktree)
+          }
           await writeFile(join(destDir, file), content, 'utf8')
         }
         console.log(`✅`)
@@ -1518,6 +1526,11 @@ try {
 
       break
     }
+    case 'worktree': {
+      process.exitCode = await runWorktreeCli(args)
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1527,7 +1540,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/graphql/js/tooling.mjs

@@ -82,7 +82,9 @@ function checkExtensionsRecommendation(pass, fail, cwd) {
   const pathRel = '.vscode/extensions.json'
   const pathAbs = join(cwd, pathRel)
   if (!existsSync(pathAbs)) {
-    fail(`${pathRel} не існує — створи файл і додай у recommendations ${REQUIRED_GRAPHQL_VSCODE_EXTENSION} (graphql.mdc)`)
+    fail(
+      `${pathRel} не існує — створи файл і додай у recommendations ${REQUIRED_GRAPHQL_VSCODE_EXTENSION} (graphql.mdc)`
+    )
     return
   }
   const violations = runConftestBatch({

package/rules/npm-module/js/package_structure.mjs

@@ -422,7 +422,10 @@ async function collectPublishedFiles(filesField, cwd) {
     }
     if (!s.isDirectory()) continue
     await walkDir(fullPath, p => {
-      const rel = p.slice(npmRoot.length + 1).split(sep).join('/')
+      const rel = p
+        .slice(npmRoot.length + 1)
+        .split(sep)
+        .join('/')
       collected.add(rel)
     })
   }

package/rules/npm-module/js/skill_meta.mjs

@@ -0,0 +1,61 @@
+/**
+ * Перевірка метаданих скілів пакета `@nitra/cursor` (концерн правила npm-module).
+ *
+ * Кожен `npm/skills/<id>/` має містити валідний `meta.json`:
+ *  - `worktree` присутнє і boolean;
+ *  - `auto` (якщо присутнє) — розпізнане (`"завжди"` або непорожній масив рядків);
+ *  - залишковий `auto.md` заборонено (міграція на meta.json завершена).
+ *
+ * Концерн застосовний лише в репо самого пакета (де є `npm/skills/`); у споживача
+ * каталогу `npm/skills/` нема, тож перевірка мовчки проходить.
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+import { parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill-meta.mjs'
+
+/**
+ * Валідує всі `npm/skills/<id>/meta.json`.
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function check(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+  const skillsDir = join(cwd, 'npm', 'skills')
+  if (!existsSync(skillsDir)) {
+    reporter.pass('npm/skills/ відсутній — немає скілів для валідації')
+    return Promise.resolve(reporter.getExitCode())
+  }
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const id = entry.name
+    const skillDir = join(skillsDir, id)
+    let skillOk = true
+
+    if (existsSync(join(skillDir, 'auto.md'))) {
+      reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+      skillOk = false
+    }
+
+    const raw = readSkillMetaRaw(skillDir)
+    if (!raw) {
+      reporter.fail(`skills/${id}: відсутній або невалідний meta.json (очікується {"auto"?, "worktree": bool})`)
+      continue
+    }
+    if (typeof raw.worktree !== 'boolean') {
+      reporter.fail(`skills/${id}: meta.json.worktree має бути boolean`)
+      skillOk = false
+    }
+    if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
+      reporter.fail(`skills/${id}: meta.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
+      skillOk = false
+    }
+    if (skillOk) {
+      reporter.pass(`skills/${id}: meta.json валідний`)
+    }
+  }
+
+  return Promise.resolve(reporter.getExitCode())
+}

package/rules/release/change.mjs

@@ -43,7 +43,9 @@ export async function runChangeCli(args) {
   const message = get('--message')
   const ws = get('--ws') ?? '.'
   if (!bump || !section || !message) {
-    console.error('❌ Використання: n-cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]')
+    console.error(
+      '❌ Використання: n-cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]'
+    )
     return 1
   }
   try {

package/rules/release/lib/change-file.mjs

@@ -45,7 +45,9 @@ export function parseChangeFile(text) {
     throw new Error(`change-файл: bump має бути одним із ${VALID_BUMPS.join('|')} (отримано «${fm.bump ?? ''}»)`)
   }
   if (!VALID_SECTIONS.includes(fm.section)) {
-    throw new Error(`change-файл: section має бути одним із ${VALID_SECTIONS.join('|')} (отримано «${fm.section ?? ''}»)`)
+    throw new Error(
+      `change-файл: section має бути одним із ${VALID_SECTIONS.join('|')} (отримано «${fm.section ?? ''}»)`
+    )
   }
   if (!description) throw new Error('change-файл: порожній опис')
   return { bump: fm.bump, section: fm.section, description }

package/rules/release/release.mjs

@@ -28,7 +28,9 @@ async function writeManifestVersion(cwd, manifest, newVersion) {
   const re = manifest.kind === 'npm' ? SEMVER_LINE_RE : PY_VERSION_LINE_RE
   const replaced = text.replace(re, `$1${newVersion}$2`)
   if (replaced === text) {
-    throw new Error(`release: не вдалося оновити version у ${manifest.ws}/${manifest.manifestRel} — патерн version не знайдено`)
+    throw new Error(
+      `release: не вдалося оновити version у ${manifest.ws}/${manifest.manifestRel} — патерн version не знайдено`
+    )
   }
   await writeFile(path, replaced)
 }

package/rules/test/js/data/stryker_config/stryker-vue-macros-ignorer.mjs

@@ -24,7 +24,8 @@ const VUE_SETUP_MACROS = new Set([
   'defineOptions'
 ])
 
-const IGNORE_MESSAGE = 'Vue <script setup> macro call cannot be mutated (defineProps/defineEmits/etc. must be statically analyzable for @vue/compiler-sfc).'
+const IGNORE_MESSAGE =
+  'Vue <script setup> macro call cannot be mutated (defineProps/defineEmits/etc. must be statically analyzable for @vue/compiler-sfc).'
 
 /**
  * @param {{isCallExpression: () => boolean, node: {callee: {type: string, name?: string}}}} path babel NodePath, переданий Stryker-instrumenter

package/rules/test/js/stryker_config.mjs

@@ -111,13 +111,7 @@ export async function check(cwd = process.cwd()) {
   for (const jsRoot of jsRoots) {
     const isVueRoot = await hasVueFiles(jsRoot)
     const strykerBaseline = isVueRoot ? STRYKER_VUE_BASELINE_PATH : STRYKER_BASELINE_PATH
-    await ensureBaselineFile(
-      reporter,
-      cwd,
-      strykerBaseline,
-      join(jsRoot, 'stryker.config.mjs'),
-      'stryker.config.mjs'
-    )
+    await ensureBaselineFile(reporter, cwd, strykerBaseline, join(jsRoot, 'stryker.config.mjs'), 'stryker.config.mjs')
     if (isVueRoot) {
       await ensureBaselineFile(
         reporter,
@@ -133,7 +127,11 @@ export async function check(cwd = process.cwd()) {
   // Гарантуємо що тест-артефакти (Stryker output, lcov HTML-звіт) ніколи не
   // потрапляють у commit. Patterns покривають усі workspaces через `**/`-префікс
   // (єдиний root .gitignore).
-  const { added } = await ensureGitignoreEntries(cwd, TEST_GITIGNORE_ENTRIES, 'Test artifacts: Stryker + coverage (test.mdc)')
+  const { added } = await ensureGitignoreEntries(
+    cwd,
+    TEST_GITIGNORE_ENTRIES,
+    'Test artifacts: Stryker + coverage (test.mdc)'
+  )
   if (added.length > 0) {
     reporter.pass(`.gitignore: додано тест-патерни (${added.join(', ')}) (test.mdc)`)
   }

package/rules/vue/js/packages.mjs

@@ -422,15 +422,7 @@ async function checkVuePackage(rootDir, ignorePaths, fail, passFn, cwd) {
   await checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail, cwd)
 
   const { hasVueAutoImport } = await checkViteConfig(rootDir, prefix, passFn, fail, cwd)
-  await checkVueImportViolations(
-    rootDir,
-    join(cwd, rootDir),
-    ignorePaths,
-    hasVueAutoImport,
-    prefix,
-    passFn,
-    fail
-  )
+  await checkVueImportViolations(rootDir, join(cwd, rootDir), ignorePaths, hasVueAutoImport, prefix, passFn, fail)
   await checkVueNodeImportViolations(rootDir, join(cwd, rootDir), ignorePaths, prefix, passFn, fail)
   await checkEsbuildMentions(rootDir, join(cwd, rootDir), ignorePaths, prefix, passFn, fail)
 }

package/rules/worktree/worktree.mdc

@@ -0,0 +1,34 @@
+---
+description: Конвенція git-worktree у цьому репо — створення, інвентаризація та прибирання через n-cursor worktree CLI.
+globs:
+alwaysApply: true
+---
+
+# Worktree-конвенція
+
+Усі git-worktree створюй і прибирай через CLI `n-cursor worktree` — він кладе їх у
+`.worktrees/` (gitignored) і веде інвентарний файл-опис поруч.
+
+## Розташування
+
+```
+.worktrees/
+  feat-skill-meta/        ← git worktree checkout
+  feat-skill-meta.md      ← інвентарний опис поруч (gitignored через .worktrees/)
+```
+
+Слеш у гілці перетворюється на дефіс: `feat/skill-meta` → `.worktrees/feat-skill-meta/`.
+Git-гілка лишається з оригінальним імʼям (`feat/skill-meta`).
+
+## Команди
+
+- **Створити** (опис обовʼязковий): `npx @nitra/cursor worktree add <branch> "<навіщо>"`
+- **Інвентаризація**: `npx @nitra/cursor worktree list`
+- **Прибрати**: `npx @nitra/cursor worktree remove <branch> [--force]`
+- **Прибрати осиротілі**: `npx @nitra/cursor worktree prune`
+
+## Заборони
+
+- Не клади worktree в `.claude/worktrees/` — це приватна директорія харнесу Claude Code.
+- Не клади worktree в батьківський каталог `../cursor-<name>` — ускладнює інвентаризацію.
+- Не створюй worktree вручну (`git worktree add`) повз CLI — інакше не буде інвентарного опису.

package/schemas/skill-meta.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@nitra/cursor/schemas/skill-meta.json",
+  "title": "n-cursor skill meta",
+  "description": "Метадані скіла @nitra/cursor: умова автоактивації (auto) і чи виконувати в окремому git-worktree (worktree). Файл npm/skills/<id>/meta.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["worktree"],
+  "properties": {
+    "auto": {
+      "description": "Умова автоактивації: \"завжди\" або непорожній масив id правил, від яких залежить скіл.",
+      "oneOf": [
+        { "const": "завжди" },
+        { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+      ]
+    },
+    "worktree": {
+      "type": "boolean",
+      "description": "true — виконувати скіл в окремому git-worktree, один інстанс за раз (без паралельного запуску); false — у worktree не виконується."
+    }
+  }
+}

package/schemas/v8r-catalog.json

@@ -25,6 +25,11 @@
       "description": "TypeScript config для pi extension templates, які Schema Store не матчить через вкладений/прихований шлях",
       "url": "https://json.schemastore.org/tsconfig.json",
       "fileMatch": [".pi/extensions/*/tsconfig.json", "npm/.pi-template/extensions/*/tsconfig.json"]
+    },
+    {
+      "name": "n-cursor skill meta",
+      "fileMatch": ["npm/skills/*/meta.json"],
+      "url": "https://unpkg.com/@nitra/cursor/schemas/skill-meta.json"
     }
   ]
 }

package/scripts/auto-skills.mjs

@@ -1,56 +1,33 @@
 /**
- * Автовизначення skills для `.n-cursor.json` за умовами зі `npm/skills/<skill>/auto.md`.
+ * Автовизначення skills для `.n-cursor.json` за умовами з `npm/skills/<skill>/meta.json`.
  *
- * `auto.md` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
+ * `meta.json` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
  *
- *  - `завжди` — скіл активується незалежно від інших правил
+ *  - `auto: "завжди"` — скіл активується незалежно від інших правил
  *    (приклади: `fix`, `lint`, `llm-patch`, `publish-telegram`).
- *  - `[rule, rule, …]` — скіл активується, якщо ВСІ перелічені правила вже виявлені
- *    auto-rules (приклади: `adr-normalize - [adr]`, `taze - [bun]`).
- *  - файл відсутній або формат не розпізнано — скіл opt-in лише через `.n-cursor.json:skills`.
+ *  - `auto: ["rule", …]` — скіл активується, якщо ВСІ перелічені правила вже виявлені
+ *    auto-rules (приклади: `adr-normalize - ["adr"]`, `taze - ["bun"]`).
+ *  - поле `auto` відсутнє або формат не розпізнано — скіл opt-in лише через `.n-cursor.json:skills`.
  *
  * Сканування `npm/skills/` — sync під час завантаження модуля (детермінізм + sync API
  * `auto-rules.mjs`-сусіда). Кеш на час процесу.
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { parseSkillAutoSpec, readSkillMetaRaw } from './lib/skill-meta.mjs'
+
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const SKILLS_DIR = join(PACKAGE_ROOT, 'skills')
 
-const ALWAYS_LITERAL = 'завжди'
-const BRACKET_LIST_RE = /^\[([^\]]+)\]$/u
-
 /**
  * @typedef {{ always: true } | { rules: readonly string[] }} SkillAutoSpec
  */
 
 /**
- * Парсить тіло `auto.md` одного скіла.
- * @param {string} text вміст файла (без `trim`)
- * @returns {SkillAutoSpec | null} `null` — формат не розпізнано (= opt-in)
- */
-function parseSkillAutoSpec(text) {
-  const trimmed = text.trim()
-  if (trimmed === ALWAYS_LITERAL) {
-    return { always: true }
-  }
-  const m = trimmed.match(BRACKET_LIST_RE)
-  if (m) {
-    const rules = m[1]
-      .split(',')
-      .map(s => s.trim())
-      .filter(s => s.length > 0)
-    if (rules.length === 0) return null
-    return { rules: Object.freeze(rules) }
-  }
-  return null
-}
-
-/**
- * Сканує `npm/skills/<id>/auto.md`. Скіли без `auto.md` або з нерозпізнаним
- * вмістом не потрапляють у результат — їх можна вмикати лише вручну в конфізі.
+ * Сканує `npm/skills/<id>/meta.json`. Скіли без `meta.json` або без розпізнаного
+ * `auto` не потрапляють у результат — їх вмикають лише вручну в конфізі.
  * @param {string} [skillsDir] override для тестів
  * @returns {Record<string, SkillAutoSpec>} мапа `skillId → spec`
  */
@@ -60,9 +37,9 @@ export function discoverSkillAutoActivation(skillsDir = SKILLS_DIR) {
   const out = {}
   for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue
-    const autoMdPath = join(skillsDir, entry.name, 'auto.md')
-    if (!existsSync(autoMdPath)) continue
-    const spec = parseSkillAutoSpec(readFileSync(autoMdPath, 'utf8'))
+    const raw = readSkillMetaRaw(join(skillsDir, entry.name))
+    if (!raw) continue
+    const spec = parseSkillAutoSpec(raw.auto)
     if (spec) out[entry.name] = spec
   }
   return out

package/scripts/lib/skill-meta.mjs

@@ -0,0 +1,54 @@
+/**
+ * Спільний парсер метаданих скіла з `npm/skills/<id>/meta.json`.
+ *
+ * `meta.json` — єдине джерело правди для скіла замість колишнього `auto.md`:
+ *  - `auto` — умова автоактивації (`"завжди"` | масив id правил), опційне;
+ *  - `worktree` — boolean: чи виконувати скіл в окремому git-worktree (один інстанс).
+ *
+ * Цим хелпером користуються `auto-skills.mjs` (автоактивація), `n-cursor.js`
+ * (sync + вшивання worktree-блоку) і check-концерн `npm-module/js/skill_meta.mjs`,
+ * щоб не дублювати парсинг і форму валідації.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Літерал безумовної автоактивації (українською, як у `auto-skills.mjs`). */
+export const SKILL_ALWAYS = 'завжди'
+
+/**
+ * @typedef {{ always: true } | { rules: string[] }} SkillAutoSpec
+ */
+
+/**
+ * Перетворює значення поля `auto` з `meta.json` у `SkillAutoSpec`.
+ * @param {unknown} value значення `meta.json.auto`
+ * @returns {SkillAutoSpec | null} `null` — формат не розпізнано (= opt-in)
+ */
+export function parseSkillAutoSpec(value) {
+  if (value === SKILL_ALWAYS) {
+    return { always: true }
+  }
+  if (Array.isArray(value)) {
+    const rules = value.map(s => String(s).trim()).filter(s => s.length > 0)
+    if (rules.length === 0) return null
+    return { rules }
+  }
+  return null
+}
+
+/**
+ * Читає й парсить `meta.json` одного скіла.
+ * @param {string} skillDir абсолютний шлях до каталогу скіла
+ * @returns {Record<string, unknown> | null} розпарсений обʼєкт або `null` (немає файлу / невалідний JSON / не-обʼєкт)
+ */
+export function readSkillMetaRaw(skillDir) {
+  const metaPath = join(skillDir, 'meta.json')
+  if (!existsSync(metaPath)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(metaPath, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return /** @type {Record<string, unknown>} */ (parsed)
+  } catch {
+    return null
+  }
+}

package/scripts/lib/worktree-notice.mjs

@@ -0,0 +1,55 @@
+/**
+ * Вшивання worktree-інструкції у синкнутий `SKILL.md` (рішення D2 зі spec).
+ *
+ * Коли `meta.json.worktree === true`, скіл має виконуватись в окремому git-worktree
+ * і не паралелитись. Підказка адресована агенту, який читає `SKILL.md`, тож
+ * вставляється в текст між стабільними маркерами — ре-синк ідемпотентний:
+ * наявний блок замінюється, при `worktree:false` — видаляється.
+ */
+
+/** Маркер початку worktree-блоку (стабільний, не залежить від тексту всередині). */
+export const WORKTREE_START = '<!-- n-cursor:worktree:start -->'
+/** Маркер кінця worktree-блоку. */
+export const WORKTREE_END = '<!-- n-cursor:worktree:end -->'
+
+const NOTICE_BODY =
+  '> **Worktree:** виконуй цей скіл в окремому git-worktree (`git worktree add`); ' +
+  '**не** запускай паралельно — один інстанс за раз.'
+
+/** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
+const BLOCK_RE = /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u
+
+/** Закриття YAML-frontmatter на початку файла. */
+const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
+
+/**
+ * Канонічний блок worktree-інструкції.
+ * @returns {string} текст блоку від START до END
+ */
+function buildBlock() {
+  return `${WORKTREE_START}\n${NOTICE_BODY}\n${WORKTREE_END}`
+}
+
+/**
+ * Вставляє / оновлює / видаляє worktree-блок у вмісті `SKILL.md`.
+ * @param {string} content вміст `SKILL.md`
+ * @param {boolean} enabled чи має бути блок (значення `meta.json.worktree`)
+ * @returns {string} оновлений вміст (ідемпотентно)
+ */
+export function injectWorktreeNotice(content, enabled) {
+  const hadBlock = content.includes(WORKTREE_START)
+  const withoutBlock = content.replace(BLOCK_RE, '\n\n')
+
+  if (!enabled) {
+    return hadBlock ? withoutBlock : content
+  }
+
+  const block = buildBlock()
+  const fm = withoutBlock.match(FRONTMATTER_RE)
+  if (fm) {
+    const head = fm[1]
+    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, '')
+    return `${head}\n${block}\n\n${rest}`
+  }
+  return `${block}\n\n${withoutBlock.replace(/^\n+/u, '')}`
+}

package/scripts/lib/worktree.mjs

@@ -0,0 +1,73 @@
+/**
+ * Чиста логіка worktree-tool `n-cursor worktree` (без git/fs side-effects).
+ *
+ * Тут — детерміновані, тестовані без git функції:
+ *  - `sanitizeBranch` — імʼя гілки → безпечне імʼя каталогу/файла (слеш та інші
+ *    небезпечні для шляху символи → дефіс), щоб структура `.worktrees/` лишалась пласкою;
+ *  - `worktreePaths` — шляхи checkout і файла-опису поруч;
+ *  - `buildDescription` — текст інвентарного `.worktrees/<name>.md` за конвенцією worktree.mdc;
+ *  - `findOrphanDescFiles` — `.md`-описи без зареєстрованого worktree (для `prune`).
+ *
+ * Оркестрація (виклики git, запис файлів, argv) — у `npm/scripts/worktree-cli.mjs`.
+ */
+import { basename, join } from 'node:path'
+
+/** Символи, безпечні для імені каталогу/файла; решта → дефіс. */
+const UNSAFE_PATH_CHARS_RE = /[^a-zA-Z0-9._-]+/gu
+
+/**
+ * Перетворює імʼя git-гілки на безпечне імʼя каталогу/файла для `.worktrees/`.
+ * @param {string} branch імʼя git-гілки (наприклад `feat/skill-meta`)
+ * @returns {string} пласке імʼя (наприклад `feat-skill-meta`)
+ */
+export function sanitizeBranch(branch) {
+  if (typeof branch !== 'string' || branch.trim() === '') {
+    throw new Error('worktree: імʼя гілки обовʼязкове')
+  }
+  const sanitized = branch.trim().replace(UNSAFE_PATH_CHARS_RE, '-').replace(/^-+|-+$/gu, '')
+  if (sanitized === '') {
+    throw new Error(`worktree: імʼя гілки "${branch}" не містить допустимих символів`)
+  }
+  return sanitized
+}
+
+/**
+ * Детерміновані шляхи checkout і файла-опису для гілки.
+ * @param {string} repoRoot абсолютний корінь репозиторію
+ * @param {string} branch імʼя git-гілки
+ * @returns {{ checkout: string, descFile: string }} абсолютні шляхи
+ */
+export function worktreePaths(repoRoot, branch) {
+  const name = sanitizeBranch(branch)
+  const dir = join(repoRoot, '.worktrees')
+  return { checkout: join(dir, name), descFile: join(dir, `${name}.md`) }
+}
+
+/**
+ * Текст інвентарного файла-опису worktree.
+ * @param {{ branch: string, task: string, baseCommit: string, date: string }} params поля опису
+ * @returns {string} markdown-вміст `.worktrees/<name>.md`
+ */
+export function buildDescription({ branch, task, baseCommit, date }) {
+  return [
+    `# ${branch}`,
+    '',
+    `**Задача:** ${task}`,
+    `**Дата:** ${date}`,
+    `**База (коміт):** ${baseCommit}`,
+    '',
+    'Прибрати: ' + '`' + `npx @nitra/cursor worktree remove ${branch}` + '`',
+    ''
+  ].join('\n')
+}
+
+/**
+ * `.md`-описи без відповідного зареєстрованого worktree-checkout.
+ * @param {string[]} descFiles абсолютні шляхи `.worktrees/*.md`
+ * @param {string[]} registeredCheckouts абсолютні шляхи зареєстрованих worktree-checkout
+ * @returns {string[]} осиротілі `.md` (підмножина `descFiles`)
+ */
+export function findOrphanDescFiles(descFiles, registeredCheckouts) {
+  const checkoutBasenames = new Set(registeredCheckouts.map(c => basename(c)))
+  return descFiles.filter(md => !checkoutBasenames.has(basename(md).replace(/\.md$/u, '')))
+}

package/scripts/worktree-cli.mjs

@@ -0,0 +1,200 @@
+/**
+ * CLI-оркестратор worktree-tool `n-cursor worktree` (виконавець конвенції `.worktrees/`).
+ *
+ * Підкоманди:
+ *   add <branch> "<опис>"     — git worktree add .worktrees/<sanit> -b <branch> (від HEAD) + .md-опис
+ *   remove <branch> [--force] — прибрати checkout + .md (гілку лишає)
+ *   list                      — git worktree list + вміст .md-описів
+ *   prune                     — git worktree prune + видалити осиротілі .md
+ *
+ * Чисті функції (санітизація, шляхи, текст опису, осиротілі) — у `lib/worktree.mjs`.
+ * Тут лише git-виклики, запис файлів, парсинг argv і звіт.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { buildDescription, findOrphanDescFiles, worktreePaths } from './lib/worktree.mjs'
+
+const USAGE = [
+  'Usage:',
+  '  npx @nitra/cursor worktree add <branch> "<опис>"',
+  '  npx @nitra/cursor worktree remove <branch> [--force]',
+  '  npx @nitra/cursor worktree list',
+  '  npx @nitra/cursor worktree prune'
+].join('\n')
+
+/**
+ * Запускає git, повертає { status, stdout, stderr }.
+ * @param {string[]} args аргументи git
+ * @param {string} cwd робочий каталог
+ * @returns {{ status: number, stdout: string, stderr: string }} результат
+ */
+function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/**
+ * Поточна дата YYYY-MM-DD (ін'єкція через ctx.now для тестів).
+ * @param {() => Date} now фабрика дати
+ * @returns {string} дата у форматі YYYY-MM-DD
+ */
+function today(now) {
+  return now().toISOString().slice(0, 10)
+}
+
+/**
+ * Реєстровані worktree-checkout (абсолютні шляхи) з `git worktree list --porcelain`.
+ * @param {string} cwd корінь репо
+ * @returns {string[]} абсолютні шляхи checkout
+ */
+function listRegisteredCheckouts(cwd) {
+  return git(['worktree', 'list', '--porcelain'], cwd)
+    .stdout.split('\n')
+    .filter(line => line.startsWith('worktree '))
+    .map(line => line.slice('worktree '.length).trim())
+}
+
+/**
+ * Абсолютні шляхи `.worktrees/*.md`.
+ * @param {string} cwd корінь репо
+ * @returns {string[]} шляхи файлів-описів
+ */
+function listDescFiles(cwd) {
+  const dir = join(cwd, '.worktrees')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter(n => n.endsWith('.md'))
+    .map(n => join(dir, n))
+}
+
+/**
+ * add: створити worktree від HEAD + .md-опис.
+ * @param {string[]} rest [branch, ...descParts]
+ * @param {{ cwd: string, log: Function, logError: Function, now: () => Date }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdAdd(rest, ctx) {
+  const [branch, ...descParts] = rest
+  const task = descParts.join(' ').trim()
+  if (!branch) {
+    ctx.logError('worktree add: потрібне імʼя гілки')
+    ctx.logError(USAGE)
+    return 1
+  }
+  if (!task) {
+    ctx.logError('worktree add: опис обовʼязковий — `worktree add <branch> "<опис>"`')
+    return 1
+  }
+  let paths
+  try {
+    paths = worktreePaths(ctx.cwd, branch)
+  } catch (error) {
+    ctx.logError(error.message)
+    return 1
+  }
+  const added = git(['worktree', 'add', paths.checkout, '-b', branch], ctx.cwd)
+  if (added.status !== 0) {
+    ctx.logError(`worktree add не вдався: ${added.stderr.trim()}`)
+    return 1
+  }
+  const baseCommit = git(['rev-parse', '--short', 'HEAD'], ctx.cwd).stdout.trim()
+  const md = buildDescription({ branch, task, baseCommit, date: today(ctx.now) })
+  writeFileSync(paths.descFile, md, 'utf8')
+  ctx.log(`✅ worktree: ${paths.checkout}`)
+  ctx.log(`   опис:    ${paths.descFile}`)
+  return 0
+}
+
+/**
+ * remove: прибрати checkout + .md (гілку лишає).
+ * @param {string[]} rest [branch, ...flags]
+ * @param {{ cwd: string, log: Function, logError: Function }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdRemove(rest, ctx) {
+  const branch = rest.find(a => !a.startsWith('--'))
+  const force = rest.includes('--force')
+  if (!branch) {
+    ctx.logError('worktree remove: потрібне імʼя гілки')
+    return 1
+  }
+  let paths
+  try {
+    paths = worktreePaths(ctx.cwd, branch)
+  } catch (error) {
+    ctx.logError(error.message)
+    return 1
+  }
+  const args = ['worktree', 'remove', paths.checkout]
+  if (force) args.push('--force')
+  const removed = git(args, ctx.cwd)
+  if (removed.status !== 0) {
+    ctx.logError(`worktree remove не вдався: ${removed.stderr.trim()} (спробуй --force, якщо дерево брудне)`)
+    return 1
+  }
+  if (existsSync(paths.descFile)) rmSync(paths.descFile, { force: true })
+  ctx.log(`✅ прибрано: ${paths.checkout} (гілку ${branch} лишено)`)
+  return 0
+}
+
+/**
+ * list: git worktree list + вміст .md-описів.
+ * @param {{ cwd: string, log: Function }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdList(ctx) {
+  ctx.log(git(['worktree', 'list'], ctx.cwd).stdout.trimEnd())
+  for (const md of listDescFiles(ctx.cwd)) {
+    ctx.log(`\n--- ${md} ---`)
+    ctx.log(readFileSync(md, 'utf8').trimEnd())
+  }
+  return 0
+}
+
+/**
+ * prune: git worktree prune + видалити осиротілі .md.
+ * @param {{ cwd: string, log: Function }} ctx контекст
+ * @returns {number} exit code
+ */
+function cmdPrune(ctx) {
+  git(['worktree', 'prune'], ctx.cwd)
+  const orphans = findOrphanDescFiles(listDescFiles(ctx.cwd), listRegisteredCheckouts(ctx.cwd))
+  for (const md of orphans) {
+    rmSync(md, { force: true })
+    ctx.log(`🧹 видалено осиротілий опис: ${md}`)
+  }
+  ctx.log(`prune завершено (осиротілих описів: ${orphans.length})`)
+  return 0
+}
+
+/**
+ * Точка входу підкоманди worktree.
+ * @param {string[]} argv аргументи після `worktree`
+ * @param {{ cwd?: string, log?: Function, logError?: Function, now?: () => Date }} [options] ін'єкція для тестів
+ * @returns {Promise<number>} exit code
+ */
+export function runWorktreeCli(argv, options = {}) {
+  const ctx = {
+    cwd: options.cwd ?? processCwd(),
+    log: options.log ?? (line => console.log(line)),
+    logError: options.logError ?? (line => console.error(line)),
+    now: options.now ?? (() => new Date())
+  }
+  const [sub, ...rest] = argv
+  switch (sub) {
+    case 'add':
+      return Promise.resolve(cmdAdd(rest, ctx))
+    case 'remove':
+      return Promise.resolve(cmdRemove(rest, ctx))
+    case 'list':
+      return Promise.resolve(cmdList(ctx))
+    case 'prune':
+      return Promise.resolve(cmdPrune(ctx))
+    default:
+      ctx.logError(USAGE)
+      return Promise.resolve(1)
+  }
+}

package/skills/adr-normalize/meta.json

@@ -0,0 +1 @@
+{ "auto": ["adr"], "worktree": true }

package/skills/coverage-fix/meta.json

@@ -0,0 +1 @@
+{ "auto": ["js-lint"], "worktree": true }

package/skills/fix/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": true }

package/skills/fix-tests/meta.json

@@ -0,0 +1 @@
+{ "auto": ["js-lint"], "worktree": true }

package/skills/lint/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false }

package/skills/llm-patch/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false }

package/skills/publish-telegram/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false }

package/skills/start-check/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false }

package/skills/taze/meta.json

@@ -0,0 +1 @@
+{ "auto": ["bun"], "worktree": true }

package/skills/worktree/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: worktree
+description: >-
+  Створення та керування git-worktree через n-cursor worktree CLI: ізольований
+  workspace у .worktrees/<branch>/ з інвентарним файлом-описом
+---
+
+# worktree — ізольований workspace через CLI
+
+Для роботи в окремому git-worktree використовуй CLI `n-cursor worktree` — він
+однаковий у Claude і Cursor, кладе worktree у `.worktrees/` (gitignored) і сам
+створює інвентарний файл-опис поруч.
+
+## Команди
+
+- Створити (опис **обовʼязковий**):
+  `npx @nitra/cursor worktree add <branch> "<навіщо цей worktree>"`
+- Список активних з описами:
+  `npx @nitra/cursor worktree list`
+- Прибрати (гілку лишає; `--force` для брудного дерева):
+  `npx @nitra/cursor worktree remove <branch> [--force]`
+- Прибрати осиротілі описи / метадані:
+  `npx @nitra/cursor worktree prune`
+
+## Приклад
+
+```bash
+npx @nitra/cursor worktree add feat/skill-meta "реалізація Spec A: meta.json"
+cd .worktrees/feat-skill-meta
+# … робота в ізоляції …
+cd -
+npx @nitra/cursor worktree remove feat/skill-meta
+```
+
+Слеш у гілці перетворюється на дефіс для пласкої структури: `feat/skill-meta`
+→ `.worktrees/feat-skill-meta/`. Git-гілка лишається `feat/skill-meta`.
+
+Конвенція й заборони (де НЕ створювати worktree) — `.cursor/rules/n-worktree.mdc`.

package/skills/worktree/meta.json

@@ -0,0 +1 @@
+{ "worktree": false }

package/skills/adr-normalize/auto.md

@@ -1 +0,0 @@
-[adr]

package/skills/coverage-fix/auto.md

@@ -1 +0,0 @@
-[js-lint]

package/skills/fix/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/fix-tests/auto.md

@@ -1 +0,0 @@
-[js-lint]

package/skills/lint/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/llm-patch/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/publish-telegram/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/start-check/auto.md

@@ -1 +0,0 @@
-[bun]

package/skills/taze/auto.md

@@ -1 +0,0 @@
-[bun]