claude-dev-env 2.15.1 → 2.17.0

package/_shared/pr-loop/scripts/tests/test_claude_permissions_common.py

@@ -1,4 +1,4 @@
-"""Tests for _shared permission helpers extracted from skills/bugteam/scripts/."""
+"""Tests for _shared permission helpers (historically extracted from bugteam scripts)."""
 
 import importlib.util
 import inspect

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -1,4 +1,4 @@
-"""Tests for shared code_rules_gate.py extracted from skills/bugteam/scripts/.
+"""Tests for shared code_rules_gate.py (historically extracted from bugteam scripts).
 
 Covers:
 - Module loads from _shared/pr-loop/scripts/ location

package/_shared/pr-loop/scripts/tests/test_fix_hookspath.py

@@ -1,4 +1,4 @@
-"""Tests for shared fix_hookspath.py extracted from skills/bugteam/scripts/.
+"""Tests for shared fix_hookspath.py (historically extracted from bugteam scripts).
 
 Covers:
 - removes a local-scope core.hooksPath override and re-runs preflight

package/_shared/pr-loop/state-schema.md

@@ -13,41 +13,33 @@ State each PR-loop workflow tracks across iterations. Workflows differ on persis
 | `starting_sha` | str | `git rev-parse HEAD` at workflow start |
 | `loop_comment_index` | dict | `{finding_id: {finding_comment_id, finding_comment_url, thread_node_id, fix_status, ...}}` (`thread_node_id` is the PR review thread node id — `PRRT_kwDOxxx` — captured at audit time when calling `get_review_comments`, used by `resolve_thread` at FIX time) |
 
-## Workflow-specific extensions
+## autoconverge (workflow and portable pacer)
 
-### bugteam
+Workflow runs hold round state in the workflow journal. On `pacer=portable`, the
+continuous driver seeds `pr-converge-state.json` under the job directory and
+advances phases through `portable_converge_driver.py`. Portable state carries
+`current_head`, `phase`, `codex_clean_at`, `codex_down`, `codex_required`, and
+pending `next` / `wait_seconds` stamps. Round shape and terminal gates are
+documented in
+[`../../.agents/skills/autoconverge/reference/convergence.md`](../../.agents/skills/autoconverge/reference/convergence.md).
+The machine readiness checklist is
+[`../../.agents/skills/autoconverge/reference/convergence-gates.md`](../../.agents/skills/autoconverge/reference/convergence-gates.md).
 
-Adds:
-- `team_name` — `bugteam-pr-<N>-<YYYYMMDDHHMMSS>` or `bugteam-<YYYYMMDDHHMMSS>` for multi-PR
-- `team_temp_dir` — absolute path resolved from `tempfile.gettempdir()`
-- `pre_fix_sha` — `git rev-parse HEAD` immediately before each FIX
-- `gate_round_count` — consecutive pre-audit gate failures (cap: 5 → exit `error`)
+## Archived workflow extensions
 
-State lives inline in the lead session (orchestrator). Cleared on TeamDelete. A single-subagent cycle returns its loop counter and findings in the exit payload (`{exit_reason, loop_count, final_commit_sha, audit_log, unresolved}`); the orchestrator discards intermediate state.
+Historical field lists for retired entry skills live under
+`packages/claude-dev-env/.agents/skills-archived/`:
 
