claude-dev-env 8.32.0 → 8.32.1

package/bin/codex-skill-load-block.mjs

@@ -50,7 +50,8 @@ function withPackageGuidanceBlock(guidanceText, packageGuidanceText) {
         PACKAGE_GUIDANCE_BLOCK_END,
         block,
     );
-    return replacedText ?? `${guidanceText}\n${block}`;
+    if (replacedText !== null) return replacedText;
+    return guidanceText ? `${guidanceText}\n${block}` : block;
 }
 
 function comparablePath(filePath) {
@@ -66,28 +67,14 @@ function linksToPackageGuidance(agentsPath, allPackageGuidancePaths) {
     return allPackageGuidancePaths.some(eachPath => comparablePath(eachPath) === linkTarget);
 }
 
-/**
- * Keep CODEX_HOME/AGENTS.md carrying the skill-load block.
- *
- * A symbolic link that points at the package guidance (the shared agents-home
- * copy, or the retired copy under the Claude home) is replaced by a regular
- * file holding the skill-load block and a package-guidance block, so Codex
- * keeps both after the package moves its guidance. A file that already holds
- * the package-guidance block gets the current guidance text. A link to any
- * other file is left alone.
- *
- * Returns the file path when the file changed, and null otherwise.
- */
-export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
+function writeCodexGuidanceFile(codexHome, allPackageGuidancePaths, transformGuidance) {
     const agentsPath = join(codexHome, 'AGENTS.md');
     const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    if (agentsEntry && !agentsEntry.isFile() && !agentsEntry.isSymbolicLink()) return null;
     const isPackageGuidanceLink = agentsEntry?.isSymbolicLink() ?? false;
     if (isPackageGuidanceLink && !linksToPackageGuidance(agentsPath, allPackageGuidancePaths)) return null;
     const currentText = agentsEntry && !isPackageGuidanceLink ? readFileSync(agentsPath, 'utf8') : '';
-    let updatedText = withSkillLoadBlock(currentText);
-    if (isPackageGuidanceLink || updatedText.includes(PACKAGE_GUIDANCE_BLOCK_START)) {
-        updatedText = withPackageGuidanceBlock(updatedText, packageGuidanceText);
-    }
+    const updatedText = transformGuidance(currentText);
     if (!isPackageGuidanceLink && updatedText === currentText) return null;
     mkdirSync(codexHome, { recursive: true });
     if (isPackageGuidanceLink) unlinkSync(agentsPath);
@@ -95,6 +82,39 @@ export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPack
     return agentsPath;
 }
 
+/**
+ * Keep CODEX_HOME/AGENTS.md carrying the skill-load block and the package guidance.
+ *
+ * The skill-load block goes first, and the package-guidance block holds the
+ * current guidance text. A symbolic link that points at the package guidance
+ * (the shared agents-home copy, or the retired copy under the Claude home) is
+ * replaced by a regular file holding both blocks, so Codex keeps both after
+ * the package moves its guidance. A link to any other file is left alone.
+ *
+ * Returns the file path when the file changed, and null otherwise.
+ */
+export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
+    return writeCodexGuidanceFile(
+        codexHome,
+        allPackageGuidancePaths,
+        currentText => withPackageGuidanceBlock(withSkillLoadBlock(currentText), packageGuidanceText),
+    );
+}
+
+/**
+ * Keep CODEX_HOME/AGENTS.md carrying the package guidance, with no skill-load block.
+ *
+ * Links follow the same rule as writeCodexAgentsGuidance. Returns the file
+ * path when the file changed, and null otherwise.
+ */
+export function writeCodexPackageGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
+    return writeCodexGuidanceFile(
+        codexHome,
+        allPackageGuidancePaths,
+        currentText => withPackageGuidanceBlock(currentText, packageGuidanceText),
+    );
+}
+
 export function writeCodexQuestionGuidance(codexHome, policyText) {
     const agentsPath = join(codexHome, 'AGENTS.md');
     const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
@@ -112,30 +132,63 @@ export function writeCodexQuestionGuidance(codexHome, policyText) {
     return agentsPath;
 }
 
-export function hasOnlyQuestionPresentationBlock(guidanceText) {
-    if (!guidanceText.startsWith(`${QUESTION_PRESENTATION_BLOCK_START}\n`)) return false;
-    if (!guidanceText.endsWith(`${QUESTION_PRESENTATION_BLOCK_END}\n`)) return false;
-    return withBlockReplaced(
-        guidanceText, QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END, '',
-    ) === '';
+const ALL_PACKAGE_MANAGED_BLOCK_MARKERS = [
+    [SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END],
+    [PACKAGE_GUIDANCE_BLOCK_START, PACKAGE_GUIDANCE_BLOCK_END],
+    [QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END],
+];
+
+/**
+ * Report whether the guidance holds at least one package-managed block and
+ * nothing else but blank lines.
+ */
+export function hasOnlyPackageManagedBlocks(guidanceText) {
+    let remainingText = guidanceText;
+    let removedBlockCount = 0;
+    for (const [blockStart, blockEnd] of ALL_PACKAGE_MANAGED_BLOCK_MARKERS) {
+        const withoutBlock = withBlockReplaced(remainingText, blockStart, blockEnd, '');
+        if (withoutBlock === null) continue;
+        remainingText = withoutBlock;
+        removedBlockCount += 1;
+    }
+    return removedBlockCount > 0 && remainingText.trim() === '';
+}
+
+function removeCodexGuidanceBlock(codexHome, blockStart, blockEnd) {
+    const agentsPath = join(codexHome, 'AGENTS.md');
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    if (!agentsEntry?.isFile()) return null;
+    const currentText = readFileSync(agentsPath, 'utf8');
+    const updatedText = withBlockReplaced(currentText, blockStart, blockEnd, '');
+    if (updatedText === null) return null;
+    const isLeftEmpty = updatedText.trim() === '';
+    if (isLeftEmpty) unlinkSync(agentsPath);
+    if (!isLeftEmpty) writeFileSync(agentsPath, updatedText, 'utf8');
+    return agentsPath;
 }
 
 /**
  * Remove the managed question block while keeping surrounding guidance bytes.
  *
+ * A file left holding only blank lines is deleted.
+ *
  * @param {string} codexHome
  * @returns {string|null} The changed path, or null when no block was removed.
  */
 export function removeCodexQuestionGuidance(codexHome) {
-    const agentsPath = join(codexHome, 'AGENTS.md');
-    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
-    if (!agentsEntry?.isFile()) return null;
-    const currentText = readFileSync(agentsPath, 'utf8');
-    const updatedText = withBlockReplaced(
-        currentText, QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END, '',
+    return removeCodexGuidanceBlock(
+        codexHome, QUESTION_PRESENTATION_BLOCK_START, QUESTION_PRESENTATION_BLOCK_END,
     );
-    if (updatedText === null) return null;
-    if (updatedText === '') unlinkSync(agentsPath);
-    if (updatedText !== '') writeFileSync(agentsPath, updatedText, 'utf8');
-    return agentsPath;
+}
+
+/**
+ * Remove the managed package-guidance block while keeping surrounding guidance bytes.
+ *
+ * A file left holding only blank lines is deleted.
+ *
+ * @param {string} codexHome
+ * @returns {string|null} The changed path, or null when no block was removed.
+ */
+export function removeCodexPackageGuidance(codexHome) {
+    return removeCodexGuidanceBlock(codexHome, PACKAGE_GUIDANCE_BLOCK_START, PACKAGE_GUIDANCE_BLOCK_END);
 }

package/bin/codex-skill-load-block.test.mjs

@@ -11,9 +11,11 @@ import {
     SKILL_LOAD_BLOCK_END,
     SKILL_LOAD_BLOCK_START,
     SKILL_LOAD_INSTRUCTION,
+    removeCodexPackageGuidance,
     removeCodexQuestionGuidance,
     withSkillLoadBlock,
     writeCodexAgentsGuidance,
+    writeCodexPackageGuidance,
     writeCodexQuestionGuidance,
 } from './codex-skill-load-block.mjs';
 
@@ -50,16 +52,19 @@ test('the instruction names the skill and binds spawned helpers', () => {
     assert.match(SKILL_LOAD_INSTRUCTION, /spawn_agent/);
 });
 
-test('a missing Codex guidance file is created holding only the skill-load block', (context) => {
+test('a missing Codex guidance file is created holding the skill-load block and the package guidance', (context) => {
     const homes = makeHomes(context);
 
     const writtenPath = writeGuidance(homes);
 
     assert.equal(writtenPath, homes.agentsPath);
-    assert.equal(readFileSync(homes.agentsPath, 'utf8'), EXPECTED_BLOCK);
+    assert.equal(
+        readFileSync(homes.agentsPath, 'utf8'),
+        `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+    );
 });
 
-test('existing guidance keeps every line and gains the skill-load block first', (context) => {
+test('existing guidance keeps every line between the skill-load block and the package guidance', (context) => {
     const homes = makeHomes(context);
     mkdirSync(homes.codexHome);
     writeFileSync(homes.agentsPath, '# pstack model configuration\n\nbug-fix: gpt-6-astra\n');
@@ -68,7 +73,7 @@ test('existing guidance keeps every line and gains the skill-load block first',
 
     assert.equal(
         readFileSync(homes.agentsPath, 'utf8'),
-        `${EXPECTED_BLOCK}\n# pstack model configuration\n\nbug-fix: gpt-6-astra\n`,
+        `${EXPECTED_BLOCK}\n# pstack model configuration\n\nbug-fix: gpt-6-astra\n\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
     );
 });
 
@@ -138,6 +143,78 @@ test('a link to a file the package does not own is left alone', (context) => {
     assert.equal(readFileSync(ownGuidancePath, 'utf8'), 'My own Codex notes\n');
 });
 
+function writePackageGuidance(homes) {
+    return writeCodexPackageGuidance(homes.codexHome, PACKAGE_GUIDANCE, homes.allPackageGuidancePaths);
+}
+
+test('package guidance creates a missing Codex file holding only the package block', (context) => {
+    const homes = makeHomes(context);
+
+    assert.equal(writePackageGuidance(homes), homes.agentsPath);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), guidanceBlock(PACKAGE_GUIDANCE));
+});
+
+test('package guidance replaces its block in place and a repeat write changes nothing', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, `Before\n${guidanceBlock('Old guidance\n')}After\n`);
+
+    assert.equal(writePackageGuidance(homes), homes.agentsPath);
+    const expectedGuidance = `Before\n${guidanceBlock(PACKAGE_GUIDANCE)}After\n`;
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), expectedGuidance);
+    assert.equal(writePackageGuidance(homes), null);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), expectedGuidance);
+});
+
+test('package guidance appends its block after custom notes', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, 'Custom agents\n');
+
+    writePackageGuidance(homes);
+
+    assert.equal(
+        readFileSync(homes.agentsPath, 'utf8'),
+        `Custom agents\n\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+    );
+});
+
+for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
+    test(`package guidance turns a link at ${linkName} into a file with only the package block`, (context) => {
+        const homes = makeHomes(context);
+        mkdirSync(homes.codexHome);
+        symlinkSync(homes[linkName], homes.agentsPath);
+
+        assert.equal(writePackageGuidance(homes), homes.agentsPath);
+        assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), false);
+        assert.equal(readFileSync(homes.agentsPath, 'utf8'), guidanceBlock(PACKAGE_GUIDANCE));
+    });
+}
+
+test('package guidance leaves a link to a file the package does not own unchanged', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const ownGuidancePath = join(homes.root, 'notes', 'codex.md');
+    mkdirSync(join(homes.root, 'notes'));
+    writeFileSync(ownGuidancePath, 'My own Codex notes\n');
+    symlinkSync(ownGuidancePath, homes.agentsPath);
+
+    assert.equal(writePackageGuidance(homes), null);
+    assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(ownGuidancePath, 'utf8'), 'My own Codex notes\n');
+});
+
+test('package guidance leaves an existing directory and its notes unchanged', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.agentsPath, { recursive: true });
+    const notesPath = join(homes.agentsPath, 'notes.md');
+    writeFileSync(notesPath, 'Directory notes\n');
+
+    assert.equal(writePackageGuidance(homes), null);
+    assert.equal(lstatSync(homes.agentsPath).isDirectory(), true);
+    assert.equal(readFileSync(notesPath, 'utf8'), 'Directory notes\n');
+});
+
 test('question guidance creates a missing Codex file and repeat writes preserve bytes', (context) => {
     const homes = makeHomes(context);
     const expectedBlock = `${QUESTION_PRESENTATION_BLOCK_START}\n${QUESTION_POLICY}${QUESTION_PRESENTATION_BLOCK_END}\n`;
@@ -245,6 +322,37 @@ test('question removal preserves a guidance directory and its notes', (context)
     assert.equal(readFileSync(notesPath, 'utf8'), 'Directory notes\n');
 });
 
+test('package and question removal delete a file left with only blank lines', (context) => {
+    const homes = makeHomes(context);
+    writePackageGuidance(homes);
+    writeCodexQuestionGuidance(homes.codexHome, QUESTION_POLICY);
+
+    assert.equal(removeCodexPackageGuidance(homes.codexHome), homes.agentsPath);
+    assert.equal(removeCodexQuestionGuidance(homes.codexHome), homes.agentsPath);
+    assert.equal(lstatSync(homes.agentsPath, { throwIfNoEntry: false }), undefined);
+});
+
+test('package removal keeps the custom text around its block', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, `Before\n${guidanceBlock(PACKAGE_GUIDANCE)}After\n`);
+
+    assert.equal(removeCodexPackageGuidance(homes.codexHome), homes.agentsPath);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), 'Before\nAfter\n');
+});
+
+test('package removal leaves a linked file and its target unchanged', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    mkdirSync(dirname(homes.sharedGuidancePath), { recursive: true });
+    writeFileSync(homes.sharedGuidancePath, guidanceBlock(PACKAGE_GUIDANCE));
+    symlinkSync(homes.sharedGuidancePath, homes.agentsPath);
+
+    assert.equal(removeCodexPackageGuidance(homes.codexHome), null);
+    assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(homes.sharedGuidancePath, 'utf8'), guidanceBlock(PACKAGE_GUIDANCE));
+});
+
 test('question removal leaves a missing guidance file absent', (context) => {
     const homes = makeHomes(context);
 

package/bin/install.mjs

@@ -53,8 +53,10 @@ import {
 } from './install-pstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
 import {
+    removeCodexPackageGuidance,
     removeCodexQuestionGuidance,
     writeCodexAgentsGuidance,
+    writeCodexPackageGuidance,
     writeCodexQuestionGuidance,
 } from './codex-skill-load-block.mjs';
 import {
@@ -2606,7 +2608,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     ];
 
     const allInstalledFiles = [];
-    const allQuestionGuidancePaths = [];
+    const allCodexGuidancePaths = [];
     const allUserOwnedPreferencePaths = new Set();
     const summary = {};
     for (const directory of CONTENT_DIRECTORIES) {
@@ -2758,6 +2760,8 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.log(`  Pstack: retired release store removed from ${retiredPstack.removedStorePath}`);
         }
     }
+    const packageGuidanceText = selectedGroups ? '' : readFileSync(join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8');
+    const allPackageGuidancePaths = [join(CLAUDE_HOME, 'AGENTS.md'), join(AGENTS_HOME, 'AGENTS.md')];
     if (!selectedGroups && shouldInstallPstackPlugin()) {
         const pstackPlugin = installPstackPluginForHosts();
         summary.pstackPlugin = pstackPlugin;
@@ -2773,8 +2777,8 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             }
             const skillLoadGuidancePath = writeCodexAgentsGuidance(
                 INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
-                readFileSync(join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8'),
-                [join(CLAUDE_HOME, 'AGENTS.md'), join(AGENTS_HOME, 'AGENTS.md')],
+                packageGuidanceText,
+                allPackageGuidancePaths,
             );
             if (skillLoadGuidancePath) {
                 console.log(`  \u2713 ${skillLoadGuidancePath} (Codex skill-load line)`);
@@ -2787,13 +2791,22 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         }
     }
     if (!selectedGroups) {
+        const packageGuidancePath = writeCodexPackageGuidance(
+            INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+            packageGuidanceText,
+            allPackageGuidancePaths,
+        );
+        if (packageGuidancePath) {
+            allCodexGuidancePaths.push(packageGuidancePath);
+            console.log(`  \u2713 ${packageGuidancePath} (Codex package guidance)`);
+        }
         const questionGuidancePath = writeCodexQuestionGuidance(
             INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
             readFileSync(join(PACKAGE_ROOT, 'rules', 'question-presentation.md'), 'utf8'),
         );
-        if (questionGuidancePath) allQuestionGuidancePaths.push(questionGuidancePath);
+        if (questionGuidancePath) allCodexGuidancePaths.push(questionGuidancePath);
     }
-    syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
+    syncWrittenPaths([...allInstalledFiles, ...allCodexGuidancePaths, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
     throwIfFault(FAULT_PHASES.BEFORE_DURABLE_PROMOTION);
     const shouldInstallAnyHooks = shouldInstallAllHooks || (allowedHookFiles && allowedHookFiles.size > 0);
@@ -2834,7 +2847,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         summary.hookGroups = totalHookGroups;
         summary.codexHookGroups = totalCodexHookGroups;
         console.log(`  Hook groups: ${totalHookGroups} merged into settings.json, ${totalCodexHookGroups} merged into hooks.json`);
-        syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
+        syncWrittenPaths([...allInstalledFiles, ...allCodexGuidancePaths, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
 
         console.warn(
@@ -2856,7 +2869,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.warn(`  Git hooks: ${gitHookInstallationResult.hooksPathConfigurationResult.reason}`);
         }
         console.log(`  Git hook shims: ${gitHookInstallationResult.createdShimPaths.length} files (${KNOWN_GIT_HOOK_NAMES.join(', ')})`);
-        syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
+        syncWrittenPaths([...allInstalledFiles, ...allCodexGuidancePaths, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
         throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
 
@@ -2876,7 +2889,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.warn(`      ${mypyIniInstallResult.expectedLine}`);
         }
     } else {
-        syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, ...publishedPointerPaths]);
+        syncWrittenPaths([...allInstalledFiles, ...allCodexGuidancePaths, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
         throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
         throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
@@ -2964,7 +2977,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         ? manifestFilesWithFailedPrunes(allManagedInstalledFiles, failedPrunePaths)
         : unionOnComparisonKey(priorManifestFiles || [], allManagedInstalledFiles);
     writeManifest(manifestFiles, manifestSkillNames, summary.managedPermissions.managedPermissions);
-    syncWrittenPaths([...allInstalledFiles, ...allQuestionGuidancePaths, MANIFEST_FILE, plan.settingsPath, ...publishedPointerPaths]);
+    syncWrittenPaths([...allInstalledFiles, ...allCodexGuidancePaths, MANIFEST_FILE, plan.settingsPath, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_MANIFEST_WRITE);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
@@ -3143,6 +3156,7 @@ function executeUninstallPlan(plan, helpers = {}) {
             `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME}, outside ${MYPY_INI_INSTALL_PATH}, outside ${INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory}, outside ${INSTALL_ROOT_RESOLUTION.cursorInstallDirectory}, and outside ${AGENTS_HOME}`,
         );
     }
+    removeCodexPackageGuidance(INSTALL_ROOT_RESOLUTION.codexHomeDirectory);
     removeCodexQuestionGuidance(INSTALL_ROOT_RESOLUTION.codexHomeDirectory);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
 

package/bin/install.question-presentation.test.mjs

@@ -81,7 +81,7 @@ test('uninstall removes question-only Codex guidance', (context) => {
     assert.equal(existsSync(codexGuidancePath), false);
 });
 
-test('uninstall removes the question block and preserves surrounding custom guidance', (context) => {
+test('uninstall removes the managed blocks and preserves surrounding custom guidance', (context) => {
     const homeDirectory = makeScratchHome(context);
     const codexGuidancePath = join(homeDirectory, '.codex', 'AGENTS.md');
     mkdirSync(dirname(codexGuidancePath), { recursive: true });
@@ -94,7 +94,7 @@ test('uninstall removes the question block and preserves surrounding custom guid
     const removal = installInScratchHome(homeDirectory, ['--uninstall']);
 
     assert.equal(removal.status, 0, removal.stdout + removal.stderr);
-    assert.equal(readFileSync(codexGuidancePath, 'utf8'), `${customGuidance}\nTrailing notes\n`);
+    assert.equal(readFileSync(codexGuidancePath, 'utf8'), `${customGuidance}\n\nTrailing notes\n`);
 });
 
 for (const eachPriorGuidance of [null, '# Personal guidance\n']) {

package/bin/install.test.mjs

@@ -54,6 +54,8 @@ import {
 } from './install.mjs';
 import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
+    PACKAGE_GUIDANCE_BLOCK_END,
+    PACKAGE_GUIDANCE_BLOCK_START,
     SKILL_LOAD_BLOCK_START,
     SKILL_LOAD_INSTRUCTION,
     QUESTION_PRESENTATION_BLOCK_START,
@@ -3162,6 +3164,109 @@ test('--no-pstack skips the plugin and delivers Codex question guidance', t => {
     );
 });
 
+const PSTACK_TEST_PACKAGE_GUIDANCE = readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), '..', 'AGENTS.md'),
+    'utf8',
+);
+
+function assertHoldsPackageGuidance(codexGuidance) {
+    assert.ok(codexGuidance.includes(`${PACKAGE_GUIDANCE_BLOCK_START}\n${PSTACK_TEST_PACKAGE_GUIDANCE}`));
+    assert.ok(codexGuidance.includes(PACKAGE_GUIDANCE_BLOCK_END));
+}
+
+test('a fresh full install writes the package guidance into Codex AGENTS.md', t => {
+    const sandbox = pstackPluginSandbox(t);
+
+    runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
+
+    const codexGuidance = readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8');
+    assertHoldsPackageGuidance(codexGuidance);
+    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+});
+
+test('--no-pstack writes package and question guidance without the skill-load block', t => {
+    const sandbox = pstackPluginSandbox(t);
+
+    runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], sandbox.environment);
+
+    assert.deepEqual(
+        sandbox.recordedCommands().filter(eachCommand => eachCommand.startsWith('codex plugin')),
+        [],
+    );
+    const codexGuidance = readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8');
+    assertHoldsPackageGuidance(codexGuidance);
+    assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+    assert.equal(codexGuidance.includes(SKILL_LOAD_BLOCK_START), false);
+});
+
+test('--no-pstack replaces an outdated package block and keeps the text around it', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(
+        join(codexHome, 'AGENTS.md'),
+        `My notes\n${PACKAGE_GUIDANCE_BLOCK_START}\nOld guidance\n${PACKAGE_GUIDANCE_BLOCK_END}\nMore notes\n`,
+    );
+
+    runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], sandbox.environment);
+
+    const codexGuidance = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.ok(codexGuidance.startsWith(`My notes\n${PACKAGE_GUIDANCE_BLOCK_START}\n${PSTACK_TEST_PACKAGE_GUIDANCE}`));
+    assert.ok(codexGuidance.includes(`${PACKAGE_GUIDANCE_BLOCK_END}\nMore notes\n`));
+    assert.equal(codexGuidance.includes('Old guidance'), false);
+    assert.equal(codexGuidance.includes(SKILL_LOAD_BLOCK_START), false);
+});
+
+for (const linkTargetDirectory of ['.claude', '.agents']) {
+    test(`--no-pstack turns a Codex link to the ${linkTargetDirectory} package guidance into a file`, t => {
+        const sandbox = pstackPluginSandbox(t);
+        const codexHome = join(sandbox.homeDirectory, '.codex');
+        const codexAgentsPath = join(codexHome, 'AGENTS.md');
+        mkdirSync(codexHome, { recursive: true });
+        symlinkSync(join(sandbox.homeDirectory, linkTargetDirectory, 'AGENTS.md'), codexAgentsPath);
+
+        runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], sandbox.environment);
+
+        assert.equal(lstatSync(codexAgentsPath).isSymbolicLink(), false);
+        const codexGuidance = readFileSync(codexAgentsPath, 'utf8');
+        assertHoldsPackageGuidance(codexGuidance);
+        assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+        assert.equal(codexGuidance.includes(SKILL_LOAD_BLOCK_START), false);
+    });
+}
+
+test('--no-pstack leaves a Codex link to a file the package does not own unchanged', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    const codexAgentsPath = join(codexHome, 'AGENTS.md');
+    const ownGuidancePath = join(sandbox.homeDirectory, 'notes', 'codex.md');
+    mkdirSync(codexHome, { recursive: true });
+    mkdirSync(dirname(ownGuidancePath), { recursive: true });
+    writeFileSync(ownGuidancePath, 'My own Codex notes\n');
+    symlinkSync(ownGuidancePath, codexAgentsPath);
+
+    runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], sandbox.environment);
+
+    assert.equal(lstatSync(codexAgentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(ownGuidancePath, 'utf8'), 'My own Codex notes\n');
+});
+
+test('a pstack install after a --no-pstack install seeds the Codex model sheet', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], sandbox.environment);
+
+    runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
+
+    assert.match(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), /^session hook: on$/m);
+    const codexGuidance = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.match(codexGuidance, /^feature, refactoring: gpt-6-sol$/m);
+    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assertHoldsPackageGuidance(codexGuidance);
+    assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+});
+
 function continuityCommandCount(configurationPath) {
     if (!existsSync(configurationPath)) return 0;
     const configuration = JSON.parse(readFileSync(configurationPath, 'utf8'));

package/bin/seed-codex-pstack-models.mjs

@@ -1,7 +1,7 @@
 import { copyFileSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, constants as filesystemConstants } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { hasOnlyQuestionPresentationBlock } from './codex-skill-load-block.mjs';
+import { hasOnlyPackageManagedBlocks } from './codex-skill-load-block.mjs';
 
 const CODEX_PRESET_PATH = fileURLToPath(new URL('../pstack-codex-models.md', import.meta.url));
 
@@ -16,7 +16,7 @@ export function seedCodexPstackModels(codexHome, writeAgentGuidance = writeFileS
     const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
     if (agentsEntry && !agentsEntry.isFile()) return null;
     const existingGuidance = agentsEntry ? readFileSync(agentsPath, 'utf8') : '';
-    if (agentsEntry && !hasOnlyQuestionPresentationBlock(existingGuidance)) return null;
+    if (agentsEntry && !hasOnlyPackageManagedBlocks(existingGuidance)) return null;
 
     const preset = readFileSync(CODEX_PRESET_PATH, 'utf8');
     const agentGuidance = preset.replace(/^session hook: on\n?$/m, '');

package/bin/seed-codex-pstack-models.test.mjs

@@ -4,7 +4,14 @@ import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, sy
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
-import { QUESTION_PRESENTATION_BLOCK_END, QUESTION_PRESENTATION_BLOCK_START } from './codex-skill-load-block.mjs';
+import {
+    PACKAGE_GUIDANCE_BLOCK_END,
+    PACKAGE_GUIDANCE_BLOCK_START,
+    QUESTION_PRESENTATION_BLOCK_END,
+    QUESTION_PRESENTATION_BLOCK_START,
+    SKILL_LOAD_BLOCK_END,
+    SKILL_LOAD_BLOCK_START,
+} from './codex-skill-load-block.mjs';
 
 const QUESTION_GUIDANCE = `${QUESTION_PRESENTATION_BLOCK_START}\nAsk one question.\n${QUESTION_PRESENTATION_BLOCK_END}\n`;
 
@@ -114,3 +121,47 @@ test('a linked question-only Codex file does not trigger model seeding', (contex
     assert.equal(lstatSync(join(codexHome, 'AGENTS.md')).isSymbolicLink(), true);
     assert.equal(readFileSync(linkedGuidancePath, 'utf8'), QUESTION_GUIDANCE);
 });
+
+const PACKAGE_GUIDANCE = `${PACKAGE_GUIDANCE_BLOCK_START}\nStatus\n${PACKAGE_GUIDANCE_BLOCK_END}\n`;
+const SKILL_LOAD_GUIDANCE = `${SKILL_LOAD_BLOCK_START}\nLoad the skill.\n${SKILL_LOAD_BLOCK_END}\n`;
+
+function codexHomeHolding(context, existingGuidance) {
+    const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    const codexHome = join(root, '.codex');
+    mkdirSync(codexHome);
+    writeFileSync(join(codexHome, 'AGENTS.md'), existingGuidance);
+    return codexHome;
+}
+
+for (const [label, existingGuidance] of [
+    ['package block', PACKAGE_GUIDANCE],
+    ['package then question blocks', `${PACKAGE_GUIDANCE}\n${QUESTION_GUIDANCE}`],
+    ['question then package blocks', `${QUESTION_GUIDANCE}\n${PACKAGE_GUIDANCE}`],
+    ['all three managed blocks', `${SKILL_LOAD_GUIDANCE}\n${PACKAGE_GUIDANCE}\n${QUESTION_GUIDANCE}`],
+]) {
+    test(`a Codex file holding only the ${label} receives model defaults and keeps its blocks`, (context) => {
+        const codexHome = codexHomeHolding(context, existingGuidance);
+
+        const paths = seedCodexPstackModels(codexHome);
+
+        assert.deepEqual(paths, [join(codexHome, 'pstack-models.md'), join(codexHome, 'AGENTS.md')]);
+        const agents = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+        assert.match(agents, /^feature, refactoring: gpt-6-sol$/m);
+        assert.ok(agents.endsWith(existingGuidance));
+    });
+}
+
+for (const [label, existingGuidance] of [
+    ['an empty file', ''],
+    ['a package block with personal notes', `${PACKAGE_GUIDANCE}My notes\n`],
+    ['personal notes before managed blocks', `My notes\n${PACKAGE_GUIDANCE}\n${QUESTION_GUIDANCE}`],
+]) {
+    test(`${label} does not trigger model seeding`, (context) => {
+        const codexHome = codexHomeHolding(context, existingGuidance);
+
+        assert.equal(seedCodexPstackModels(codexHome), null);
+        assert.equal(existsSync(join(codexHome, 'pstack-models.md')), false);
+        assert.equal(readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'), existingGuidance);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.32.0",
+    "version": "8.32.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {