claude-dev-env 7.3.0 → 7.4.1

package/.agents/skills/session-continuity/continuity.mjs

@@ -101,9 +101,7 @@ function potetoSource() {
     const found = [...new Set(candidates.filter(existsSync).map(path => realpathSync(path)))];
     if (found.length > 1) throw new Error('Multiple Poteto sources found. Set CDE_POTETO_SOURCE to the installed source used by this host.');
     const source = resolve(found[0] || candidates[0]);
-    if (existsSync(source) && !/^name:\s*["']?Poteto Mode["']?\s*$/m.test(readFileSync(source, 'utf8'))) {
-        throw new Error(`The selected source does not declare Poteto Mode: ${source}`);
-    }
+    if (!existsSync(source)) throw new Error(`Poteto source not found: ${source}`);
     return source;
 }
 

package/.agents/skills/session-continuity/continuity.test.mjs

@@ -283,12 +283,20 @@ for (const host of ['claude', 'codex']) {
         assert.deepEqual(f.fire('SessionStart', 'auto', { source: 'startup' }), [{}]);
     });
 
-    test(`${host}: an unavailable Poteto source stops automatic activation without writing a record`, t => {
+    test(`${host}: session start accepts an unrelated display name from the canonical Poteto path`, t => {
         const f = fixture(t, host);
-        writeFileSync(f.poteto, '---\nname: Something Else\n---\n');
-        const started = f.fire('SessionStart', 'broken', { source: 'startup' })[0];
+        writeFileSync(f.poteto, '---\nname: Concise Session Style\n---\nPOTETO_SOURCE_EXPECTATION: prove the requested result.\n');
+        const started = f.fire('SessionStart', 'unrelated-display-name', { source: 'startup' })[0];
+        assert.ok(started.hookSpecificOutput, started.systemMessage);
+        assert.ok(started.hookSpecificOutput.additionalContext.includes('POTETO_SOURCE_EXPECTATION'));
+    });
+
+    test(`${host}: a missing Poteto source stops automatic activation without writing a record`, t => {
+        const f = fixture(t, host);
+        unlinkSync(f.poteto);
+        const started = f.fire('SessionStart', 'missing-source', { source: 'startup' })[0];
         assert.match(started.systemMessage, /did not activate Poteto Mode/);
-        assert.equal(existsSync(f.pathFor('broken')), false);
+        assert.equal(existsSync(f.pathFor('missing-source')), false);
     });
 }
 

package/AGENTS.md

@@ -12,6 +12,16 @@ Use direct outcome-focused wording. Omit filler, failed attempts, alternatives c
 
 Cut AI tells from any writing. Must always apply.
 
+Banned word: real
+
+Never write real, really, or real-world. Not in chat, not in a commit message, not in a pull request body, not in a comment, not in documentation, not in a heading, not in a variable name. This ban has no exception. Emphasis is not an exception. Contrast with a test, a mock, a fixture, or a hypothetical is not an exception. Insisting that something is genuine is not an exception.
+
+Every sentence carrying real says the same thing without it. "One real failure" is "one failure". "The real cause" is "the cause". "Really fast" is "fast", or the measured number. "Real users" is "users". "A real bug, not a flake" is "a bug", followed by the evidence that rules out a flake.
+
+Delete the word, then read the sentence. When it still says what you meant, you are done. When something is missing, the missing part is evidence, so name the evidence. The failing check. The log line. The measured number. The file and the line.
+
+Swapping in actual, actually, genuine, or true is the same move, and each is banned with it. So is the invented contrast that invites the word back, such as "not a hypothetical problem but a problem".
+
 Edit text to remove AI patterns and add human voice.
 
 Process
@@ -37,7 +47,7 @@ Content
 
 Puffery. "pivotal moment", "testament to", "evolving landscape", "setting the stage for", "indelible mark", "deeply rooted". Cut puffery, state what happened.
 Name-dropping. Listing media outlets without context. Pick one, say what was said.
-Superficial -ing phrases. "highlighting...", "ensuring...", "reflecting...", "showcasing...", "fostering...". Delete or expand with real sources.
+Superficial -ing phrases. "highlighting...", "ensuring...", "reflecting...", "showcasing...", "fostering...". Delete or expand with named sources.
 Promotional language. "nestled", "vibrant", "breathtaking", "groundbreaking", "renowned", "stunning", "must-visit". Use neutral descriptions.
 Vague attributions. "Experts believe", "Industry reports suggest", "Some critics argue". Name the source or delete.
 Formulaic challenges. "Despite challenges... continues to thrive." Replace with specific facts.
@@ -78,7 +88,7 @@ Generic conclusions. "The future looks bright." State specific plans or facts.
 
 
 Jargon
-Abstract metaphor nouns. Substrate, wedge, vector, locus, vantage, nexus, primitive (as noun), harness (as metaphor), surface (as in "API surface"), bedrock, scaffolding (as metaphor), modality, paradigm, gold-plating, ratchet (as metaphor), evacuate (for moving code), endgame, north star, flywheel. These read as technical but usually have a plainer concrete word. "Substrate" becomes "base". "Wedge in" becomes "add". "Vector" becomes "way" or "method". "Gold-plating" becomes "more than the job needs". "Ratchet" becomes the mechanism's real name or "a limit that only tightens". "Evacuate" becomes "move out". "Endgame" becomes "the last phase". Pick the concrete word.
+Abstract metaphor nouns. Substrate, wedge, vector, locus, vantage, nexus, primitive (as noun), harness (as metaphor), surface (as in "API surface"), bedrock, scaffolding (as metaphor), modality, paradigm, gold-plating, ratchet (as metaphor), evacuate (for moving code), endgame, north star, flywheel. These read as technical but usually have a plainer concrete word. "Substrate" becomes "base". "Wedge in" becomes "add". "Vector" becomes "way" or "method". "Gold-plating" becomes "more than the job needs". "Ratchet" becomes the mechanism's own name or "a limit that only tightens". "Evacuate" becomes "move out". "Endgame" becomes "the last phase". Pick the concrete word.
 
 
 Plain speech

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

@@ -82,6 +82,7 @@ const PREFLIGHT_PROPOSAL_FILE_NAME = 'preflight-proposal.md';
 function runInstaller(homeDirectory, extraArguments, environmentOverrides = {}) {
     const installerEnvironment = {
         ...process.env,
+        CDE_INSTALL_PSTACK: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

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

@@ -56,6 +56,7 @@ function runInstaller(homeDirectory, extraArguments) {
         encoding: 'utf8',
         env: {
             ...process.env,
+            CDE_INSTALL_PSTACK: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -83,6 +84,7 @@ function scanTextWithProductionPiiScanner(scannedText) {
                 encoding: 'utf8',
                 env: {
                     ...process.env,
+                    CDE_INSTALL_PSTACK: '0',
                     PYTHONPATH: BLOCKING_HOOKS_DIRECTORY,
                     CLAUDE_LOCAL_IDENTITY_PATH: join(
                         temporaryDirectory,

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

@@ -31,6 +31,7 @@ function runInstaller(homeDirectory, extraArguments, environmentOverrides = {})
         encoding: 'utf8',
         env: {
             ...process.env,
+            CDE_INSTALL_PSTACK: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             CODEX_HOME: join(homeDirectory, '.codex'),

package/bin/install.mjs

@@ -43,6 +43,7 @@ import {
     PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH,
     refreshPstackPluginManifest,
 } from '../scripts/refresh_pstack_plugin_skills.mjs';
+import { installPstack } from './pstack.mjs';
 import {
     resolveInstallRoot,
     parseExplicitTargetFromArgv,
@@ -326,19 +327,9 @@ export const INSTALL_GROUPS = {
     ...dependencyDiscovery.groups,
 };
 
-/**
- * Returns the ordered python interpreter candidates to probe for the given
- * platform. On win32 the `py -3` launcher is probed first because it resolves
- * through the Windows registry and is immune to the Microsoft Store
- * `python.exe` App Execution Alias that otherwise gets baked into settings.json.
- *
- * @param {string} platform A value from `process.platform` (e.g. 'win32', 'linux').
- * @returns {{command: string, versionFlag: string}[]} Candidates in probe order.
- */
 export function pythonCandidatesForPlatform(platform) {
     const windowsOrder = [
         { command: 'py -3', versionFlag: '--version' },
-        { command: 'python3', versionFlag: '--version' },
         { command: 'python', versionFlag: '--version' },
     ];
     const defaultOrder = [
@@ -432,6 +423,54 @@ export function runCursorRuleSync(pythonCommand, scriptPath, claudeRoot, cursorR
     );
 }
 
+const PSTACK_RELEASE_OPT_OUT_FLAG = '--no-pstack';
+const PSTACK_RELEASE_OPT_OUT_VARIABLE = 'CDE_INSTALL_PSTACK';
+const PSTACK_RELEASE_OPT_OUT_VALUE = '0';
+
+/**
+ * Decide whether a full install also installs the pstack release.
+ *
+ * The step reaches the network for the pinned upstream commit. `--no-pstack`
+ * on the command line, or `CDE_INSTALL_PSTACK=0` in the environment, turns it
+ * off for an air-gapped or offline run.
+ *
+ * @param {string[]} [argumentList] The command-line arguments after the script.
+ * @param {Record<string, string|undefined>} [environment] The process environment.
+ * @returns {boolean} True when this run installs the pstack release.
+ */
+export function shouldInstallPstackRelease(
+    argumentList = process.argv.slice(2),
+    environment = process.env,
+) {
+    if (argumentList.includes(PSTACK_RELEASE_OPT_OUT_FLAG)) return false;
+    return environment[PSTACK_RELEASE_OPT_OUT_VARIABLE] !== PSTACK_RELEASE_OPT_OUT_VALUE;
+}
+
+/**
+ * Install the pstack release into a managed root without failing the run.
+ *
+ * The pstack store keeps its own state and its own skill pointers, so this
+ * step reports its outcome rather than adding paths to the install manifest.
+ * A network failure returns a warning so the rules, hooks, and skills this
+ * run already wrote still reach their durable places.
+ *
+ * @param {object} [options] Options for `installPstack`, including `root`.
+ * @param {object} [dependencies] Seams `installPstack` accepts, such as `fetchSource`.
+ * @returns {{status: string, release: string|null, warning: string|null}} The outcome.
+ */
+export function installPstackRelease(options = {}, dependencies = {}) {
+    try {
+        const installation = installPstack(options, dependencies);
+        return {
+            status: installation.status,
+            release: installation.release,
+            warning: installation.warning ?? null,
+        };
+    } catch (installError) {
+        return { status: 'failed', release: null, warning: installError.message };
+    }
+}
+
 /**
  * Refresh the pstack plugin manifest Claude Code reads, when this home has one.
  *
@@ -2753,6 +2792,13 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     }
     summary.skills = { created: skillsCreated, updated: skillsUpdated, pruned: 0, paths: skillPaths };
     allInstalledFiles.push(...skillPaths);
+    if (!selectedGroups && shouldInstallPstackRelease()) {
+        const pstackRelease = installPstackRelease({ root: CLAUDE_HOME });
+        summary.pstackRelease = pstackRelease;
+        console.log(pstackRelease.warning
+            ? `  Pstack: ${pstackRelease.status} \u2014 ${pstackRelease.warning}`
+            : `  Pstack: ${pstackRelease.status} (${pstackRelease.release})`);
+    }
     const pstackManifestPath = refreshInstalledPstackPluginManifest();
     if (pstackManifestPath) allInstalledFiles.push(pstackManifestPath);
     summary.pstackPlugin = { manifestPath: pstackManifestPath };
@@ -3240,6 +3286,7 @@ Usage:
   npx ${PACKAGE_NAME} --target DIR Install into DIR instead of ~/.claude (overrides CLAUDE_CONFIG_DIR)
   npx ${PACKAGE_NAME} --profile ID Install into one named profile root (under the profiles root)
   npx ${PACKAGE_NAME} --profiles A,B  Install into each selected profile (one ownership manifest per target)
+  npx ${PACKAGE_NAME} --no-pstack  Full install without the pinned pstack release (also CDE_INSTALL_PSTACK=0)
   npx ${PACKAGE_NAME} --uninstall  Remove installed files from the selected root
   npx ${PACKAGE_NAME} --help       Show this help
 

package/bin/install.prune.test.mjs

@@ -258,6 +258,7 @@ function runInstaller(homeDirectory, extraArguments) {
 function resolveInstallerInvocation(homeDirectory) {
     const childEnvironment = {
         ...process.env,
+        CDE_INSTALL_PSTACK: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/bin/install.pstack-plugin.test.mjs

@@ -25,6 +25,7 @@ function runInstaller(homeDirectory, extraArguments) {
         encoding: 'utf8',
         env: {
             ...process.env,
+            CDE_INSTALL_PSTACK: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             CODEX_HOME: join(homeDirectory, '.codex'),

package/bin/install.settings-defaults.test.mjs

@@ -49,6 +49,7 @@ function runInstallerInSandbox(sandboxHome, installerArguments = []) {
         encoding: 'utf8',
         env: {
             ...process.env,
+            CDE_INSTALL_PSTACK: '0',
             HOME: sandboxHome,
             USERPROFILE: sandboxHome,
             GIT_CONFIG_GLOBAL: gitConfigGlobal,

package/bin/install.test.mjs

@@ -11,6 +11,8 @@ import {
     readdirSync,
     existsSync,
     copyFileSync,
+    cpSync,
+    lstatSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -18,6 +20,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
     collectPackageSourceConflicts,
+    installPstackRelease,
+    shouldInstallPstackRelease,
     CONTENT_DIRECTORIES,
     CORE_INCLUDE_DIRECTORIES,
     CORE_SKILLS,
@@ -301,10 +305,9 @@ test('collectPackageSourceConflicts surfaces both-added and deleted-by-them entr
 });
 
 
-test('pythonCandidatesForPlatform prefers py -3 ahead of python on win32 so the Microsoft Store stub is never probed first', () => {
+test('pythonCandidatesForPlatform uses Windows Python launchers on win32', () => {
     const commands = pythonCandidatesForPlatform('win32').map(candidate => candidate.command);
-    assert.equal(commands[0], 'py -3');
-    assert.ok(commands.indexOf('py -3') < commands.indexOf('python'));
+    assert.deepEqual(commands, ['py -3', 'python']);
 });
 
 
@@ -314,7 +317,7 @@ test('pythonCandidatesForPlatform keeps python3 first on non-Windows platforms',
 });
 
 
-test('pythonCandidatesForPlatform still offers python as a win32 fallback when py -3 and python3 are absent', () => {
+test('pythonCandidatesForPlatform still offers python as a win32 fallback when py -3 is absent', () => {
     const commands = pythonCandidatesForPlatform('win32').map(candidate => candidate.command);
     assert.ok(commands.includes('python'));
 });
@@ -2975,3 +2978,114 @@ test('pruneRetiredHookEntriesFromSettings warns and returns 0 when the host conf
         rmSync(sandboxRoot, { recursive: true, force: true });
     }
 });
+
+const PSTACK_TEST_PACKAGE_ROOT = dirname(fileURLToPath(new URL('./install.mjs', import.meta.url)));
+const PSTACK_TEST_INSTALLER_PATH = fileURLToPath(new URL('./install.mjs', import.meta.url));
+const PSTACK_TEST_LOCK = JSON.parse(readFileSync(
+    new URL('../scripts/pstack.lock.json', import.meta.url),
+    'utf8',
+));
+
+function writePstackFixtureFile(filePath, fileContent) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, fileContent);
+}
+
+function pstackUpstreamFixture(t) {
+    const temporaryRoot = mkdtempSync(join(tmpdir(), 'cdev-install-pstack-'));
+    t.after(() => rmSync(temporaryRoot, { recursive: true, force: true }));
+    const checkout = join(temporaryRoot, 'checkout');
+    for (const [component, allSkillNames] of Object.entries(PSTACK_TEST_LOCK.requiredSkills)) {
+        for (const skillName of allSkillNames) {
+            writePstackFixtureFile(
+                join(checkout, component, 'skills', skillName, 'SKILL.md'),
+                `---\nname: ${skillName}\ndescription: Test ${skillName}.\n---\n\nRun ${skillName}.\n`,
+            );
+        }
+    }
+    const managedRoot = join(temporaryRoot, 'home', '.claude');
+    return {
+        managedRoot,
+        options: {
+            root: managedRoot,
+            lock: structuredClone(PSTACK_TEST_LOCK),
+            packageRoot: dirname(PSTACK_TEST_PACKAGE_ROOT),
+        },
+        dependencies: {
+            fetchSource: (_lock, destination) => cpSync(checkout, destination, { recursive: true }),
+        },
+    };
+}
+
+function runPstackInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [PSTACK_TEST_INSTALLER_PATH, ...extraArguments], {
+        cwd: dirname(PSTACK_TEST_PACKAGE_ROOT),
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            CLAUDE_CONFIG_DIR: join(homeDirectory, '.claude'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            CDE_INSTALL_PSTACK: '1',
+            GIT_ALLOW_PROTOCOL: 'none',
+        },
+    });
+}
+
+function withPstackTemporaryHome(t, runAssertions) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-install-pstack-run-'));
+    t.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    runAssertions(homeDirectory);
+}
+
+test('the base install publishes the pstack poteto-mode entry into the managed skills home', t => {
+    const fixture = pstackUpstreamFixture(t);
+
+    const outcome = installPstackRelease(fixture.options, fixture.dependencies);
+
+    assert.equal(outcome.status, 'installed');
+    assert.equal(outcome.warning, null);
+    const pstackRoot = join(fixture.managedRoot, 'skills', 'pstack');
+    const entryPath = join(pstackRoot, 'poteto-mode');
+    assert.equal(lstatSync(pstackRoot).isSymbolicLink(), true, 'the pstack root is a pointer into the release');
+    assert.equal(existsSync(join(entryPath, 'SKILL.md')), true, 'the nested entry resolves to a skill');
+});
+
+test('an unreachable pstack upstream reports a warning and keeps the base install going', t => {
+    const fixture = pstackUpstreamFixture(t);
+
+    const outcome = installPstackRelease(fixture.options, {
+        fetchSource: () => { throw new Error('network unavailable'); },
+    });
+
+    assert.equal(outcome.status, 'failed');
+    assert.equal(outcome.release, null);
+    assert.match(outcome.warning, /network unavailable/);
+});
+
+test('--no-pstack and CDE_INSTALL_PSTACK=0 each turn the pstack step off', () => {
+    assert.equal(shouldInstallPstackRelease([], {}), true);
+    assert.equal(shouldInstallPstackRelease(['--no-pstack'], {}), false);
+    assert.equal(shouldInstallPstackRelease([], { CDE_INSTALL_PSTACK: '0' }), false);
+    assert.equal(shouldInstallPstackRelease([], { CDE_INSTALL_PSTACK: '1' }), true);
+});
+
+test('a full install runs the pstack step and reports an upstream failure without stopping', t => {
+    withPstackTemporaryHome(t, homeDirectory => {
+        const installerOutput = runPstackInstaller(homeDirectory, []);
+
+        assert.match(installerOutput, /Pstack:/, 'the run reports the pstack step');
+        assert.equal(existsSync(join(homeDirectory, '.claude', 'pstack')), true);
+    });
+});
+
+test('--no-pstack leaves the pstack store absent', t => {
+    withPstackTemporaryHome(t, homeDirectory => {
+        const installerOutput = runPstackInstaller(homeDirectory, ['--no-pstack']);
+
+        assert.doesNotMatch(installerOutput, /Pstack:/);
+        assert.equal(existsSync(join(homeDirectory, '.claude', 'pstack')), false);
+    });
+});

package/bin/install.transaction.test.mjs

@@ -83,6 +83,7 @@ test('capture and restore recover settings, manifest, files, and hooksPath', ()
     mkdirSync(priorHooksDirectory, { recursive: true });
     const env = {
         ...process.env,
+        CDE_INSTALL_PSTACK: '0',
         HOME: box.root,
         USERPROFILE: box.root,
         GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -139,6 +140,7 @@ test('runWithInstallTransaction restores prior state on injected fault', () => {
     writeFileSync(gitConfigPath, '');
     const env = {
         ...process.env,
+        CDE_INSTALL_PSTACK: '0',
         HOME: box.root,
         USERPROFILE: box.root,
         GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -191,6 +193,7 @@ test('runWithInstallTransaction commits and discards journal on success', () =>
     const io = {
         env: {
             ...process.env,
+            CDE_INSTALL_PSTACK: '0',
             HOME: box.root,
             USERPROFILE: box.root,
             GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -239,6 +242,7 @@ test('runWithInstallTransaction commits and discards journal on success', () =>
 function runInstaller(homeDirectory, extraArguments, options = {}) {
     const childEnvironment = {
         ...process.env,
+        CDE_INSTALL_PSTACK: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -356,6 +360,7 @@ test('installer fault after_git_config restores prior core.hooksPath', () => {
         writeGlobalCoreHooksPath(priorHooksPath, {
             env: {
                 ...process.env,
+                CDE_INSTALL_PSTACK: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -371,6 +376,7 @@ test('installer fault after_git_config restores prior core.hooksPath', () => {
         const restored = readGlobalCoreHooksPath({
             env: {
                 ...process.env,
+                CDE_INSTALL_PSTACK: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/bin/install.uninstall-transaction.test.mjs

@@ -71,6 +71,7 @@ function writeFileWithParents(filePath, contents) {
 function runInstaller(homeDirectory, extraArguments, options = {}) {
     const childEnvironment = {
         ...process.env,
+        CDE_INSTALL_PSTACK: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -303,6 +304,7 @@ test('uninstall fault after_git_config restores prior core.hooksPath', () => {
         const io = {
             env: {
                 ...process.env,
+                CDE_INSTALL_PSTACK: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/bin/pstack.mjs

@@ -84,6 +84,17 @@ function adaptSkill(text, name, releaseRoot, skillRoot) {
         + fork + '\n' + match[2].trimStart();
 }
 
+function writePstackPluginManifest(stage, skills) {
+    const manifest = {
+        $schema: 'https://anthropic.com/claude-code/plugin.schema.json',
+        name: 'pstack',
+        skills: skills.filter(skill => skill.component === 'pstack').map(skill => `./${skill.slug}`),
+    };
+    const pluginRoot = join(stage, 'runtime', 'pstack', 'skills');
+    mkdirSync(join(pluginRoot, '.claude-plugin'), { recursive: true });
+    writeFileSync(join(pluginRoot, '.claude-plugin', 'plugin.json'), json(manifest));
+}
+
 export function prepareRelease(checkout, stage, finalRoot, lock, adapters) {
     const skills = [];
     const agents = [];
@@ -102,10 +113,11 @@ export function prepareRelease(checkout, stage, finalRoot, lock, adapters) {
         }
         for (const slug of names) {
             if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`Invalid skill directory: ${slug}`);
-            const name = `${component}-${slug}`;
+            const name = component === 'pstack' ? `pstack:${slug}` : `${component}-${slug}`;
+            const frontmatterName = component === 'pstack' ? slug : name;
             const path = join('runtime', component, 'skills', slug);
             const text = readFileSync(join(source, 'skills', slug, 'SKILL.md'), 'utf8');
-            writeFileSync(join(stage, path, 'SKILL.md'), adaptSkill(text, name, finalRoot, join(finalRoot, path)));
+            writeFileSync(join(stage, path, 'SKILL.md'), adaptSkill(text, frontmatterName, finalRoot, join(finalRoot, path)));
             skills.push({ name, component, slug, path });
         }
         const agentHome = join(source, 'agents');
@@ -118,6 +130,7 @@ export function prepareRelease(checkout, stage, finalRoot, lock, adapters) {
     mkdirSync(join(stage, creatorPath), { recursive: true });
     writeFileSync(join(stage, creatorPath, 'SKILL.md'), adapters['create-skill.md']);
     skills.push({ name: 'cde-create-skill', component: 'cde', slug: 'create-skill', path: creatorPath });
+    writePstackPluginManifest(stage, skills);
     const knownNames = new Set(skills.map(skill => `${skill.component}:${skill.slug}`));
     for (const path of filesUnder(join(stage, 'upstream')).filter(path => path.endsWith('.md') && (path.includes(sep + 'skills' + sep) || path.includes(sep + 'agents' + sep)))) {
         const references = readFileSync(path, 'utf8').matchAll(/\b(pstack|cursor-team-kit):([a-z][a-z0-9-]*)/g);
@@ -146,7 +159,9 @@ export function verifyRelease(root) {
         if (digest(readFileSync(assertContained(root, path))) !== hash) throw new Error(`Changed installed file: ${path}`);
     }
     for (const skill of release.skills) {
-        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.name)) throw new Error('Invalid installed skill name');
+        const validPart = value => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+        const expectedName = skill.component === 'pstack' ? `pstack:${skill.slug}` : `${skill.component}-${skill.slug}`;
+        if (!validPart(skill.component) || !validPart(skill.slug) || skill.name !== expectedName) throw new Error('Invalid installed skill name');
         const path = join(assertContained(root, skill.path), 'SKILL.md');
         if (!Object.hasOwn(release.fileDigests, relative(root, path)) || !existsSync(path)) throw new Error(`Missing entry: ${skill.name}`);
     }
@@ -177,7 +192,12 @@ export function verifyInstallation(options = {}) {
 
 function publish(releaseRoot, release, homes, prior) {
     const uniqueHomes = [...new Set(homes.map(home => { mkdirSync(home, { recursive: true }); return realpathSync(home); }))];
-    const links = Object.fromEntries(uniqueHomes.flatMap(home => release.skills.map(skill => [join(home, skill.name), join(releaseRoot, skill.path)])));
+    const pstackSkill = release.skills.find(skill => skill.component === 'pstack');
+    const directSkills = release.skills.filter(skill => skill.component !== 'pstack');
+    const links = Object.fromEntries(uniqueHomes.flatMap(home => [
+        ...(pstackSkill ? [[join(home, 'pstack'), join(releaseRoot, dirname(pstackSkill.path))]] : []),
+        ...directSkills.map(skill => [join(home, skill.name), join(releaseRoot, skill.path)]),
+    ]));
     const paths = new Set([...Object.keys(prior?.links ?? {}), ...Object.keys(links)]);
     const before = new Map();
     for (const path of paths) {

package/bin/pstack.test.mjs

@@ -44,15 +44,23 @@ for (const host of ['claude', 'codex', 'cursor']) {
         assert.equal(result.commit, '27e2a62ff94f9af4b5e68435e41cdceacadb840c');
         assert.equal(result.verification, 'filesystem-only');
         const release = join(f.store, 'releases', result.release);
-        const expected = ['cde-create-skill', 'cursor-team-kit-control-cli', 'cursor-team-kit-control-ui', 'cursor-team-kit-deslop', 'pstack-poteto-mode'];
+        const releaseManifest = JSON.parse(readFileSync(join(release, 'release.json'), 'utf8'));
+        assert.equal(releaseManifest.skills.find(skill => skill.component === 'pstack').name, 'pstack:poteto-mode');
+        const expected = ['cde-create-skill', 'cursor-team-kit-control-cli', 'cursor-team-kit-control-ui', 'cursor-team-kit-deslop', 'pstack'];
         for (const home of ['.claude', '.agents']) {
-            assert.deepEqual(readdirSync(join(f.options.project, home, 'skills')).sort(), expected);
-            const entry = join(f.options.project, home, 'skills', 'pstack-poteto-mode');
+            const skillsHome = join(f.options.project, home, 'skills');
+            assert.deepEqual(readdirSync(skillsHome).sort(), expected);
+            const pstackRoot = join(skillsHome, 'pstack');
+            assert.equal(lstatSync(pstackRoot).isSymbolicLink(), true);
+            const entry = join(pstackRoot, 'poteto-mode');
             assert.equal(realpathSync(entry), join(release, 'runtime', 'pstack', 'skills', 'poteto-mode'));
             const text = readFileSync(join(entry, 'SKILL.md'), 'utf8');
-            assert.match(text, /name: pstack-poteto-mode/);
+            assert.match(text, /name: poteto-mode/);
             assert.ok(text.includes(JSON.stringify(join(release, 'compat', 'common.md'))));
             assert.equal(readFileSync(join(entry, 'playbooks', 'feature.md'), 'utf8'), 'Build a small task, delegate, and verify it.\n');
+            const manifest = JSON.parse(readFileSync(join(pstackRoot, '.claude-plugin', 'plugin.json'), 'utf8'));
+            assert.equal(manifest.name, 'pstack');
+            assert.deepEqual(manifest.skills, ['./poteto-mode']);
         }
         assert.equal(existsSync(join(f.options.project, '.cursor')), false);
         for (const component of baseLock.components) {
@@ -89,10 +97,12 @@ test('changed, added, and removed skills converge while old releases remain read
     const after = installPstack({ ...f.options, lock: { ...baseLock, commit: 'b'.repeat(40) } }, f.dependencies);
     assert.equal(after.skillCount, 6);
     for (const home of ['.claude', '.agents']) {
-        const path = join(f.options.project, home, 'skills');
-        assert.equal(existsSync(join(path, 'pstack-old')), false);
-        assert.equal(readFileSync(join(path, 'pstack-new', 'SKILL.md'), 'utf8').endsWith('New body.\n'), true);
-        assert.equal(readFileSync(join(path, 'pstack-poteto-mode', 'playbooks', 'feature.md'), 'utf8'), 'Changed playbook.\n');
+        const pstackRoot = join(f.options.project, home, 'skills', 'pstack');
+        assert.equal(existsSync(join(pstackRoot, 'old')), false);
+        assert.equal(readFileSync(join(pstackRoot, 'new', 'SKILL.md'), 'utf8').endsWith('New body.\n'), true);
+        assert.equal(readFileSync(join(pstackRoot, 'poteto-mode', 'playbooks', 'feature.md'), 'utf8'), 'Changed playbook.\n');
+        const manifest = JSON.parse(readFileSync(join(pstackRoot, '.claude-plugin', 'plugin.json'), 'utf8'));
+        assert.deepEqual(manifest.skills, ['./new', './poteto-mode']);
     }
     assert.equal(readFileSync(join(oldRelease, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'), firstBody);
 });
@@ -117,9 +127,9 @@ test('a failed first install returns failure and publishes no skills', t => {
     assert.equal(existsSync(join(f.store, '.install-lock')), false);
 });
 
-test('unmanaged skill collision preserves user files', t => {
+test('unmanaged pstack root collision preserves user files', t => {
     const f = fixture(t);
-    const userFile = join(f.options.project, '.claude', 'skills', 'pstack-poteto-mode', 'SKILL.md');
+    const userFile = join(f.options.project, '.claude', 'skills', 'pstack', 'poteto-mode', 'SKILL.md');
     put(userFile, 'Personal workflow\n');
     assert.throws(() => installPstack(f.options, f.dependencies), /Keep existing unmanaged path/);
     assert.equal(readFileSync(userFile, 'utf8'), 'Personal workflow\n');