claude-dev-env 8.28.0 → 8.29.0

package/bin/install.test.mjs

@@ -56,6 +56,7 @@ import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
     SKILL_LOAD_BLOCK_START,
     SKILL_LOAD_INSTRUCTION,
+    QUESTION_PRESENTATION_BLOCK_START,
     withSkillLoadBlock,
 } from './codex-skill-load-block.mjs';
 
@@ -3094,10 +3095,9 @@ test('a repeat install preserves Codex pstack configuration', t => {
 
     runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
 
-    assert.equal(
-        readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'),
-        withSkillLoadBlock('Custom Codex guidance\n'),
-    );
+    const codexGuidance = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.ok(codexGuidance.startsWith(withSkillLoadBlock('Custom Codex guidance\n')));
+    assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
     assert.equal(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), 'session hook: off\n');
 });
 
@@ -3140,10 +3140,13 @@ test('an absent host command is reported and leaves the other host installed', t
         [],
     );
     assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'pstack-models.md')), false);
-    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md')), false);
+    assert.match(
+        readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8'),
+        /<!-- claude-dev-env question presentation: start -->/,
+    );
 });
 
-test('--no-pstack leaves both hosts untouched', t => {
+test('--no-pstack skips the plugin and delivers Codex question guidance', t => {
     const sandbox = pstackPluginSandbox(t);
 
     const installerOutput = runPstackInstaller(
@@ -3153,7 +3156,10 @@ test('--no-pstack leaves both hosts untouched', t => {
     assert.deepEqual(sandbox.recordedCommands(), []);
     assert.doesNotMatch(installerOutput, /Pstack \(/);
     assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'pstack-models.md')), false);
-    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md')), false);
+    assert.match(
+        readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8'),
+        /<!-- claude-dev-env question presentation: start -->/,
+    );
 });
 
 function continuityCommandCount(configurationPath) {

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

@@ -1,6 +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';
 
 const CODEX_PRESET_PATH = fileURLToPath(new URL('../pstack-codex-models.md', import.meta.url));
 
@@ -11,14 +12,24 @@ function pathExists(path) {
 export function seedCodexPstackModels(codexHome, writeAgentGuidance = writeFileSync) {
     const sheetPath = join(codexHome, 'pstack-models.md');
     const agentsPath = join(codexHome, 'AGENTS.md');
-    if (pathExists(sheetPath) || pathExists(agentsPath)) return null;
+    if (pathExists(sheetPath)) return null;
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    if (agentsEntry && !agentsEntry.isFile()) return null;
+    const existingGuidance = agentsEntry ? readFileSync(agentsPath, 'utf8') : '';
+    if (agentsEntry && !hasOnlyQuestionPresentationBlock(existingGuidance)) return null;
 
     const preset = readFileSync(CODEX_PRESET_PATH, 'utf8');
     const agentGuidance = preset.replace(/^session hook: on\n?$/m, '');
+    const separator = agentGuidance.endsWith('\n') ? '\n' : '\n\n';
+    const combinedGuidance = existingGuidance
+        ? `${agentGuidance}${separator}${existingGuidance}`
+        : agentGuidance;
     mkdirSync(codexHome, { recursive: true });
     copyFileSync(CODEX_PRESET_PATH, sheetPath, filesystemConstants.COPYFILE_EXCL);
     try {
-        writeAgentGuidance(agentsPath, agentGuidance, { encoding: 'utf8', flag: 'wx' });
+        writeAgentGuidance(agentsPath, combinedGuidance, {
+            encoding: 'utf8', flag: agentsEntry ? 'w' : 'wx',
+        });
     } catch (writeError) {
         unlinkSync(sheetPath);
         throw writeError;

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

@@ -1,9 +1,12 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 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';
+
+const QUESTION_GUIDANCE = `${QUESTION_PRESENTATION_BLOCK_START}\nAsk one question.\n${QUESTION_PRESENTATION_BLOCK_END}\n`;
 
 test('fresh Codex home gets the selected roles and hook setting', (context) => {
     const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
@@ -70,3 +73,44 @@ for (const existingFile of ['AGENTS.md', 'pstack-models.md']) {
         assert.equal(existsSync(join(codexHome, existingFile === 'AGENTS.md' ? 'pstack-models.md' : 'AGENTS.md')), false);
     });
 }
+
+test('a question-only Codex file receives model defaults and keeps its block', (context) => {
+    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'), QUESTION_GUIDANCE);
+
+    const paths = seedCodexPstackModels(codexHome);
+
+    assert.deepEqual(paths, [join(codexHome, 'pstack-models.md'), join(codexHome, 'AGENTS.md')]);
+    assert.match(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), /^session hook: on$/m);
+    const agents = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.match(agents, /^feature, refactoring: gpt-6-sol$/m);
+    assert.ok(agents.endsWith(QUESTION_GUIDANCE));
+});
+
+test('a question block with personal notes does not trigger model seeding', (context) => {
+    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'), `${QUESTION_GUIDANCE}My notes\n`);
+
+    assert.equal(seedCodexPstackModels(codexHome), null);
+    assert.equal(existsSync(join(codexHome, 'pstack-models.md')), false);
+});
+
+test('a linked question-only Codex file does not trigger model seeding', (context) => {
+    const root = mkdtempSync(join(tmpdir(), 'cde-pstack-models-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    const codexHome = join(root, '.codex');
+    const linkedGuidancePath = join(root, 'linked-guidance.md');
+    mkdirSync(codexHome);
+    writeFileSync(linkedGuidancePath, QUESTION_GUIDANCE);
+    symlinkSync(linkedGuidancePath, join(codexHome, 'AGENTS.md'));
+
+    assert.equal(seedCodexPstackModels(codexHome), null);
+    assert.equal(lstatSync(join(codexHome, 'AGENTS.md')).isSymbolicLink(), true);
+    assert.equal(readFileSync(linkedGuidancePath, 'utf8'), QUESTION_GUIDANCE);
+});

package/package.json

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

package/rules/question-presentation.md

@@ -0,0 +1,12 @@
+# Present questions clearly
+
+Before asking for input, give a short formatted brief in chat. Put the context and the effect of each choice there. Add a visual or artifact only when it helps the decision.
+
+For Codex, when a visual comparison helps, discover callable tools for Page creation, visualization upload, and Page opening. Create the comparison, upload its visualization, and open its Page in the current task before asking. If a tool is unavailable, creation, upload, or opening fails, or opening queues, put the comparison in chat before asking. Inline Visualize references appear only in final replies. Use the user's submitted answer for the decision. An async dispatch acknowledgement or saved visual supplies context only. Wait for the answer before work that depends on it.
+
+Ask one short, self-contained question with two or three clear choices. Use short labels, and keep each supported choice description to one short sentence. Use the same labels in the chat brief, comparison, and picker.
+
+Discover the current session's native question tool and its schema. Claude may expose `AskUserQuestion`.
+Codex may expose `request_user_input_async` or `request_user_input`. Follow the tool's mode restrictions.
+Put the question in its declared title or question field and choices in its declared string or object fields.
+When no native tool is usable, ask the short question and choices in chat.

package/rules/verify-before-asking.md

@@ -8,7 +8,7 @@ If a question can be answered by inspecting files, running a command, querying a
 
 ## Decision Checklist
 
-Before writing any AskUserQuestion or asking a clarifying question in chat, evaluate:
+Before using the current session's native question tool or asking a clarifying question in chat, evaluate:
 
 | Check | Action |
 |---|---|
@@ -21,14 +21,14 @@ Before writing any AskUserQuestion or asking a clarifying question in chat, eval
 | Is the answer retrievable from any available MCP tool? | Use the tool. |
 | Did the user already state a criterion, standard, or line that decides this? | Apply it, state the call and the reason, and keep going. |
 
-Only after confirming the answer cannot be obtained through any available tool, ask the user.
+Only after confirming the answer cannot be obtained through any available tool, ask the user. Present the question using [Present questions clearly](question-presentation.md).
 
 ## Prior-session facts expire
 
 A path, port, branch name, or config value you recall from an earlier session counts as unanswered until a tool re-checks it this session. Memory records what was true when it was written; the file may have moved, the port may be down, the branch may have merged. Treat every recalled fact as a claim to re-ground, not an answer to reuse.
 
 - When a tool can settle it, re-check in silence and act on the fresh result — no question to the user.
-- When no tool can settle it and the user has a stake in the answer, ask through `AskUserQuestion`.
+- When no tool can settle it and the user has a stake in the answer, use the current session's native question tool when available.
 
 ## Questions That Belong to the User