Lifecycle Hooks

This skill documents the session-start lifecycle hooks used by the dev-tools package. These hooks run automatically at session initialization to ensure cross-plugin references resolve correctly in cached environments.

Cross-Plugin Dependency Resolution

Problem

When plugins are installed from a marketplace/registry, each plugin is cached in an isolated directory with organization-prefixed names and version subdirectories. Cross-plugin references (e.g., loading a skill from a sibling plugin via relative paths) break because the directory structure differs from the local development monorepo layout.

Local monorepo layout:

claude/
├── core-tools/       <- ../core-tools/ resolves naturally
├── dev-tools/
└── claude-tools/

Cached plugin layout:

plugins/cache/org-name/
├── org-name-core-tools/
│   └── 0.2.3/       <- long path, org-prefixed name
├── org-name-dev-tools/
│   └── 0.3.4/
└── org-name-claude-tools/
    └── 0.2.5/

Solution

The

resolve-cross-plugins.sh

script (in

references/

) runs at session start and creates short-name symlinks at the plugin-name directory level so that

../{short-name}/

resolves correctly in both environments.

After script runs:

plugins/cache/org-name/org-name-dev-tools/
├── 0.3.4/                    <- actual plugin content
├── core-tools -> ../org-name-core-tools/0.2.3   <- symlink
└── claude-tools -> ../org-name-claude-tools/0.2.5  <- symlink

Hook Configuration

The hook runs as a

session_start

event of type

command

:

event: session_start
type: command
command: bash <plugin_root>/hooks/resolve-cross-plugins.sh <plugin_root>
timeout: 10

Script Behavior

The

resolve-cross-plugins.sh

script:

1. Guard: Only runs in cached plugin environments (path contains

   /plugins/cache/

   ). In local monorepo development, the script exits immediately since relative paths already work.

2. Discovery: Iterates over sibling directories in the organization directory, stripping the org prefix to derive the short name (e.g.,

   org-name-core-tools

   ->

   core-tools

   ).

3. Version Resolution: Determines the correct version directory using:

   • Primary: reads

     installed_plugins.json

     from the agent configuration directory (requires

     jq

     )
   • Fallback: sorts version directories by version number and takes the latest

4. Symlink Creation: Creates relative symlinks (

   ln -sfn

   ) from the short name to the resolved version directory. Skips if a real (non-symlink) directory already exists with that name.

5. Safety: Never blocks session start -- the script traps all errors and exits cleanly with code 0. Debug logging is available via the

   AGENT_ALCHEMY_HOOK_DEBUG=1

   environment variable.

Adaptation for Other Platforms

If your platform uses a different plugin caching mechanism:

1. Identify the cached layout -- how are sibling plugins organized on disk?
2. Determine the naming convention -- are names prefixed with organization/scope?
3. Create equivalent symlinks -- ensure

   ../{short-name}/

   resolves to the correct version of each sibling plugin
4. Handle version resolution -- use your platform's installed-plugins metadata if available
5. Ensure safety -- never block session initialization on symlink creation failures

---

Integration Notes

What this component does: Provides a session-start hook that creates short-name symlinks for cross-plugin dependency resolution in cached/installed plugin environments, ensuring that relative path references between plugin packages work correctly. Capabilities needed: Shell execution (bash script with

ln

,

jq

), file system access (symlink creation in plugin cache directory). Adaptation guidance: This hook addresses a specific problem with cached plugin directory layouts. If your platform resolves cross-package references differently (e.g., through a module system, import maps, or path aliases), you may not need this hook. The script in

references/resolve-cross-plugins.sh

can serve as a reference implementation. The key requirement is that

../{package-short-name}/

relative paths must resolve from any sibling plugin's root directory.