claude-dev-env 2.15.0 → 2.16.0

package/.agents/skills/run-claude-dev-env/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: run-claude-dev-env
+description: Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.
+---
+
+`claude-dev-env` is the npm-distributed installer that copies this repo's rules, hooks, commands, and docs into `~/.claude/`, copies skills and agents into `~/.agents/`, publishes directory pointers at `~/.claude/skills` and `~/.claude/agents`, and merges its hook entries into `~/.claude/settings.json`. Its entry point is `bin/install.mjs`. Drive it with the smoke driver at `.claude/skills/run-claude-dev-env/driver.mjs`, which runs the installer against a throwaway sandbox home directory so a run never touches the real `~/.claude/` or `~/.agents/`.
+
+All paths below are written from the `packages/claude-dev-env/` directory.
+
+## Prerequisites
+
+The installer needs three tools on `PATH`:
+
+- **Node.js 18+** — the installer is an ES module (verified on Node 22.17).
+- **Python 3.8+** — the installer bakes a Python interpreter into every hook command and aborts if it finds none. On Windows it skips the Microsoft Store stub (verified `py -3` → Python 3.13.5).
+- **git** — the installer reads `git status` to guard against installing from a conflicted source, and sets a global git hooks path.
+
+```bash
+node --version
+git --version
+py -3 --version    # POSIX: python3 --version
+```
+
+On a fresh Ubuntu container the three come from `sudo apt-get install -y nodejs python3 git`.
+
+## Run (agent path) — the smoke driver
+
+The driver is the handle to reach for first. It spawns the installer against a fresh temp home directory with `HOME`, `USERPROFILE`, and `GIT_CONFIG_GLOBAL` all redirected, runs the `--help` → install → `--uninstall` lifecycle, asserts the result of each step against the sandbox tree, then deletes the sandbox. It works the same on Windows and POSIX.
+
+```bash
+node .claude/skills/run-claude-dev-env/driver.mjs
+```
+
+Expected tail:
+
+```
+21/21 checks passed.
+ALL CHECKS PASSED
+```
+
+The driver proves a full install lands skills under `<sandbox>/.agents/skills` with a directory pointer at `<sandbox>/.claude/skills`, lands agents the same way, lands hook scripts, rules, the `CLAUDE.md` hub, a populated `settings.json`, and a tracking manifest, and that `--uninstall` removes every manifest-tracked file. The real `~/.claude/`, `~/.agents/`, and the real global git config stay untouched. Exit code is 0 only when all checks hold.
+
+## Run (human path) — install for real
+
+These write into your real `~/.claude/` and set a global git hooks path. Run them only when you mean to install on this machine.
+
+```bash
+node bin/install.mjs --help         # usage only, no side effects
+node bin/install.mjs                # install every group
+node bin/install.mjs --only core    # install one or more named groups
+node bin/install.mjs --update       # remove manifest-tracked files, then reinstall
+node bin/install.mjs --uninstall    # remove every installed file
+```
+
+Groups: `core`, `journal`, and the discovered `prompt-generator` dependency group. Run `node bin/install.mjs --help` for the live list. The published package runs the same entry point as `npx claude-dev-env`.
+
+## Test
+
+```bash
+npm test
+```
+
+Runs `node --test` over `bin/*.test.mjs` and `.agents/skills/**/*.test.mjs` with Node's built-in test runner — no extra dependency, no network. Expected: `# fail 0`, with the pass count growing as tests are added.
+
+## Gotchas
+
+- **The install target is `os.homedir()/.claude` with no override flag** (the `CLAUDE_HOME` constant in `bin/install.mjs`). To drive the installer without overwriting your real config, redirect the home directory: set `USERPROFILE` (Windows) and `HOME` (POSIX) to a temp dir. The driver does this for you.
+- **The installer reaches outside `~/.claude/`.** It writes skills and agents under `~/.agents/`, runs `git config --global core.hooksPath ...`, which applies to every git repo on the machine, and it writes `~/.mypy.ini`. The driver isolates those writes by pointing `GIT_CONFIG_GLOBAL` at a sandbox file and redirecting the home directory.
+- **git "dubious ownership" aborts the install.** The source-conflict guard runs `git status`; when the checkout sits on a path git distrusts (a UNC network share owned by another account), git exits 128 with a dubious-ownership message that the installer rethrows. The driver seeds its sandbox git config with `safe.directory = *` so the guard runs. For a real install on such a checkout, add the exception: `git config --global --add safe.directory '<repo-path>'`.
+- **`npm install` at the repo root fails on a Windows network-share checkout.** npm symlinks the workspace package into root `node_modules` and the share rejects the symlink (`UNKNOWN ... symlink`, errno -4094). The package's own `node_modules` already carries its single dependency, so the driver and tests run without it. The installer also keeps working when `@jl-cmd/prompt-generator` cannot resolve — it skips that group with a warning (`discoverDependencyGroups` in `bin/install.mjs`).
+- **Microsoft Store Python is rejected on Windows.** The installer skips any interpreter under a `WindowsApps` directory because that stub cannot run as a hook subprocess (`isWindowsStorePythonStub` in `bin/install.mjs`). Install Python from python.org if detection fails.
+
+## Troubleshooting
+
+- **`ERROR: No usable Python 3 found`**: no `py -3` / `python3` / `python` resolves to a non-Store Python 3. Install Python 3.8+ from python.org and reopen the shell.
+- **`fatal: detected dubious ownership in repository`**: add the `safe.directory` exception shown above, then rerun.
+- **`ERROR: settings.json is malformed JSON`**: `~/.claude/settings.json` has a syntax error; fix the JSON and rerun.
+
+## Files
+
+- `SKILL.md` — this page: the agent path (the driver), the human install path, the test command, gotchas, and troubleshooting.
+- `driver.mjs` — the smoke harness that drives `bin/install.mjs` against a sandbox home directory. Run it; you do not need to read it. It sits beside this file at `.claude/skills/run-claude-dev-env/driver.mjs`.
+
+The `/run` skill auto-discovers this skill when asked to run, install, or test `claude-dev-env`.