-### pr-converge
-
-Normative field list, phase enum, dual persistence, and reset semantics: [`../../skills/pr-converge/reference/state-schema.md`](../../skills/pr-converge/reference/state-schema.md). File-backed multi-PR `status` enum: [`../../skills/pr-converge/reference/multi-pr-orchestration.md`](../../skills/pr-converge/reference/multi-pr-orchestration.md).
-
-Multi-PR runs also keep a per-PR JSON state file at `~/.claude/skills/pr-converge/state/<owner>-<repo>-<pr_number>.json`:
-
-| Field | Type | Description |
-|---|---|---|
-| `repo_name` | str | Full `owner/repo` |
-| `pr_number` | int | PR number |
-| `status` | enum | `open`, `blocked_escalation`, `fixing`, `ready_candidate`, `closed` |
-| `copilot_review` | enum | `none`, `requested`, `pending`, `commented`, `approved` |
-| `bugbot_review` | enum | Same vocabulary as `copilot_review`; one of `none`, `requested`, `pending`, `commented`, `approved` |
-| `last_seen_comment_id` | int \| null | Highest processed review-comment id (incremental polling watermark) |
-| `review_comments` | list[object] | Optional cache; `{id, author, path, line}` per entry |
-| `escalation_queue` | list[object] | Pending human-judgment items: `{comment_id, summary, created_at}` |
+- **bugteam** — inline orchestrator state, `team_name`, `gate_round_count`, exit payload fields. See [`../../.agents/skills-archived/bugteam/SKILL.md`](../../.agents/skills-archived/bugteam/SKILL.md).
+- **pr-converge** — file-backed multi-PR state, phase enum, dual persistence. See [`../../.agents/skills-archived/pr-converge/reference/state-schema.md`](../../.agents/skills-archived/pr-converge/reference/state-schema.md) and [`../../.agents/skills-archived/pr-converge/reference/multi-pr-orchestration.md`](../../.agents/skills-archived/pr-converge/reference/multi-pr-orchestration.md).
 
 ## Reset semantics
 
-- bugteam: cleared on each new `/bugteam` invocation
-- pr-converge: see [`../../skills/pr-converge/reference/state-schema.md`](../../skills/pr-converge/reference/state-schema.md); multi-PR file state persists across orchestrator runs and only `last_seen_comment_id` advances monotonically
+- **autoconverge** — portable state resets on a fresh `open-run`; workflow journal is per run id.
+- **Archived bugteam** — cleared on each new invocation; see archived skill body.
+- **Archived pr-converge** — see archived [`state-schema.md`](../../.agents/skills-archived/pr-converge/reference/state-schema.md); multi-PR file state persists across orchestrator runs and only `last_seen_comment_id` advances monotonically.
 
 ## Convergence checks
 
-- bugteam: `last_action == "audited"` AND `last_findings.total == 0` → `converged`
-- pr-converge: see [`../../skills/pr-converge/reference/convergence-gates.md`](../../skills/pr-converge/reference/convergence-gates.md); multi-PR ready when no unresolved comments require code changes, required checks are green, and review policy is satisfied → `gh pr ready`
+- **autoconverge** — `packages/claude-dev-env/_shared/pr-loop/scripts/check_convergence.py` is the single readiness source; gate labels are listed in [`../../.agents/skills/autoconverge/reference/convergence-gates.md`](../../.agents/skills/autoconverge/reference/convergence-gates.md). On pass, mark the PR ready (`gh pr ready`).
+- **Archived pr-converge** — same script and archived [`convergence-gates.md`](../../.agents/skills-archived/pr-converge/reference/convergence-gates.md) reference.

package/_shared/process-tree/AGENTS.md

@@ -9,10 +9,10 @@ never outlive the run and hold the capture pipe open.
 | Caller | Use |
 |---|---|
 | `scripts/grok_headless_runner.py` | Kills a timed-out worker's tree between drain attempts |
-| `skills/codex-review/scripts/run_codex_review.py` | Kills the review tree on timeout, then drains |
-| `skills/codex-review/scripts/codex_usage_probe.py` | Tears the app-server tree down after the rate-limits exchange |
+| `_shared/pr-loop/scripts/run_codex_review.py` | Kills the review tree on timeout, then drains |
+| `_shared/pr-loop/scripts/codex_usage_probe.py` | Tears the app-server tree down after the rate-limits exchange |
 
