claude-dev-env 2.15.0 → 2.16.0

package/bin/install.test.mjs

@@ -176,6 +176,15 @@ test('CONTENT_DIRECTORIES includes _shared so installer copies _shared/pr-loop/
 });
 
 
+test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
+    assert.equal(
+        CONTENT_DIRECTORIES.includes('agents'),
+        false,
+        'agents copies into ~/.agents/agents; ~/.claude/agents is the lookup pointer',
+    );
+});
+
+
 test('core includeDirectories ships _shared and scripts for advisor protocol and CLI fallback', () => {
     assert.ok(
         CORE_INCLUDE_DIRECTORIES.includes('_shared'),
@@ -1281,25 +1290,59 @@ const README_BASENAME_PATTERN = /^readme\.md$/i;
 
 
 /**
- * Build a sandbox holding an installed skills root and a run backup root.
+ * Build a sandbox holding one installed managed root and a run backup root.
  *
- * @param {object} installedFiles Forward-slash relative paths under the skills root mapped to contents.
- * @returns {{root: string, skillsRoot: string, backupRoot: string}} The sandbox paths.
+ * @param {object} installedFiles Forward-slash relative paths under the installed root mapped to contents.
+ * @param {string} [managedRootName] The managed top-level directory the files sit under.
+ * @returns {{root: string, skillsRoot: string, installedRoot: string, backupRoot: string}} The sandbox paths.
  */
-function createStalePruneSandbox(installedFiles) {
+function createStalePruneSandbox(installedFiles, managedRootName = 'skills') {
     const root = mkdtempSync(join(tmpdir(), 'cdev-stale-prune-'));
-    const skillsRoot = join(root, 'skills');
+    const installedRoot = join(root, managedRootName);
     const backupRoot = join(root, 'pruned', 'run-timestamp');
-    mkdirSync(skillsRoot, { recursive: true });
+    mkdirSync(installedRoot, { recursive: true });
     for (const [relativePath, contents] of Object.entries(installedFiles)) {
-        const targetPath = join(skillsRoot, relativePath);
+        const targetPath = join(installedRoot, relativePath);
         mkdirSync(dirname(targetPath), { recursive: true });
         writeFileSync(targetPath, contents);
     }
-    return { root, skillsRoot, backupRoot };
+    return { root, skillsRoot: installedRoot, installedRoot, backupRoot };
 }
 
 
+test('pruneStaleInstalledFiles leaves a retained unmanaged path the package stopped shipping in place', () => {
+    const sandbox = createStalePruneSandbox({
+        'profile-isolation-launchers/config/mcp-bundles.json': '{"schemaVersion":1}\n',
+        'sync-to-cursor.py': 'print("shipped")\n',
+    }, 'scripts');
+    try {
+        const shippedFilePath = join(sandbox.installedRoot, 'sync-to-cursor.py');
+        const retainedFilePath = join(
+            sandbox.installedRoot, 'profile-isolation-launchers', 'config', 'mcp-bundles.json',
+        );
+
+        const pruneOutcome = pruneStaleInstalledFiles(
+            [shippedFilePath, retainedFilePath],
+            [shippedFilePath],
+            sandbox.installedRoot,
+            sandbox.backupRoot,
+            { managedHomeDirectory: sandbox.root },
+        );
+
+        assert.equal(pruneOutcome.prunedCount, 0, 'a retained unmanaged path never counts as pruned');
+        assert.deepEqual(pruneOutcome.failedPaths, [], 'skipping a retained path reports no failed move');
+        assert.equal(
+            existsSync(retainedFilePath),
+            true,
+            'the launcher file a prior install recorded stays where the live launcher reads it',
+        );
+        assert.equal(existsSync(shippedFilePath), true, 'a file this run wrote stays in place');
+    } finally {
+        rmSync(sandbox.root, { recursive: true, force: true });
+    }
+});
+
+
 /**
  * Run a callable with console.warn captured, returning its value and the warnings.
  *

package/bin/publish-directory-pointer.mjs

@@ -0,0 +1,175 @@
+/**
+ * Publish a Claude Code lookup path as a directory pointer to the agents home.
+ *
+ * Skills and agents live under the agents home. Claude Code still discovers
+ * them at `managedRoot/skills` and `managedRoot/agents`, so the installer
+ * writes those two paths as directory pointers (a POSIX symlink, or a Windows
+ * junction). One helper owns the create, refresh, and relocate steps.
+ */
+
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    readlinkSync,
+    readdirSync,
+    renameSync,
+    rmSync,
+    symlinkSync,
+    unlinkSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { normalizePathForComparison } from './resolve-install-root.mjs';
+
+export const DIRECTORY_POINTER_TYPE_JUNCTION = 'junction';
+export const DIRECTORY_POINTER_TYPE_DIR = 'dir';
+export const POINTER_ACTION_ALREADY_POINTING = 'already-pointing';
+export const POINTER_ACTION_CREATED = 'created';
+
+/**
+ * Directory-pointer type this host uses.
+ *
+ * Windows receives a junction so the pointer works without Developer Mode.
+ * POSIX receives a directory symlink.
+ *
+ * @param {string} [platform]
+ * @returns {typeof DIRECTORY_POINTER_TYPE_JUNCTION | typeof DIRECTORY_POINTER_TYPE_DIR}
+ */
+export function directoryPointerTypeForPlatform(platform = process.platform) {
+    return platform === 'win32'
+        ? DIRECTORY_POINTER_TYPE_JUNCTION
+        : DIRECTORY_POINTER_TYPE_DIR;
+}
+
+/**
+ * Report whether pointerPath is a directory pointer whose target is targetPath.
+ *
+ * @param {string} pointerPath
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isDirectoryPointerTo(pointerPath, targetPath) {
+    const pathKind = readPathKind(pointerPath);
+    if (pathKind !== 'symlink') {
+        return false;
+    }
+    const linkTarget = readlinkSync(pointerPath);
+    const resolvedLinkTarget = resolve(dirname(pointerPath), linkTarget);
+    return normalizePathForComparison(resolvedLinkTarget)
+        === normalizePathForComparison(resolve(targetPath));
+}
+
+/**
+ * Make pointerPath a directory pointer to targetPath.
+ *
+ * A real directory already sitting at the lookup path is merged into the
+ * target, then the pointer is written. A pointer that already aims at the
+ * target is left in place.
+ *
+ * @param {string} pointerPath Claude Code lookup path (for example `~/.claude/skills`).
+ * @param {string} targetPath Canonical directory (for example `~/.agents/skills`).
+ * @param {{ pointerType?: string }} [options]
+ * @returns {{ action: string, pointerPath: string, targetPath: string }}
+ */
+export function ensureDirectoryPointer(pointerPath, targetPath, options = {}) {
+    const pointerType = options.pointerType ?? directoryPointerTypeForPlatform();
+    const resolvedTarget = resolve(targetPath);
+    const resolvedPointer = resolve(pointerPath);
+    mkdirSync(resolvedTarget, { recursive: true });
+
+    if (isDirectoryPointerTo(resolvedPointer, resolvedTarget)) {
+        return {
+            action: POINTER_ACTION_ALREADY_POINTING,
+            pointerPath: resolvedPointer,
+            targetPath: resolvedTarget,
+        };
+    }
+
+    const pathKind = readPathKind(resolvedPointer);
+    if (pathKind === 'symlink') {
+        unlinkSync(resolvedPointer);
+    } else if (pathKind === 'directory') {
+        mergeDirectoryContents(resolvedPointer, resolvedTarget);
+        rmSync(resolvedPointer, { recursive: true, force: true });
+    } else if (pathKind === 'file') {
+        throw new Error(
+            `Cannot publish a directory pointer: ${resolvedPointer} is a file`,
+        );
+    }
+
+    mkdirSync(dirname(resolvedPointer), { recursive: true });
+    symlinkSync(resolvedTarget, resolvedPointer, pointerType);
+    return {
+        action: POINTER_ACTION_CREATED,
+        pointerPath: resolvedPointer,
+        targetPath: resolvedTarget,
+    };
+}
+
+/**
+ * Remove a directory pointer when it aims at the expected target.
+ *
+ * @param {string} pointerPath
+ * @param {string} targetPath
+ * @returns {boolean} True when this call unlinked the pointer.
+ */
+export function unlinkDirectoryPointerIfMatch(pointerPath, targetPath) {
+    if (!isDirectoryPointerTo(pointerPath, targetPath)) {
+        return false;
+    }
+    unlinkSync(pointerPath);
+    return true;
+}
+
+/**
+ * @param {string} absolutePath
+ * @returns {'missing' | 'symlink' | 'directory' | 'file' | 'other'}
+ */
+function readPathKind(absolutePath) {
+    let stats;
+    try {
+        stats = lstatSync(absolutePath);
+    } catch (readError) {
+        if (readError && readError.code === 'ENOENT') {
+            return 'missing';
+        }
+        throw readError;
+    }
+    if (stats.isSymbolicLink()) {
+        return 'symlink';
+    }
+    if (stats.isDirectory()) {
+        return 'directory';
+    }
+    if (stats.isFile()) {
+        return 'file';
+    }
+    return 'other';
+}
+
+/**
+ * Move unique entries from sourceDirectory into destinationDirectory.
+ *
+ * An entry that already exists at the destination stays there. Nested
+ * directories merge the same way. Leftover source entries are removed by the
+ * caller with the source directory.
+ *
+ * @param {string} sourceDirectory
+ * @param {string} destinationDirectory
+ * @returns {void}
+ */
+function mergeDirectoryContents(sourceDirectory, destinationDirectory) {
+    mkdirSync(destinationDirectory, { recursive: true });
+    const allEntries = readdirSync(sourceDirectory, { withFileTypes: true });
+    for (const eachEntry of allEntries) {
+        const sourceChild = join(sourceDirectory, eachEntry.name);
+        const destinationChild = join(destinationDirectory, eachEntry.name);
+        if (!existsSync(destinationChild)) {
+            renameSync(sourceChild, destinationChild);
+            continue;
+        }
+        if (eachEntry.isDirectory() && readPathKind(destinationChild) === 'directory') {
+            mergeDirectoryContents(sourceChild, destinationChild);
+        }
+    }
+}

package/bin/publish-directory-pointer.test.mjs

@@ -0,0 +1,129 @@
+/**
+ * Real-filesystem tests for Claude lookup pointers into the agents home.
+ */
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    realpathSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+    DIRECTORY_POINTER_TYPE_DIR,
+    DIRECTORY_POINTER_TYPE_JUNCTION,
+    POINTER_ACTION_ALREADY_POINTING,
+    POINTER_ACTION_CREATED,
+    directoryPointerTypeForPlatform,
+    ensureDirectoryPointer,
+    isDirectoryPointerTo,
+    unlinkDirectoryPointerIfMatch,
+} from './publish-directory-pointer.mjs';
+
+function makeSandbox() {
+    const root = mkdtempSync(join(tmpdir(), 'cdev-pointer-'));
+    return {
+        root,
+        pointerPath: join(root, 'lookup', 'skills'),
+        targetPath: join(root, 'canonical', 'skills'),
+    };
+}
+
+test('directoryPointerTypeForPlatform uses a junction on Windows and a dir pointer elsewhere', () => {
+    assert.equal(directoryPointerTypeForPlatform('win32'), DIRECTORY_POINTER_TYPE_JUNCTION);
+    assert.equal(directoryPointerTypeForPlatform('linux'), DIRECTORY_POINTER_TYPE_DIR);
+    assert.equal(directoryPointerTypeForPlatform('darwin'), DIRECTORY_POINTER_TYPE_DIR);
+});
+
+test('ensureDirectoryPointer writes a lookup pointer whose files are the canonical files', () => {
+    const sandbox = makeSandbox();
+    try {
+        mkdirSync(sandbox.targetPath, { recursive: true });
+        const canonicalFile = join(sandbox.targetPath, 'notes.md');
+        writeFileSync(canonicalFile, 'canonical body\n');
+
+        const publication = ensureDirectoryPointer(sandbox.pointerPath, sandbox.targetPath);
+        assert.equal(publication.action, POINTER_ACTION_CREATED);
+        assert.equal(lstatSync(sandbox.pointerPath).isSymbolicLink(), true);
+        assert.equal(isDirectoryPointerTo(sandbox.pointerPath, sandbox.targetPath), true);
+        assert.equal(
+            readFileSync(join(sandbox.pointerPath, 'notes.md'), 'utf8'),
+            'canonical body\n',
+        );
+        assert.equal(
+            realpathSync(join(sandbox.pointerPath, 'notes.md')),
+            realpathSync(canonicalFile),
+        );
+    } finally {
+        rmSync(sandbox.root, { recursive: true, force: true });
+    }
+});
+
+test('ensureDirectoryPointer leaves a correct pointer in place', () => {
+    const sandbox = makeSandbox();
+    try {
+        const firstPublication = ensureDirectoryPointer(sandbox.pointerPath, sandbox.targetPath);
+        assert.equal(firstPublication.action, POINTER_ACTION_CREATED);
+        const secondPublication = ensureDirectoryPointer(sandbox.pointerPath, sandbox.targetPath);
+        assert.equal(secondPublication.action, POINTER_ACTION_ALREADY_POINTING);
+        assert.equal(isDirectoryPointerTo(sandbox.pointerPath, sandbox.targetPath), true);
+    } finally {
+        rmSync(sandbox.root, { recursive: true, force: true });
+    }
+});
+
+test('ensureDirectoryPointer relocates a real lookup directory into the agents home', () => {
+    const sandbox = makeSandbox();
+    try {
+        mkdirSync(sandbox.pointerPath, { recursive: true });
+        writeFileSync(join(sandbox.pointerPath, 'personal.md'), 'user skill\n');
+        mkdirSync(sandbox.targetPath, { recursive: true });
+        writeFileSync(join(sandbox.targetPath, 'shipped.md'), 'package skill\n');
+
+        ensureDirectoryPointer(sandbox.pointerPath, sandbox.targetPath);
+
+        assert.equal(lstatSync(sandbox.pointerPath).isSymbolicLink(), true);
+        assert.equal(
+            readFileSync(join(sandbox.targetPath, 'personal.md'), 'utf8'),
+            'user skill\n',
+        );
+        assert.equal(
+            readFileSync(join(sandbox.pointerPath, 'personal.md'), 'utf8'),
+            'user skill\n',
+        );
+        assert.equal(
+            readFileSync(join(sandbox.pointerPath, 'shipped.md'), 'utf8'),
+            'package skill\n',
+        );
+        assert.equal(existsSync(join(sandbox.targetPath, 'personal.md')), true);
+    } finally {
+        rmSync(sandbox.root, { recursive: true, force: true });
+    }
+});
+
+test('unlinkDirectoryPointerIfMatch removes only a pointer that aims at the expected target', () => {
+    const sandbox = makeSandbox();
+    try {
+        ensureDirectoryPointer(sandbox.pointerPath, sandbox.targetPath);
+        writeFileSync(join(sandbox.targetPath, 'kept.md'), 'kept\n');
+        assert.equal(
+            unlinkDirectoryPointerIfMatch(sandbox.pointerPath, sandbox.targetPath),
+            true,
+        );
+        assert.equal(existsSync(sandbox.pointerPath), false);
+        assert.equal(readFileSync(join(sandbox.targetPath, 'kept.md'), 'utf8'), 'kept\n');
+        assert.equal(
+            unlinkDirectoryPointerIfMatch(sandbox.pointerPath, sandbox.targetPath),
+            false,
+        );
+    } finally {
+        rmSync(sandbox.root, { recursive: true, force: true });
+    }
+});

package/bin/resolve-install-root.mjs

@@ -10,7 +10,7 @@
  */
 
 import { homedir } from 'node:os';
-import { join, normalize, resolve, sep } from 'node:path';
+import { basename, dirname, join, normalize, resolve, sep } from 'node:path';
 import {
     MYPY_INI_FILE_NAME,
     CODEX_HOME_ENVIRONMENT_VARIABLE,
@@ -18,10 +18,13 @@ import {
     CODEX_RULES_DIRECTORY_NAME,
     DEFAULT_CURSOR_DIRECTORY_NAME,
     CURSOR_RULES_DIRECTORY_NAME,
+    MANAGED_SKILLS_DIRECTORY_NAME,
+    MANAGED_AGENTS_DIRECTORY_NAME,
 } from './install-constants.mjs';
 
 export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
 export const DEFAULT_CLAUDE_DIRECTORY_NAME = '.claude';
+export const DEFAULT_AGENTS_DIRECTORY_NAME = '.agents';
 export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
 
 /**
@@ -44,9 +47,47 @@ export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
  *   codexRulesInstallDirectory: string,
  *   cursorInstallDirectory: string,
  *   cursorRulesInstallDirectory: string,
+ *   agentsHome: string,
+ *   skillsInstallDirectory: string,
+ *   agentsInstallDirectory: string,
+ *   skillsLookupDirectory: string,
+ *   agentsLookupDirectory: string,
  * }} InstallRootResolution
  */
 
+/**
+ * Resolve the canonical skills/agents home for one managed Claude root.
+ *
+ * When the managed root's base name is `.claude`, the agents home is the sibling
+ * `.agents` directory (so `~/.claude` pairs with `~/.agents`). Any other managed
+ * root — a named profile directory or an explicit `--target` — pairs with a
+ * sibling named `<root-name>.agents`, so two profile directories never share one
+ * agents home.
+ *
+ * @param {string} managedRoot Absolute managed Claude root.
+ * @returns {string} Absolute agents home.
+ */
+export function resolveAgentsHome(managedRoot) {
+    const resolvedManagedRoot = resolve(managedRoot);
+    const parentDirectory = dirname(resolvedManagedRoot);
+    const managedBaseName = basename(resolvedManagedRoot);
+    if (isClaudeDirectoryBaseName(managedBaseName)) {
+        return resolve(join(parentDirectory, DEFAULT_AGENTS_DIRECTORY_NAME));
+    }
+    return resolve(join(parentDirectory, `${managedBaseName}${DEFAULT_AGENTS_DIRECTORY_NAME}`));
+}
+
+/**
+ * @param {string} directoryName
+ * @returns {boolean}
+ */
+function isClaudeDirectoryBaseName(directoryName) {
+    if (process.platform === 'win32') {
+        return directoryName.toLowerCase() === DEFAULT_CLAUDE_DIRECTORY_NAME.toLowerCase();
+    }
+    return directoryName === DEFAULT_CLAUDE_DIRECTORY_NAME;
+}
+
 /**
  * Resolve the managed install root and declared external destinations.
  *
@@ -92,6 +133,11 @@ export function resolveInstallRoot(options = {}) {
     const cursorRulesInstallDirectory = resolve(
         join(cursorInstallDirectory, CURSOR_RULES_DIRECTORY_NAME),
     );
+    const agentsHome = resolveAgentsHome(managedRoot);
+    const skillsInstallDirectory = join(agentsHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const agentsInstallDirectory = join(agentsHome, MANAGED_AGENTS_DIRECTORY_NAME);
+    const skillsLookupDirectory = join(managedRoot, MANAGED_SKILLS_DIRECTORY_NAME);
+    const agentsLookupDirectory = join(managedRoot, MANAGED_AGENTS_DIRECTORY_NAME);
     return {
         managedRoot,
         source,
@@ -99,10 +145,19 @@ export function resolveInstallRoot(options = {}) {
         manifestFilePath: join(managedRoot, MANIFEST_FILE_NAME),
         mypyIniInstallPath,
         allDeclaredExternalPaths: [mypyIniInstallPath],
-        allDeclaredExternalDirectories: [codexRulesInstallDirectory, cursorInstallDirectory],
+        allDeclaredExternalDirectories: [
+            codexRulesInstallDirectory,
+            cursorInstallDirectory,
+            agentsHome,
+        ],
         codexRulesInstallDirectory,
         cursorInstallDirectory,
         cursorRulesInstallDirectory,
+        agentsHome,
+        skillsInstallDirectory,
+        agentsInstallDirectory,
+        skillsLookupDirectory,
+        agentsLookupDirectory,
     };
 }
 
@@ -131,8 +186,8 @@ export function isPathWithinManagedRoot(candidatePath, managedRoot) {
 
 /**
  * True when a write destination is allowed: inside the managed root, the
- * home-directory `.mypy.ini`, a file under the Codex rules directory, or a file
- * under the Cursor rules directory.
+ * home-directory `.mypy.ini`, a file under the Codex rules directory, a file
+ * under the Cursor rules directory, or a file under the agents home.
  *
  * @param {string} candidatePath
  * @param {InstallRootResolution} resolution

package/bin/resolve-package-managed-directory.mjs

@@ -0,0 +1,29 @@
+/**
+ * Resolve a managed content directory in a package source tree.
+ *
+ * This package keeps skills and agents under `.agents/<name>/`. A dependency
+ * package may still keep those trees at `<package-root>/<name>/`. Callers pass
+ * the package root and the managed directory name (`skills` or `agents`); this
+ * helper returns the directory that exists.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_AGENTS_HOME_DIRECTORY_NAME } from './install-constants.mjs';
+
+/**
+ * @param {string} sourceRoot Package root that may hold `.agents/<name>` or `<name>`.
+ * @param {string} directoryName Managed directory name (`skills` or `agents`).
+ * @returns {string} Absolute source directory to copy from.
+ */
+export function resolvePackageManagedDirectory(sourceRoot, directoryName) {
+    const agentsHomeDirectory = join(
+        sourceRoot,
+        PACKAGE_AGENTS_HOME_DIRECTORY_NAME,
+        directoryName,
+    );
+    if (existsSync(agentsHomeDirectory)) {
+        return agentsHomeDirectory;
+    }
+    return join(sourceRoot, directoryName);
+}

package/bin/resolve-package-managed-directory.test.mjs

@@ -0,0 +1,97 @@
+/**
+ * Package-source layout: skills and agents live under `.agents`, and
+ * `.claude/skills` / `.claude/agents` are directory pointers to that home.
+ */
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    mkdtempSync,
+    realpathSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    MANAGED_AGENTS_DIRECTORY_NAME,
+    MANAGED_SKILLS_DIRECTORY_NAME,
+    PACKAGE_AGENTS_HOME_DIRECTORY_NAME,
+} from './install-constants.mjs';
+import { resolvePackageManagedDirectory } from './resolve-package-managed-directory.mjs';
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const CANONICAL_SKILL_NAME = 'privacy-hygiene';
+const CANONICAL_AGENT_FILE_NAME = 'clean-coder.md';
+
+test('prefers the .agents tree when both layouts exist', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-src-agents-'));
+    try {
+        const agentsHomeSkills = join(
+            sourceRoot, PACKAGE_AGENTS_HOME_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME,
+        );
+        const packageRootSkills = join(sourceRoot, MANAGED_SKILLS_DIRECTORY_NAME);
+        mkdirSync(agentsHomeSkills, { recursive: true });
+        mkdirSync(packageRootSkills, { recursive: true });
+        writeFileSync(join(agentsHomeSkills, 'marker.txt'), 'canonical\n');
+        writeFileSync(join(packageRootSkills, 'marker.txt'), 'legacy\n');
+        assert.equal(
+            resolvePackageManagedDirectory(sourceRoot, MANAGED_SKILLS_DIRECTORY_NAME),
+            agentsHomeSkills,
+        );
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+    }
+});
+
+test('falls back to the package-root tree when .agents does not carry it', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-src-legacy-'));
+    try {
+        const packageRootSkills = join(sourceRoot, MANAGED_SKILLS_DIRECTORY_NAME);
+        mkdirSync(packageRootSkills, { recursive: true });
+        assert.equal(
+            resolvePackageManagedDirectory(sourceRoot, MANAGED_SKILLS_DIRECTORY_NAME),
+            packageRootSkills,
+        );
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+    }
+});
+
+test('live package source keeps skills and agents under .agents with .claude pointers', () => {
+    const canonicalSkills = join(
+        PACKAGE_ROOT, PACKAGE_AGENTS_HOME_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME,
+    );
+    const canonicalAgents = join(
+        PACKAGE_ROOT, PACKAGE_AGENTS_HOME_DIRECTORY_NAME, MANAGED_AGENTS_DIRECTORY_NAME,
+    );
+    const lookupSkills = join(PACKAGE_ROOT, '.claude', MANAGED_SKILLS_DIRECTORY_NAME);
+    const lookupAgents = join(PACKAGE_ROOT, '.claude', MANAGED_AGENTS_DIRECTORY_NAME);
+
+    assert.equal(
+        resolvePackageManagedDirectory(PACKAGE_ROOT, MANAGED_SKILLS_DIRECTORY_NAME),
+        canonicalSkills,
+    );
+    assert.equal(
+        resolvePackageManagedDirectory(PACKAGE_ROOT, MANAGED_AGENTS_DIRECTORY_NAME),
+        canonicalAgents,
+    );
+    assert.equal(
+        existsSync(join(canonicalSkills, CANONICAL_SKILL_NAME, 'SKILL.md')),
+        true,
+    );
+    assert.equal(
+        existsSync(join(canonicalAgents, CANONICAL_AGENT_FILE_NAME)),
+        true,
+    );
+    assert.equal(existsSync(join(PACKAGE_ROOT, MANAGED_SKILLS_DIRECTORY_NAME)), false);
+    assert.equal(existsSync(join(PACKAGE_ROOT, MANAGED_AGENTS_DIRECTORY_NAME)), false);
+    assert.equal(lstatSync(lookupSkills).isSymbolicLink(), true);
+    assert.equal(lstatSync(lookupAgents).isSymbolicLink(), true);
+    assert.equal(realpathSync(lookupSkills), realpathSync(canonicalSkills));
+    assert.equal(realpathSync(lookupAgents), realpathSync(canonicalAgents));
+});

package/hooks/blocking/hedging_language_blocker.py

@@ -49,6 +49,7 @@ from observability.prose_matcher_advisory import emit_advisory_candidate  # noqa
 PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 RESEARCH_MODE_SKILL_SEARCH_PATHS = [
+    os.path.join(PLUGIN_ROOT, ".agents", "skills", "research-mode", "SKILL.md"),
     os.path.join(PLUGIN_ROOT, "skills", "research-mode", "SKILL.md"),
     os.path.join(os.path.expanduser("~"), ".claude", "skills", "research-mode", "SKILL.md"),
     os.path.join(os.path.expanduser("~"), ".claude", "plugins", "marketplaces", "claude-deep-research", "skills", "research-mode", "SKILL.md"),

package/hooks/blocking/orchestrator_refresh_reschedule_gate.py

@@ -25,6 +25,7 @@ if _hooks_dir not in sys.path:
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.orchestrator_refresh_reschedule_gate_constants import (  # noqa: E402
     ALL_HOME_SKILLS_RELATIVE_PARTS,
+    ALL_PACKAGE_AGENTS_SKILL_SCRIPTS_RELATIVE_PARTS,
     ALL_SCHEDULE_TOOL_NAMES,
     ALL_SKILL_SCRIPTS_RELATIVE_PARTS,
     CALLING_HOOK_NAME,
@@ -51,14 +52,17 @@ def _candidate_skill_script_directories() -> list[Path]:
     """
     all_candidates: list[Path] = []
     plugin_root = os.environ.get(PLUGIN_ROOT_ENV_VAR)
+    relative_skill_script_layouts = (
+        ALL_PACKAGE_AGENTS_SKILL_SCRIPTS_RELATIVE_PARTS,
+        ALL_SKILL_SCRIPTS_RELATIVE_PARTS,
+    )
     if plugin_root:
-        all_candidates.append(
-            Path(plugin_root).joinpath(*ALL_SKILL_SCRIPTS_RELATIVE_PARTS)
-        )
+        plugin_root_path = Path(plugin_root)
+        for each_relative_parts in relative_skill_script_layouts:
+            all_candidates.append(plugin_root_path.joinpath(*each_relative_parts))
     package_hooks_parent = Path(__file__).resolve().parents[2]
-    all_candidates.append(
-        package_hooks_parent.joinpath(*ALL_SKILL_SCRIPTS_RELATIVE_PARTS)
-    )
+    for each_relative_parts in relative_skill_script_layouts:
+        all_candidates.append(package_hooks_parent.joinpath(*each_relative_parts))
     all_candidates.append(Path.home().joinpath(*ALL_HOME_SKILLS_RELATIVE_PARTS))
     return all_candidates
 

package/hooks/blocking/test_code_rules_command_dispatch.py

@@ -79,7 +79,7 @@ def test_ignores_single_word_command_literal() -> None:
 
 
 def test_ignores_file_outside_hooks_blocking() -> None:
-    other_path = "packages/claude-dev-env/skills/thing/helper.py"
+    other_path = "packages/claude-dev-env/.agents/skills/thing/helper.py"
     assert check_unanchored_command_dispatch(UNANCHORED_SOURCE, other_path) == []