package/.agents/skills/run-claude-dev-env/driver.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Smoke driver for the claude-dev-env installer.
+ *
+ * The installer (bin/install.mjs) writes into os.homedir()/.claude and
+ * os.homedir()/.agents and has
+ * three global side effects: it copies files under ~/.claude/ and ~/.agents/, sets
+ * `git config --global core.hooksPath`, and writes ~/.mypy.ini. There is no
+ * flag to redirect the target, so this driver isolates every side effect by
+ * spawning the installer with HOME, USERPROFILE, and GIT_CONFIG_GLOBAL all
+ * pointed at a throwaway sandbox directory. Node's os.homedir() follows
+ * USERPROFILE on Windows and HOME on POSIX, so setting both redirects the
+ * install target on either platform without touching the real ~/.claude/.
+ *
+ * The isolated GIT_CONFIG_GLOBAL is seeded with `safe.directory = *` so the
+ * installer's `git status` source-conflict guard runs even when the checkout
+ * lives somewhere git flags as dubious ownership (for example a UNC network
+ * share), while the installer's `git config --global core.hooksPath` write
+ * still lands only in the sandbox config.
+ *
+ * It runs the three lifecycle commands an agent cares about — `--help`, a full
+ * install, and `--uninstall` — and asserts the observable result of each
+ * against the sandbox tree. Exit code 0 means every assertion held.
+ *
+ * Usage: node .claude/skills/run-claude-dev-env/driver.mjs
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    existsSync,
+    lstatSync,
+    readFileSync,
+    realpathSync,
+    writeFileSync,
+    readdirSync,
+    rmSync,
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const DRIVER_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(DRIVER_DIRECTORY, '..', '..', '..');
+const INSTALL_ENTRY = join(PACKAGE_ROOT, 'bin', 'install.mjs');
+
+const checks = [];
+
+function record(label, passed, detail) {
+    checks.push({ label, passed, detail });
+    const mark = passed ? 'PASS' : 'FAIL';
+    console.log(`  [${mark}] ${label}${detail ? ` — ${detail}` : ''}`);
+}
+
+function collectFilesRecursive(directory) {
+    const collected = [];
+    if (!existsSync(directory)) return collected;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const entryPath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            collected.push(...collectFilesRecursive(entryPath));
+        } else {
+            collected.push(entryPath);
+        }
+    }
+    return collected;
+}
+
+function runInstaller(sandboxHome, installerArguments) {
+    const gitConfigGlobal = join(sandboxHome, '.gitconfig-sandbox');
+    const result = spawnSync(process.execPath, [INSTALL_ENTRY, ...installerArguments], {
+        cwd: PACKAGE_ROOT,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: sandboxHome,
+            USERPROFILE: sandboxHome,
+            GIT_CONFIG_GLOBAL: gitConfigGlobal,
+        },
+    });
+    return result;
+}
+
+function main() {
+    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-driver-'));
+    const claudeHome = join(sandboxHome, '.claude');
+    writeFileSync(join(sandboxHome, '.gitconfig-sandbox'), '[safe]\n\tdirectory = *\n');
+    console.log(`Sandbox HOME: ${sandboxHome}`);
+    console.log(`Install entry: ${INSTALL_ENTRY}\n`);
+
+    try {
+        console.log('Step 1: node bin/install.mjs --help');
+        const help = runInstaller(sandboxHome, ['--help']);
+        record('--help exits 0', help.status === 0, `exit=${help.status}`);
+        record('--help prints usage', /Usage:/.test(help.stdout), '');
+        record('--help wrote nothing to ~/.claude', !existsSync(claudeHome), '');
+
+        console.log('\nStep 2: node bin/install.mjs (full install)');
+        const install = runInstaller(sandboxHome, []);
+        if (install.status !== 0) {
+            console.log(install.stdout);
+            console.log(install.stderr);
+        }
+        record('install exits 0', install.status === 0, `exit=${install.status}`);
+
+        const manifestPath = join(claudeHome, '.claude-dev-env-manifest.json');
+        let manifest = null;
+        if (existsSync(manifestPath)) {
+            manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        record('manifest written', manifest !== null, manifestPath);
+        record(
+            'manifest names this package',
+            manifest?.package === 'claude-dev-env',
+            manifest ? `package=${manifest.package} version=${manifest.version}` : 'missing',
+        );
+        record(
+            'manifest tracks installed files',
+            Array.isArray(manifest?.files) && manifest.files.length > 0,
+            manifest?.files ? `${manifest.files.length} files` : 'none',
+        );
+
+        const skillsDirectory = join(claudeHome, 'skills');
+        const agentsHomeSkillsDirectory = join(sandboxHome, '.agents', 'skills');
+        const installedSkills = existsSync(skillsDirectory)
+            ? readdirSync(skillsDirectory, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+            : [];
+        record('skills installed', installedSkills.length > 0, `${installedSkills.length} skill dirs`);
+        record(
+            'skills live under ~/.agents/skills',
+            existsSync(agentsHomeSkillsDirectory)
+                && installedSkills.some((entry) => existsSync(join(agentsHomeSkillsDirectory, entry.name))),
+            agentsHomeSkillsDirectory,
+        );
+        record(
+            '~/.claude/skills is a directory pointer',
+            existsSync(skillsDirectory) && lstatSync(skillsDirectory).isSymbolicLink(),
+            skillsDirectory,
+        );
+        const sampleSkillName = installedSkills.find((entry) => existsSync(join(skillsDirectory, entry.name, 'SKILL.md')))?.name;
+        if (sampleSkillName) {
+            const lookupSkillPath = join(skillsDirectory, sampleSkillName, 'SKILL.md');
+            const canonicalSkillPath = join(agentsHomeSkillsDirectory, sampleSkillName, 'SKILL.md');
+            record(
+                'skill files match through the lookup pointer',
+                existsSync(lookupSkillPath)
+                    && existsSync(canonicalSkillPath)
+                    && realpathSync(lookupSkillPath) === realpathSync(canonicalSkillPath),
+                sampleSkillName,
+            );
+        } else {
+            record('skill files match through the lookup pointer', false, 'no skill dirs');
+        }
+
+        const agentsLookupDirectory = join(claudeHome, 'agents');
+        const agentsHomeAgentsDirectory = join(sandboxHome, '.agents', 'agents');
+        record(
+            'agents live under ~/.agents/agents',
+            existsSync(agentsHomeAgentsDirectory)
+                && readdirSync(agentsHomeAgentsDirectory).some((name) => name.endsWith('.md')),
+            agentsHomeAgentsDirectory,
+        );
+        record(
+            '~/.claude/agents is a directory pointer',
+            existsSync(agentsLookupDirectory) && lstatSync(agentsLookupDirectory).isSymbolicLink(),
+            agentsLookupDirectory,
+        );
+
+        const hookFiles = collectFilesRecursive(join(claudeHome, 'hooks')).filter((file) =>
+            file.endsWith('.py'),
+        );
+        record('hook scripts installed', hookFiles.length > 0, `${hookFiles.length} .py files`);
+
+        const ruleFiles = existsSync(join(claudeHome, 'rules'))
+            ? readdirSync(join(claudeHome, 'rules')).filter((name) => name.endsWith('.md'))
+            : [];
+        record('rules installed', ruleFiles.length > 0, `${ruleFiles.length} .md files`);
+
+        record('CLAUDE.md hub installed', existsSync(join(claudeHome, 'CLAUDE.md')), '');
+
+        const settingsPath = join(claudeHome, 'settings.json');
+        let managedHookCount = 0;
+        if (existsSync(settingsPath)) {
+            const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+            for (const matcherGroups of Object.values(settings.hooks ?? {})) {
+                for (const group of matcherGroups) {
+                    for (const hook of group.hooks ?? []) {
+                        if (hook.command.replace(/\\/g, '/').includes('/.claude/hooks')) {
+                            managedHookCount += 1;
+                        }
+                    }
+                }
+            }
+        }
+        record('settings.json carries managed hooks', managedHookCount > 0, `${managedHookCount} hook commands`);
+
+        const gitConfigGlobalPath = join(sandboxHome, '.gitconfig-sandbox');
+        const gitHooksPathRedirectedIntoSandbox =
+            existsSync(gitConfigGlobalPath) &&
+            readFileSync(gitConfigGlobalPath, 'utf8').replace(/\\/g, '/').includes('/.claude/hooks/git-hooks');
+        record(
+            'global git hooksPath isolated to sandbox',
+            gitHooksPathRedirectedIntoSandbox,
+            'GIT_CONFIG_GLOBAL kept the real ~/.gitconfig untouched',
+        );
+
+        const sampleInstalledFile = manifest?.files?.find((file) => existsSync(file));
+
+        console.log('\nStep 3: node bin/install.mjs --uninstall');
+        const uninstall = runInstaller(sandboxHome, ['--uninstall']);
+        if (uninstall.status !== 0) {
+            console.log(uninstall.stdout);
+            console.log(uninstall.stderr);
+        }
+        record('uninstall exits 0', uninstall.status === 0, `exit=${uninstall.status}`);
+        record('manifest removed', !existsSync(manifestPath), '');
+        record(
+            'tracked file removed',
+            sampleInstalledFile ? !existsSync(sampleInstalledFile) : false,
+            sampleInstalledFile ? sampleInstalledFile : 'no sample file captured',
+        );
+    } finally {
+        rmSync(sandboxHome, { recursive: true, force: true });
+        console.log(`\nSandbox removed: ${sandboxHome}`);
+    }
+
+    const failures = checks.filter((check) => !check.passed);
+    console.log(`\n${checks.length - failures.length}/${checks.length} checks passed.`);
+    if (failures.length > 0) {
+        console.log('FAILED:');
+        for (const failure of failures) {
+            console.log(`  - ${failure.label}`);
+        }
+        process.exit(1);
+    }
+    console.log('ALL CHECKS PASSED');
+}
+
+main();

package/.agents/skills/session-log/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/session-tidy/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/skill-builder/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/skill-builder/references/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/{skills → .agents/skills}/skill-builder/references/deterministic-elements.md

@@ -1,6 +1,6 @@
 # Deterministic skill elements
 
-Source: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (scripts, progressive disclosure), [Lessons from Building Claude Code](thariq-x-post-skills.json), repo skill conventions (`skills/CLAUDE.md`), `docs/CODE_RULES.md`, host task tools (`TaskCreate`, `TodoWrite`, and equivalents).
+Source: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (scripts, progressive disclosure), [Lessons from Building Claude Code](thariq-x-post-skills.json), repo skill conventions (`skills/.claude/CLAUDE.md`), `docs/CODE_RULES.md`, host task tools (`TaskCreate`, `TodoWrite`, and equivalents).
 
 ## Contents
 

package/.agents/skills/skill-builder/templates/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/skill-builder/workflows/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/{skills → .agents/skills}/split-pr/reference/proposal-format.md

@@ -12,4 +12,4 @@ Each slice carries `id`, `title` (exactly one conventional prefix), `layer`
 (one of `config` / `backend` / `frontend` / `tests` / `docs` / `other`), and
 `all_paths`. Every path in `all_changed_paths` is assigned to exactly one
 slice. Titles are normalized with `split_pr_title.normalize_split_title`.
-Layer tokens follow `ALL_LAYER_ORDER` in `packages/claude-dev-env/skills/split-pr/scripts/config/plan_constants.py`.
+Layer tokens follow `ALL_LAYER_ORDER` in `packages/claude-dev-env/.agents/skills/split-pr/scripts/config/plan_constants.py`.

package/.agents/skills/task-build/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/update/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/_shared/advisor/reference/sol-rung.md

@@ -19,7 +19,7 @@ Flag on: run the Codex preflight first —
 python ~/.claude/skills/codex-review/scripts/codex_usage_probe.py
 ```
 
-Repo home: `packages/claude-dev-env/skills/codex-review/scripts/`.
+Repo home: `packages/claude-dev-env/.agents/skills/codex-review/scripts/`.
 
 The shared entry point is `~/.claude/_shared/advisor/scripts/codex_sol_advisor.py`; it calls the installed probe and owns Sol bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
 

package/_shared/advisor/scripts/tests/test_codex_sol_advisor.py

@@ -475,7 +475,7 @@ def test_bind_runs_probe_then_codex_with_read_only_xhigh_settings() -> None:
 
 
 def test_team_advisor_path_preserves_sol_routing_fields() -> None:
-    team_advisor_path = SCRIPTS_ROOT.parents[2] / "skills" / "team-advisor" / "SKILL.md"
+    team_advisor_path = SCRIPTS_ROOT.parents[2] / ".agents" / "skills" / "team-advisor" / "SKILL.md"
     sol_rung_path = SCRIPTS_ROOT.parent / "reference" / "sol-rung.md"
     assert "advisor-protocol.md" in team_advisor_path.read_text(encoding="utf-8")
     sol_rung = sol_rung_path.read_text(encoding="utf-8")

package/_shared/advisor/scripts/tier_model_ids.py

@@ -30,8 +30,12 @@ from collections.abc import Mapping
 from pathlib import Path
 
 _config_directory = str(Path(__file__).resolve().parent / "config")
-if _config_directory not in sys.path:
-    sys.path.insert(0, _config_directory)
+sys.path[:] = [
+    each_existing_entry
+    for each_existing_entry in sys.path
+    if each_existing_entry != _config_directory
+]
+sys.path[:0] = [_config_directory]
 
 from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
     ALL_CLI_MODEL_ID_BY_TIER,

package/_shared/pr-loop/code-rules-gate.md

@@ -9,7 +9,7 @@ Canonical: `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py` after install.
 Workflows reference it via:
 - all skills (bugteam, pr-converge): `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
 
-Cross-skill path traversal works because every skill installs as a flat top-level dir under `~/.claude/skills/` and `_shared/` lives alongside `skills/` under `~/.claude/`.
+Cross-skill path traversal works because every skill installs as a flat top-level dir under the skills lookup path (`~/.claude/skills/`, a directory pointer to `~/.agents/skills/`) and `_shared/` lives alongside `skills/` under `~/.claude/`.
 
 ## Invocation
 

package/bin/AGENTS.md

@@ -1,23 +1,28 @@
 # bin
 
-The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, writes `~/.mypy.ini` under the process home, and copies Codex exec-policy files into `~/.codex/rules` (`CODEX_HOME/rules` when that variable is set), and generates Cursor `.mdc` files into `~/.cursor/rules` from the installed Claude rules.
+The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), copies skills and agents into the agents home (`~/.agents/` for the default root) and publishes directory pointers at `skills/` and `agents/` under the managed root, merges hook entries into that root's `settings.json`, installs Git hooks, writes `~/.mypy.ini` under the process home, and copies Codex exec-policy files into `~/.codex/rules` (`CODEX_HOME/rules` when that variable is set), and generates Cursor `.mdc` files into `~/.cursor/rules` from the installed Claude rules.
 
 ## Files
 
 | File | Purpose |
 |---|---|
-| `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
-| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` plus files under the Codex rules directory and the Cursor home |
+| `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (publish skill/agent lookup pointers, copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the agents home, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
+| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, sibling `.agents` home (or `<root>.agents` for a named profile), separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` plus files under the Codex rules directory, the Cursor home, and the agents home |
+| `resolve-package-managed-directory.mjs` | Package-source resolver: skills and agents under `.agents/<name>/`, with a package-root `<name>/` fallback for dependency packages |
+| `resolve-package-managed-directory.test.mjs` | Real-filesystem tests for the source resolver plus the live package `.agents` trees and `.claude` pointers |
+| `publish-directory-pointer.mjs` | Directory-pointer helper: POSIX symlink or Windows junction from a Claude lookup path to the agents home; relocates a real directory at the lookup path into the target |
+| `publish-directory-pointer.test.mjs` | Real-filesystem tests for pointer create, refresh, relocate, and unlink |
 | `select-install-targets.mjs` | Pure target selection for main-default, explicit `--target`, and `--profile`/`--profiles`; rejects ambiguous or duplicate targets; builds per-target manifest records with `targetIdentity` and `managedRoot` |
 | `install-plan.mjs` | Read-only install and uninstall plans: install preflight (managed root, source conflicts, Python, settings when hooks install) and uninstall preflight (settings JSON before removal, removable vs skipped manifest records), freezes plans E2/F execute |
 | `install-transaction.mjs` | Install, update, and uninstall transaction journal: captures prior settings, manifest, managed files, and `core.hooksPath`, restores them on failure, and supports fault injection phases for recovery tests |
 | `install.transaction.test.mjs` | Unit and sandbox installer tests for snapshot/restore and fault phases (`after_file_staging`, `after_settings_write`, `after_git_config`, `after_manifest_write`) |
 | `install.uninstall-transaction.test.mjs` | Uninstall plan preflight and recovery: malformed/non-object settings fail before removal, each fault phase restores files/settings/manifest/`core.hooksPath`, retry succeeds, selected-root containment |
-| `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, and the install.mjs import smoke check |
+| `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, agents-home pairing, and the install.mjs import smoke check |
+| `install.agents-home.test.mjs` | End-to-end tests that a sandbox install writes skills and agents under `.agents` and publishes `.claude/skills` and `.claude/agents` as directory pointers |
 | `install.codex-rules.test.mjs` | Tests that Codex exec-policy files copy to `~/.codex/rules`, honor `CODEX_HOME`, skip `--only journal`, and uninstall without touching `default.rules` |
 | `install.cursor-rules.test.mjs` | Tests that Cursor `.mdc` files generate into `~/.cursor/rules` from Claude rules, skip `--only journal`, and leave a local extra `.mdc` in place |
-| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes, plus the Codex home and rules directory names `resolve-install-root.mjs` uses |
-| `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
+| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `PACKAGE_AGENTS_HOME_DIRECTORY_NAME` for the `.agents` source home, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_AGENTS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under the agents home — read by the copy loops, the pointer publisher, and the prunes alike — `MANAGED_HOOKS_DIRECTORY_NAME` for the hooks tree under `~/.claude`, `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes, plus the Codex home and rules directory names `resolve-install-root.mjs` uses |
+| `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.agents/skills` |
 | `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
 | `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
 | `install_mypy_ini.mjs` | Writes `~/.mypy.ini` with settings that make mypy find the hooks package and enforce strict type checking |
@@ -42,9 +47,9 @@ The decision reads the destination directory's entry names, cached one listing p
 
 ## Retired-skill prune
 
-The full-install prune renames a retired skill directory into a timestamped backup rather than deleting it. Each pruned directory is renamed to `~/.claude/.claude-dev-env-pruned/<timestamp>/skills/<skill-name>/`, a backup root outside `~/.claude/skills` so a backed-up directory is never re-discovered as a skill. The `skills/` segment mirrors `~/.claude`, matching the layout the stale-file prune writes, so one recovery point reads as a copy of the tree it came from. One run shares one timestamped root, so a run leaves one recovery point. A rename that fails leaves the directory in place with a logged warning and never falls back to deletion, so a prune failure costs at most a cosmetic leftover.
+The full-install prune renames a retired skill directory into a timestamped backup rather than deleting it. Each pruned directory is renamed to `~/.claude/.claude-dev-env-pruned/<timestamp>/skills/<skill-name>/`, a backup root outside `~/.agents/skills` so a backed-up directory is never re-discovered as a skill. The `skills/` segment matches the layout the stale-file prune writes, so one recovery point reads as a copy of the tree it came from. One run shares one timestamped root, so a run leaves one recovery point. A rename that fails leaves the directory in place with a logged warning and never falls back to deletion, so a prune failure costs at most a cosmetic leftover.
 
-Matching is by directory name alone, so a user-authored directory whose name collides with a retired skill is backed up as if it were that skill. A directory is pruned when the prior install's manifest recorded it or the ever-shipped set names it, and the current install did not just write it. A name absent from all three of those sets, together with `~/.claude/skills/_shared`, is left in place. Recovery of a wrongly-matched directory runs until the next pruning install, which keeps its own backup and retires the rest.
+Matching is by directory name alone, so a user-authored directory whose name collides with a retired skill is backed up as if it were that skill. A directory is pruned when the prior install's manifest recorded it or the ever-shipped set names it, and the current install did not just write it. A name absent from all three of those sets, together with `~/.agents/skills/_shared`, is left in place. Recovery of a wrongly-matched directory runs until the next pruning install, which keeps its own backup and retires the rest.
 
 ## Stale-file prune
 
@@ -52,7 +57,7 @@ A full install also moves aside a file under a managed root that the run leaves
 
 Nothing moves unless a prior install recorded it. That single rule is what makes covering ten roots as safe as covering one: the installer reads the file list from `~/.claude/.claude-dev-env-manifest.json`, subtracts every file the run copied across all source roots, and moves what remains.
 
-The prune runs once per root, each call confined to its own root. Per-root iteration gives the containment guard and the emptied-parent walk the root that owns each file, and it settles `_shared`: `~/.claude/_shared` and `~/.claude/skills/_shared` are distinct absolute paths, so the `_shared` call and the `skills` call each see their own files and no path enters two diffs. Each root's content lands under `~/.claude/.claude-dev-env-pruned/<timestamp>/<root-name>/<relative>`, so the backup mirrors `~/.claude`. Every prune in a run shares that one timestamped root. A recorded path under no managed root — `~/.claude/CLAUDE.md`, `settings.json`, the manifest itself, and the `~/.mypy.ini` that sits in the home directory beside `~/.claude` — reaches no root's diff and stays where it is. The install summary reports the skills root's own count on the `skills:` line and the sum across roots on its own line.
+The prune runs once per root, each call confined to its own root. Per-root iteration gives the containment guard and the emptied-parent walk the root that owns each file, and it settles `_shared`: `~/.claude/_shared` and `~/.agents/skills/_shared` are distinct absolute paths, so the `_shared` call and the `skills` call each see their own files and no path enters two diffs. Each root's content lands under `~/.claude/.claude-dev-env-pruned/<timestamp>/<root-name>/<relative>`. Every prune in a run shares that one timestamped root. A recorded path under no managed root — `~/.claude/CLAUDE.md`, `settings.json`, the manifest itself, and the `~/.mypy.ini` that sits in the home directory beside `~/.claude` — reaches no root's diff and stays where it is. The install summary reports the skills root's own count on the `skills:` line and the sum across roots on its own line.
 
 The manifest diff limits the move to files the installer itself wrote. Runtime-generated content — a Python `__pycache__` entry, a ruff cache, a log — and any file a user authored under a managed root stay in place, because no install recorded them. Path comparison ignores letter case on Windows and macOS, so a package shipping `README.md` over an installed `Readme.md` keeps the bytes the run just wrote. A directory or a link standing where the manifest records a file is skipped with a warning, so the mover never renames a whole tree and never follows a link out of `~/.claude`. A directory emptied by a move is removed, walking up to the root the file sat under. A move that fails logs a warning and leaves the file in place, so a prune failure costs at most a stale file. The installer records each such path in the fresh manifest when the file is still on disk, so the file stays inside the next full install's diff and gets another attempt.
 
@@ -80,7 +85,7 @@ A run that moves nothing sweeps nothing, so every recovery point the user holds
 
 `--uninstall` builds a read-only uninstall plan, captures a recovery snapshot, then removes each file the plan lists.
 
-Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory, or it sits under the Codex rules directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
+Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory, or it sits under the Codex rules directory, or it sits under the Cursor home, or it sits under the agents home. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
 
 The uninstall runs inside the same snapshot/restore journal as install: prior settings, manifest, managed files, and `core.hooksPath` restore when a later phase fails, so a retry starts from a complete ownership record. The journal is discarded only after a successful commit.
 
@@ -94,8 +99,8 @@ Every prune runs behind the same two gates: a full install, and every declared d
 
 | Export | Description |
 |---|---|
-| `CONTENT_DIRECTORIES` | Array of package subdirectory names copied verbatim to `~/.claude/` |
-| `MANAGED_TOP_LEVEL_DIRECTORY_NAMES` | The content directories plus `skills` and `hooks`; the stale-file prune walks it to give each root its own diff, and the uninstall purge reads it to find the root a recorded file belongs to |
+| `CONTENT_DIRECTORIES` | Array of package subdirectory names copied verbatim to `~/.claude/` (skills and agents are outside this list; they copy into the agents home) |
+| `MANAGED_TOP_LEVEL_DIRECTORY_NAMES` | The content directories plus `skills`, `agents`, and `hooks`; the stale-file prune walks it to give each root its own diff, and the uninstall purge reads it to find the root a recorded file belongs to |
 | `collectFiles(directory)` | Lists every file under a source directory, skipping the build-artifact names and extensions in `install-constants.mjs` |
 | `pythonCandidatesForPlatform(platform)` | Returns ordered Python interpreter candidates to probe; `py -3` first on Windows to avoid Microsoft Store alias issues |
 | `isWindowsStorePythonStub(path)` | Returns true when the path resolves to the non-spawnable WindowsApps stub |

package/bin/ever-shipped-skills.mjs

@@ -3,7 +3,7 @@
  *
  * The installer subtracts the skills the current package installs from this set
  * to learn which shipped skills have retired, so a full reinstall can remove a
- * retired skill left behind under ~/.claude/skills. Because the current set is
+ * retired skill left behind under ~/.agents/skills. Because the current set is
  * subtracted at runtime, restoring a retired skill to the package protects it
  * automatically — it re-enters the installed set and drops out of the retired
  * set on the next install.
@@ -12,7 +12,9 @@
  * installs from the npm tarball, which carries no source-repo history. Refresh
  * it by running, from the repository root:
  *
- *   git log --all --pretty=format: --name-only -- 'packages/claude-dev-env/skills/*\/SKILL.md' | sort -u
+ *   git log --all --pretty=format: --name-only -- \
+ *     'packages/claude-dev-env/.agents/skills/*\/SKILL.md' \
+ *     'packages/claude-dev-env/skills/*\/SKILL.md' | sort -u
  *
  * and pasting each distinct top-level skill directory name below.
  */
@@ -64,6 +66,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'remember',
     'research-mode',
     'reviewer-gates',
+    'run-claude-dev-env',
     'session-log',
     'session-tidy',
     'skill-builder',

package/bin/install-constants.mjs

@@ -44,18 +44,43 @@ export const SKIPPED_SOURCE_FILE_EXTENSIONS = new Set(['.pyc', '.pyo']);
 export const RUN_BACKUP_DIRECTORY_NAME_PATTERN =
     /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
 
+/**
+ * Package subdirectory that holds the canonical skill and agent source trees.
+ *
+ * This package keeps those trees at `<package-root>/.agents/skills` and
+ * `<package-root>/.agents/agents`. `packages/claude-dev-env/.claude/skills` and
+ * `.claude/agents` are directory pointers to that home. A dependency package
+ * may still keep `skills/` and `agents/` at its package root; the source
+ * resolver tries this directory first and falls back to the package-root name.
+ */
+export const PACKAGE_AGENTS_HOME_DIRECTORY_NAME = '.agents';
+
 /**
  * The directory name skill directories carry in a package source and under
- * `~/.claude`.
+ * the agents home.
  *
- * The copy loop reads `<package-root>/skills` and writes `~/.claude/skills`, the
- * dependency walk reads `<dependency-root>/skills`, the retired-skill prune reads
- * the installed directory, and the per-root stale-file prune names it as one of
- * its roots. One spelling serves every one of them, so the copy destination and
- * the prune target stay the same directory.
+ * The copy loop reads `<package-root>/.agents/skills` (or `<package-root>/skills`
+ * when a dependency still ships that layout) and writes `~/.agents/skills`.
+ * Claude Code still looks up skills at `~/.claude/skills`, which the installer
+ * publishes as a directory pointer to that agents-home folder. The dependency
+ * walk reads the resolved skills source, the retired-skill prune reads the
+ * installed directory through the pointer, and the per-root stale-file prune
+ * names it as one of its roots. One spelling serves every one of them, so the
+ * copy destination and the prune target stay the same directory.
  */
 export const MANAGED_SKILLS_DIRECTORY_NAME = 'skills';
 
+/**
+ * The directory name agent definition files carry in a package source and under
+ * the agents home.
+ *
+ * The copy loop reads `<package-root>/.agents/agents` (or `<package-root>/agents`
+ * when a dependency still ships that layout) and writes `~/.agents/agents`.
+ * Claude Code still looks up agents at `~/.claude/agents`, which the installer
+ * publishes as a directory pointer to that agents-home folder.
+ */
+export const MANAGED_AGENTS_DIRECTORY_NAME = 'agents';
+
 /**
  * The directory name hook scripts carry in a package source and under
  * `~/.claude`.

package/bin/install-plan.mjs

@@ -285,7 +285,12 @@ export function describeInstallMutations(plan) {
     if (plan.shouldPurgeBeforeReinstall) {
         allMutations.push('purge_managed_installation');
     }
-    allMutations.push('ensure_managed_root', 'copy_content_trees', 'copy_skills');
+    allMutations.push(
+        'ensure_managed_root',
+        'publish_directory_pointers',
+        'copy_content_trees',
+        'copy_skills',
+    );
     if (plan.shouldInstallHooks) {
         allMutations.push(
             'copy_hook_files',