-A skill script reaches this home the way the bugteam scripts reach
+A PR-loop script reaches this home the way convergence scripts reach
 `_shared/pr-loop/scripts`: it puts the directory on `sys.path` and imports by
 module name. `bin/install.mjs` copies `_shared` and `scripts` together, and
 every install group that carries a consumer carries `_shared`, so the import

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,41 +12,64 @@
  * 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.
  */
 export const EVER_SHIPPED_SKILL_NAMES = new Set([
+    'agent-prompt',
     'anthropic-plan',
     'auditing-claude-config',
     'autoconverge',
+    'balatro',
     'bdd-protocol',
     'beat-sheet',
     'bg-agent',
+    'build-goal-prompt',
     'bugteam',
     'caveman',
     'closeout',
     'code',
+    'comments',
+    'condensing-instructions',
     'codex-review',
+    'context7-mcp',
     'copilot-finding-triage',
     'copilot-review',
     'deep-research',
+    'descriptions',
+    'emergencies',
     'everything-search',
     'findbugs',
     'fixbugs',
     'fresh-branch',
+    'gen-9-patch-icons',
+    'gen-all-icons',
+    'gen-clock-numbers',
+    'gen-icon-tray',
+    'gen-main-icons',
+    'gen-misc-icons',
     'gh-paginate',
     'gotcha',
     'grok-spawn',
     'grokify',
+    'icon-review-sheet',
     'imagegen',
     'implement',
     'issue-tracker',
     'log-audit',
     'logifix',
+    'midjourney-prompt',
+    'midjourney-submit',
     'monitor-open-prs',
     'orchestrator',
     'orchestrator-refresh',
+    'plan-to-pr',
+    'pmax',
+    'pmid',
+    'pmin',
     'post-audit-findings',
     'pr-consistency-audit',
     'pr-converge',
@@ -57,21 +80,29 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'pr-scope-resolve',
     'pre-compact',
     'privacy-hygiene',
+    'prompt-generator',
     'qbug',
     'rebase',
     'recall',
+    'reconcile-account',
+    'reddit-post-optimizer',
     'refine',
+    'release-notes-html',
     'remember',
     'research-mode',
     'reviewer-gates',
+    'reviews',
+    'run-claude-dev-env',
     'session-log',
     'session-tidy',
+    'show',
     'skill-builder',
+    'small-cl',
+    'split-pr',
     'structure-prompt',
     'task-build',
     'team-advisor',
     'update',
     'usage-pause',
     'verified-build',
-    'split-pr',
 ]);

package/bin/install-constants.mjs

