claude-dev-env 8.85.0 → 8.85.2

package/.agents/skills/efficient-review/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: efficient-review
+description: >-
+  Run one low-cost code review of the current branch, or of a branch in another
+  repository, as a headless Claude run on haiku with the slim review profile.
+  An auto run lets the account broker pick the account. A headless run names
+  the account. Triggers: /efficient-review, "efficient review", "cheap review",
+  "haiku review of this branch".
+---
+
+# Efficient review
+
+This skill runs one headless code review of a branch on haiku and prints its findings. Pick the mode, run the planner, then run the review on the machine that holds the Claude accounts, or through the agent-pc runner from a cloud session.
+
+Argument shape: `/efficient-review [auto|headless] [account] [model=] [effort=] [level=] [base=]`. Pass `model=` only as the Defaults section allows.
+A blank argument comes from [`defaults.json`](defaults.json).
+
+## Defaults
+
+**Always run the review on haiku.** `defaults.json` names `haiku`, and a blank `model` input runs it. Pass `model=` or the workflow's `model` input only when the owner's own message names the family as a directive, such as "run this review on sonnet". Then run it on that family. Do not ask which model to use. Do not change the model on your own, for depth, for cost, or because passes keep finding issues. A stream of findings is a reason to fix the findings and run haiku again.
+
+**The review must run headless.** Never spawn the review as an Agent subagent in this session. A subagent runs inside the parent session, so it cannot load the slim profile's setting sources, plugin folder, MCP config, or auto-compact window. `defaults.json` holds a headless mode, and `load_defaults` refuses any other mode.
+
+## Subcommands
+
+Run each one as `python -m tools.efficient_review <subcommand> <arguments>` from the checkout that contains `tools/efficient_review.py`.
+
+| Subcommand | Action |
+|---|---|
+| `plan` | Prints the mode, account, model family, harness, effort, level, base, and the prompt. |
+| `accounts` | Lists the Claude accounts a headless run can name. |
+| `run` | Runs a headless or auto review and prints the review, the served models, and the saved file. |
+
+## Modes
+
+| Mode | Picked when | Account |
+|---|---|---|
+| auto | No mode word and no account. The word `auto` picks it too. | The account broker picks it. Ask nothing. |
+| headless | The word `headless`, or an account launcher name. | Required. With no account named, ask for one. |
+
+A model is a family name: haiku, sonnet, opus, sol, or luna. The planner refuses a versioned model ID. `codex review` takes no level, so the planner refuses `level=` with sol or luna.
+
+## 1. Headless mode with no account
+
+Run `python -m tools.efficient_review accounts`. Ask with the session's question tool, one option per listed account, and wait for the answer. The answer is the account. On the machine that holds the launchers, the list comes from the `claude-*.cmd` launchers, without `claude-base`, `claude-raw`, and `claude-kimi`. In the cloud the list is the known roster.
+
+## 2. Headless or auto on that machine
+
+Run `python -m tools.efficient_review run <arguments> --repository <checkout>`. When the checkout has no launcher folder, go to step 3.
+
+- It builds the slim profile from `tools.review_profile` into a temp folder.
+- Auto asks `account_broker.py choose --product claude` for the account.
+- It runs the account launcher with `-p`, the model alias, the effort, the profile arguments, and the environment. The system prompt file holds the review rules from the checkout that contains the runner, and the code standards. The prompt and the diff against the base go on standard input.
+- A sol or luna family runs `codex review` on the newest slug of that family. The log prints that slug.
+- It prints the review, the served models from the stream's `modelUsage` keys, and the saved file. The review and its record go to a temp folder outside the repository.
+
+## 3. Headless or auto from a cloud session
+
+The cloud container has no other Claude accounts, so the review runs on the agent-pc runner. Read [reference/cloud-session.md](reference/cloud-session.md).
+
+## Reading guide
+
+| File | What it does |
+|---|---|
+| [`reference/cloud-session.md`](reference/cloud-session.md) | Dispatching the review from a cloud session and reading its results branch. |
+| [`defaults.json`](defaults.json) | The default model family, effort, level, prompt, base, profile, advisor, validator, mode, and timeout. |
+
+## Common pitfalls
+
+- **Picking a stronger model after several passes.** Fix the findings and run haiku again.
+- **Setting a valid finding aside.** Check each finding against the code. Fix every one that holds in the same branch, even when it reaches files the diff did not touch. Answer only the findings that fail the check, with the file and line that rules each out.
+- **Asking which model to use.** The answer is haiku. When the owner names another family, run it without a confirmation question.
+- **Spawning the review as a subagent.** The review loses the slim profile. Run it headless.
+- **Dispatching from the branch under review.** The workflow runs only from `main`.
+
+## Out of scope
+
+- The `validator` default stays `off`.
+- A fixer step after the review. The skill has no fixer step.