@@ -44,30 +44,64 @@ 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`.
+ * the agents home.
  *
- * The copy loop reads `<package-root>/hooks` and writes `~/.claude/hooks`, the
- * hooks.json reads sit under the same name in each package source, the git-hook
- * shims and the mypy configuration point at the installed directory, the
- * retired-hook diff takes its relative paths against it, and the per-root
- * stale-file prune names it as one of its roots.
+ * The copy loop reads `<package-root>/.agents/hooks` (or `<package-root>/hooks`
+ * for a dependency with the legacy layout) and writes `~/.agents/hooks`.
+ * Claude and Codex lookup paths point at that canonical directory.
  */
 export const MANAGED_HOOKS_DIRECTORY_NAME = 'hooks';
 
+/**
+ * The directory name reusable scripts carry in a package source and under the
+ * agents home.
+ */
+export const MANAGED_SCRIPTS_DIRECTORY_NAME = 'scripts';
+
+/**
+ * Directory name Codex uses for installed hook scripts.
+ */
+export const CODEX_HOOKS_DIRECTORY_NAME = 'hooks';
+
 /**
  * The `~/.claude` file name that holds the user's harness settings.
  *

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',

package/bin/install.agents-home.test.mjs

@@ -0,0 +1,199 @@
+/**
+ * End-to-end install layout: skills and agents live under the agents home,
+ * and the Claude lookup paths are directory pointers to that home.
+ */
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    realpathSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONTENT_DIRECTORIES } from './install.mjs';
+import {
+    MANAGED_AGENTS_DIRECTORY_NAME,
+    MANAGED_SKILLS_DIRECTORY_NAME,
+} from './install-constants.mjs';
+import { isDirectoryPointerTo } from './publish-directory-pointer.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const SHIPPED_SKILL_NAME = 'privacy-hygiene';
+const ELI5_SKILL_NAME = 'eli5';
+const SHIPPED_AGENT_FILE_NAME = 'clean-coder.md';
+const PERSONAL_SKILL_NAME = 'my-notes';
+
+/**
+ * @param {string} homeDirectory
+ * @param {string[]} extraArguments
+ * @returns {string}
+ */
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            CODEX_HOME: join(homeDirectory, '.codex'),
+        },
+    });
+}
+
+test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
+    assert.equal(CONTENT_DIRECTORIES.includes(MANAGED_AGENTS_DIRECTORY_NAME), false);
+});
+
+test('a full install writes skills and agents under .agents and points .claude at them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-home-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const agentsHome = join(homeDirectory, '.agents');
+    const skillsInstallDirectory = join(agentsHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const agentsInstallDirectory = join(agentsHome, MANAGED_AGENTS_DIRECTORY_NAME);
+    const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const agentsLookupDirectory = join(claudeHome, MANAGED_AGENTS_DIRECTORY_NAME);
+    try {
+        runInstaller(homeDirectory, []);
+
+        const canonicalSkillFile = join(
+            skillsInstallDirectory, SHIPPED_SKILL_NAME, 'SKILL.md',
+        );
+        const canonicalEli5SkillFile = join(
+            skillsInstallDirectory, ELI5_SKILL_NAME, 'SKILL.md',
+        );
+        const lookupSkillFile = join(
+            skillsLookupDirectory, SHIPPED_SKILL_NAME, 'SKILL.md',
+        );
+        const lookupEli5SkillFile = join(
+            skillsLookupDirectory, ELI5_SKILL_NAME, 'SKILL.md',
+        );
+        const canonicalAgentFile = join(agentsInstallDirectory, SHIPPED_AGENT_FILE_NAME);
+        const lookupAgentFile = join(agentsLookupDirectory, SHIPPED_AGENT_FILE_NAME);
+
+        assert.equal(existsSync(canonicalSkillFile), true, 'skill file lives under .agents/skills');
+        assert.equal(existsSync(canonicalEli5SkillFile), true, 'ELI5 skill file lives under .agents/skills');
+        assert.equal(existsSync(canonicalAgentFile), true, 'agent file lives under .agents/agents');
+        assert.equal(lstatSync(skillsLookupDirectory).isSymbolicLink(), true);
+        assert.equal(lstatSync(agentsLookupDirectory).isSymbolicLink(), true);
+        assert.equal(
+            isDirectoryPointerTo(skillsLookupDirectory, skillsInstallDirectory),
+            true,
+        );
+        assert.equal(
+            isDirectoryPointerTo(agentsLookupDirectory, agentsInstallDirectory),
+            true,
+        );
+        assert.equal(
+            readFileSync(lookupSkillFile, 'utf8'),
+            readFileSync(canonicalSkillFile, 'utf8'),
+        );
+        assert.equal(
+            readFileSync(lookupEli5SkillFile, 'utf8'),
+            readFileSync(canonicalEli5SkillFile, 'utf8'),
+        );
+        assert.equal(realpathSync(lookupSkillFile), realpathSync(canonicalSkillFile));
+        assert.equal(realpathSync(lookupEli5SkillFile), realpathSync(canonicalEli5SkillFile));
+        assert.equal(
+            readFileSync(lookupAgentFile, 'utf8'),
+            readFileSync(canonicalAgentFile, 'utf8'),
+        );
+        assert.equal(realpathSync(lookupAgentFile), realpathSync(canonicalAgentFile));
+        assert.equal(
+            lstatSync(skillsInstallDirectory).isSymbolicLink(),
+            false,
+            'the agents-home skills directory is a real directory',
+        );
+        assert.equal(
+            lstatSync(agentsInstallDirectory).isSymbolicLink(),
+            false,
+            'the agents-home agents directory is a real directory',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a real skills directory from an older install lands in .agents and stays readable through the pointer', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-relocate-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const personalSkillFile = join(
+        skillsLookupDirectory, PERSONAL_SKILL_NAME, 'notes.md',
+    );
+    try {
+        mkdirSync(join(skillsLookupDirectory, PERSONAL_SKILL_NAME), { recursive: true });
+        writeFileSync(personalSkillFile, 'keep this personal skill\n');
+
+        runInstaller(homeDirectory, []);
+
+        const canonicalPersonalFile = join(
+            homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
+            PERSONAL_SKILL_NAME, 'notes.md',
+        );
+        assert.equal(lstatSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME)).isSymbolicLink(), true);
+        assert.equal(existsSync(canonicalPersonalFile), true);
+        assert.equal(
+            readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
+            'keep this personal skill\n',
+        );
+        assert.equal(
+            realpathSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md')),
+            realpathSync(canonicalPersonalFile),
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('uninstall removes managed skill files from the agents home and leaves a personal skill reachable through the pointer', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-uninstall-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    try {
+        mkdirSync(join(skillsLookupDirectory, PERSONAL_SKILL_NAME), { recursive: true });
+        writeFileSync(
+            join(skillsLookupDirectory, PERSONAL_SKILL_NAME, 'notes.md'),
+            'keep this personal skill\n',
+        );
+        runInstaller(homeDirectory, []);
+        runInstaller(homeDirectory, ['--uninstall']);
+
+        const shippedSkillFile = join(
+            homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
+            SHIPPED_SKILL_NAME, 'SKILL.md',
+        );
+        const personalSkillFile = join(
+            homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
+            PERSONAL_SKILL_NAME, 'notes.md',
+        );
+        assert.equal(existsSync(shippedSkillFile), false);
+        assert.equal(existsSync(personalSkillFile), true);
+        assert.equal(
+            isDirectoryPointerTo(
+                join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME),
+                join(homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME),
+            ),
+            true,
+            'the lookup pointer stays so a personal skill remains discoverable',
+        );
+        assert.equal(
+            readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
+            'keep this personal skill\n',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.cursor-rules.test.mjs

@@ -45,7 +45,7 @@ test('resolveInstallRoot names ~/.cursor/rules and allows generated mdc files un
     );
     assert.equal(resolution.cursorRulesInstallDirectory, expectedDirectory);
     assert.equal(
-        isAllowedInstallDestination(join(expectedDirectory, 'plain-language.mdc'), resolution),
+        isAllowedInstallDestination(join(expectedDirectory, 'asd-ste100-language.mdc'), resolution),
         true,
     );
     assert.equal(
@@ -72,7 +72,7 @@ test('a full install writes stem-named Cursor rules and leaves a local extra mdc
             homeDirectory,
             DEFAULT_CURSOR_DIRECTORY_NAME,
             CURSOR_RULES_DIRECTORY_NAME,
-            'plain-language.mdc',
+            'asd-ste100-language.mdc',
         );
         assert.equal(existsSync(generatedPath), true);
         const generatedText = readFileSync(generatedPath, 'utf8');
@@ -90,7 +90,7 @@ test('--only journal skips Cursor rule generation; --only core writes them', ()
             homeDirectory,
             DEFAULT_CURSOR_DIRECTORY_NAME,
             CURSOR_RULES_DIRECTORY_NAME,
-            'plain-language.mdc',
+            'asd-ste100-language.mdc',
         );
         runInstaller(homeDirectory, ['--only', 'journal']);
         assert.equal(existsSync(generatedPath), false);