package/.agents/skills/efficient-review/defaults.json

@@ -0,0 +1,12 @@
+{
+  "model": "haiku",
+  "effort": "high",
+  "level": "high",
+  "prompt": "/code-review {level} --max-findings all {base}",
+  "base": "main",
+  "profile": "slim",
+  "advisor": "none",
+  "validator": "off",
+  "mode": "auto",
+  "timeout_minutes": 60
+}

package/.agents/skills/efficient-review/reference/cloud-session.md

@@ -0,0 +1,13 @@
+# Headless or auto from a cloud session
+
+The cloud container has no other Claude accounts, so the review runs on the agent-pc runner.
+
+1. From the checkout that contains `tools/efficient_review.py`, dispatch `.github/workflows/efficient-review.yml` on ref `main`. The job runs only from `main`, so the runner executes the reviewed tool code and never the branch under review. Inputs: `account` (blank means auto), `effort`, `level`, `base`, `ref` (the branch to review), and `repository` (the `owner/name` to review when it is not that checkout). Leave `model` blank.
+2. Wait for the run to finish.
+3. Read `review.md` from the results branch `efficient-review-results/<run id>-<attempt>`. The branch holds that file and `review.json`. The commit message names the account, the launcher, and the served models. Print the review and the served models.
+
+A review of another repository checks it out with the read token configured for that workflow.
+
+To review a pull request in the checkout that contains the workflow, pass its number as `pull_request` and leave `ref` blank. The run reviews the pull request head, then posts each finding on it as a review thread.
+
+For a pull request in this package's public repository, pass `repository` as `jl-cmd/claude-dev-env` and `pull_request` together. The workflow accepts that repository name. The run posts nothing on the public pull request. When the review lists findings, it dispatches the landing repair with the pull request number and the results branch.

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

@@ -3,9 +3,6 @@ import { dirname, join, resolve } from 'node:path';
 
 export const SKILL_LOAD_BLOCK_START = '<!-- claude-dev-env skill load: start -->';
 export const SKILL_LOAD_BLOCK_END = '<!-- claude-dev-env skill load: end -->';
-export const SKILL_LOAD_INSTRUCTION = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
-    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
-    + 'including a helper started with spawn_agent, whatever its task message says.';
 export const PACKAGE_GUIDANCE_BLOCK_START = '<!-- claude-dev-env package guidance: start -->';
 export const PACKAGE_GUIDANCE_BLOCK_END = '<!-- claude-dev-env package guidance: end -->';
 export const QUESTION_PRESENTATION_BLOCK_START = '<!-- claude-dev-env question presentation: start -->';
@@ -39,17 +36,24 @@ function withBlockReplaced(guidanceText, blockStart, blockEnd, block) {
 }
 
 /**
- * Return the Codex guidance text with the package's skill-load block in it.
+ * Return guidance text with every complete skill-load block removed.
  *
- * Codex starts a spawn_agent helper without running any hook, so the global
- * AGENTS.md is the one channel that reaches every helper. A block already in
- * the text is replaced where it stands; otherwise the block goes first.
+ * When a block is the start of the remaining text, one following blank line is
+ * removed with it. A start marker with no end marker stays.
  */
-export function withSkillLoadBlock(guidanceText) {
-    const block = managedBlock(SKILL_LOAD_BLOCK_START, SKILL_LOAD_INSTRUCTION, SKILL_LOAD_BLOCK_END);
-    const replacedText = withBlockReplaced(guidanceText, SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END, block);
-    if (replacedText !== null) return replacedText;
-    return guidanceText ? `${block}\n${guidanceText}` : block;
+export function withoutSkillLoadBlock(guidanceText) {
+    let remainingText = guidanceText;
+    let removedBlockCount = 0;
+    while (remainingText.includes(SKILL_LOAD_BLOCK_START)) {
+        const blockStartsAtTop = remainingText.startsWith(SKILL_LOAD_BLOCK_START);
+        const replacedText = withBlockReplaced(remainingText, SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END, '');
+        if (replacedText === null || replacedText === remainingText) break;
+        removedBlockCount += 1;
+        remainingText = blockStartsAtTop && replacedText.startsWith('\n')
+            ? replacedText.slice(1)
+            : replacedText;
+    }
+    return removedBlockCount === 0 ? guidanceText : remainingText;
 }
 
 function withPackageGuidanceBlock(guidanceText, packageGuidanceText) {
@@ -84,7 +88,7 @@ function writeCodexGuidanceFile(codexHome, allPackageGuidancePaths, transformGui
     const isPackageGuidanceLink = agentsEntry?.isSymbolicLink() ?? false;
     if (isPackageGuidanceLink && !linksToPackageGuidance(agentsPath, allPackageGuidancePaths)) return null;
     const currentText = agentsEntry && !isPackageGuidanceLink ? readFileSync(agentsPath, 'utf8') : '';
-    const updatedText = transformGuidance(currentText);
+    const updatedText = transformGuidance(withoutSkillLoadBlock(currentText));
     if (!isPackageGuidanceLink && updatedText === currentText) return null;
     mkdirSync(codexHome, { recursive: true });
     if (isPackageGuidanceLink) unlinkSync(agentsPath);
@@ -93,29 +97,24 @@ function writeCodexGuidanceFile(codexHome, allPackageGuidancePaths, transformGui
 }
 
 /**
- * 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.
+ * Remove a skill-load block and write package guidance into CODEX_HOME/AGENTS.md.
  *
- * Returns the file path when the file changed, and null otherwise.
+ * Link handling matches writeCodexPackageGuidance. 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),
-    );
+    return writeCodexPackageGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths);
 }
 
 /**
  * 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.
+ * An existing skill-load block is removed. 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. A link to any other file is left
+ * alone.
+ *
+ * Returns the file path when the file changed, and null otherwise.
  */
 export function writeCodexPackageGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
     return writeCodexGuidanceFile(

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

@@ -10,11 +10,10 @@ import {
     QUESTION_PRESENTATION_BLOCK_START,
     SKILL_LOAD_BLOCK_END,
     SKILL_LOAD_BLOCK_START,
-    SKILL_LOAD_INSTRUCTION,
     removeCodexDeepenGuidance,
     removeCodexPackageGuidance,
     removeCodexQuestionGuidance,
-    withSkillLoadBlock,
+    withoutSkillLoadBlock,
     DEEPEN_GUIDANCE_BLOCK_END,
     DEEPEN_GUIDANCE_BLOCK_START,
     DEEPEN_GUIDANCE_TEXT,
@@ -24,7 +23,10 @@ import {
     writeCodexQuestionGuidance,
 } from './codex-skill-load-block.mjs';
 
-const EXPECTED_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+const STALE_SKILL_LOAD_SENTENCE = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
+    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
+    + 'including a helper started with spawn_agent, whatever its task message says.';
+const STALE_SKILL_LOAD_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${STALE_SKILL_LOAD_SENTENCE}\n${SKILL_LOAD_BLOCK_END}\n`;
 const PACKAGE_GUIDANCE = 'Status\n\nChanged / proof / blocked.\n';
 const QUESTION_POLICY = '# Present questions clearly\n\nAsk one question.\n';
 
@@ -52,34 +54,44 @@ function writeGuidance(homes) {
     return writeCodexAgentsGuidance(homes.codexHome, PACKAGE_GUIDANCE, homes.allPackageGuidancePaths);
 }
 
-test('the instruction names the skill and binds spawned helpers', () => {
-    assert.match(SKILL_LOAD_INSTRUCTION, /pstack:poteto-mode/);
-    assert.match(SKILL_LOAD_INSTRUCTION, /spawn_agent/);
+test('a complete skill-load block is removed and the lines around it stay', () => {
+    assert.equal(withoutSkillLoadBlock(`Intro\n${STALE_SKILL_LOAD_BLOCK}Outro\n`), 'Intro\nOutro\n');
+    assert.equal(withoutSkillLoadBlock(`${STALE_SKILL_LOAD_BLOCK}\nNotes\n`), 'Notes\n');
+    assert.equal(
+        withoutSkillLoadBlock(`${STALE_SKILL_LOAD_BLOCK}\n${STALE_SKILL_LOAD_BLOCK}\nNotes\n`),
+        'Notes\n',
+    );
+    assert.equal(
+        withoutSkillLoadBlock(`${SKILL_LOAD_BLOCK_START}\nHalf a block\n`),
+        `${SKILL_LOAD_BLOCK_START}\nHalf a block\n`,
+    );
 });
 
-test('a missing Codex guidance file is created holding the skill-load block and the package guidance', (context) => {
+test('a missing Codex guidance file is created holding 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}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
-    );
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.equal(rendered, guidanceBlock(PACKAGE_GUIDANCE));
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
+    assert.equal(rendered.includes(SKILL_LOAD_BLOCK_START), false);
 });
 
-test('existing guidance keeps every line between the skill-load block and the package guidance', (context) => {
+test('existing guidance keeps its lines and gains the package guidance', (context) => {
     const homes = makeHomes(context);
     mkdirSync(homes.codexHome);
     writeFileSync(homes.agentsPath, '# pstack model configuration\n\nbug-fix: gpt-6-astra\n');
 
     writeGuidance(homes);
 
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
     assert.equal(
-        readFileSync(homes.agentsPath, 'utf8'),
-        `${EXPECTED_BLOCK}\n# pstack model configuration\n\nbug-fix: gpt-6-astra\n\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+        rendered,
+        `# pstack model configuration\n\nbug-fix: gpt-6-astra\n\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
     );
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
 });
 
 test('a repeat install leaves the file unchanged and reports no write', (context) => {
@@ -93,20 +105,43 @@ test('a repeat install leaves the file unchanged and reports no write', (context
     assert.equal(readFileSync(homes.agentsPath, 'utf8'), afterFirstInstall);
 });
 
-test('an outdated block is replaced in place and the text around it is kept', () => {
-    const outdated = `Intro\n${SKILL_LOAD_BLOCK_START}\nOld wording\n${SKILL_LOAD_BLOCK_END}\nOutro\n`;
+test('a stale skill-load sentence is removed and question and deepen blocks stay', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const questionBlock = `${QUESTION_PRESENTATION_BLOCK_START}\n${QUESTION_POLICY}${QUESTION_PRESENTATION_BLOCK_END}\n`;
+    const deepenBlock = `${DEEPEN_GUIDANCE_BLOCK_START}\n${DEEPEN_GUIDANCE_TEXT}\n${DEEPEN_GUIDANCE_BLOCK_END}\n`;
+    writeFileSync(
+        homes.agentsPath,
+        `${STALE_SKILL_LOAD_BLOCK}\n${guidanceBlock('Old guidance\n')}${questionBlock}${deepenBlock}`,
+    );
 
-    assert.equal(withSkillLoadBlock(outdated), `Intro\n${EXPECTED_BLOCK}Outro\n`);
+    writeGuidance(homes);
+
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.equal(rendered.includes(STALE_SKILL_LOAD_SENTENCE), false);
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
+    assert.equal(rendered.includes(SKILL_LOAD_BLOCK_START), false);
+    assert.ok(rendered.includes(guidanceBlock(PACKAGE_GUIDANCE)));
+    assert.ok(rendered.includes(questionBlock));
+    assert.ok(rendered.includes(deepenBlock));
 });
 
-test('a start marker with no end marker gets a fresh block and keeps the stray text', () => {
+test('a start marker with no end marker stays and no skill name is added', (context) => {
+    const homes = makeHomes(context);
     const broken = `${SKILL_LOAD_BLOCK_START}\nHalf a block\n`;
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, broken);
+
+    writeGuidance(homes);
 
-    assert.equal(withSkillLoadBlock(broken), `${EXPECTED_BLOCK}\n${broken}`);
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.ok(rendered.startsWith(broken));
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
+    assert.ok(rendered.includes(PACKAGE_GUIDANCE_BLOCK_START));
 });
 
 for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
-    test(`a link to package guidance at ${linkName} becomes a file with both blocks`, (context) => {
+    test(`a link to package guidance at ${linkName} becomes a file with the package block`, (context) => {
         const homes = makeHomes(context);
         mkdirSync(homes.codexHome);
         symlinkSync(homes[linkName], homes.agentsPath);
@@ -115,24 +150,21 @@ for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
 
         assert.equal(writtenPath, homes.agentsPath);
         assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), false);
-        assert.equal(
-            readFileSync(homes.agentsPath, 'utf8'),
-            `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
-        );
+        assert.equal(readFileSync(homes.agentsPath, 'utf8'), guidanceBlock(PACKAGE_GUIDANCE));
+        assert.equal(readFileSync(homes.agentsPath, 'utf8').includes('pstack:poteto-mode'), false);
     });
 }
 
-test('a converted file takes the new package guidance on the next install', (context) => {
+test('a converted file takes the new package guidance and drops a stale skill-load block', (context) => {
     const homes = makeHomes(context);
     mkdirSync(homes.codexHome);
-    writeFileSync(homes.agentsPath, `${EXPECTED_BLOCK}\n${guidanceBlock('Old guidance\n')}`);
+    writeFileSync(homes.agentsPath, `${STALE_SKILL_LOAD_BLOCK}\n${guidanceBlock('Old guidance\n')}`);
 
     writeGuidance(homes);
 
-    assert.equal(
-        readFileSync(homes.agentsPath, 'utf8'),
-        `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
-    );
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.equal(rendered, guidanceBlock(PACKAGE_GUIDANCE));
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
 });
 
 test('a link to a file the package does not own is left alone', (context) => {

package/bin/codex-trimmed-sol.test.mjs

@@ -32,6 +32,7 @@ function installInScratchHome(homeDirectory, argumentsList = [], environment = {
             CLAUDE_CONFIG_DIR: undefined,
             LLM_SETTINGS_PROFILES_ROOT: undefined,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_DEEPSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
             CDE_INSTALL_SUBAGENT_MODELS: '0',
             CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',

package/bin/ever-shipped-skills.mjs

@@ -28,6 +28,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'descriptions',
     'e-code-review',
     'e-simplify',
+    'efficient-review',
     'eli5',
     'emergencies',
     'everything-search',