@dalzoubi/dev-agents-sync 3.0.10 → 3.0.12

package/README.md

@@ -51,13 +51,27 @@ npx --yes @dalzoubi/dev-agents-sync@1 init --targets codex
 
 Codex is **opt-in only** so an existing `AGENTS.md` or `.codex/` configuration is never adopted accidentally. Pass `--targets codex` explicitly; you can combine it with other targets, e.g. `--targets claude,codex`.
 
-**Output shape.** `init --targets codex` writes one directory-per-skill file per agent at `.agents/skills/<agent>/SKILL.md`, a native custom-agent definition at `.codex/agents/<agent>.toml`, the shared lifecycle scripts under `.codex/hooks/`, their adapter and `.codex/hooks.json`, plus a thin root `AGENTS.md` index. Every file carries the managed-by marker, and `update`, `status`, and `check` scope to these paths exactly like the other targets.
+**Output shape.** `init --targets codex` writes one directory-per-skill file per agent at `.agents/skills/<agent>/SKILL.md`, a native custom-agent definition at `.codex/agents/<agent>.toml`, the shared lifecycle scripts under `.codex/hooks/`, their adapter and `.codex/hooks.json`, plus a thin root `AGENTS.md` index. Claude hook wiring uses `.claude/settings.json`. Every file carries the managed-by marker, and `update`, `status`, and `check` scope to these paths exactly like the other targets.
 
 **Standalone.** Codex is a first-class standalone target. Each emitted `SKILL.md` bundles the workflow support docs it references, so a Codex-only install does **not** need `.claude/skills/*.md`, `.cursor/`, or any other target files to run the agent workflows.
 
 **Invocation and delegation.** Codex Agent Skills are model-invoked through `/skills`, a `$<name>` mention, or implicit selection. The matching `.codex/agents/*.toml` definitions also make the topology available to Codex's native subagent delegation.
 
-**Hooks.** The Codex target registers the same nine lifecycle policies as the Claude target in project-local `.codex/hooks.json`; Claude wiring remains in `.claude/settings.json`. Codex asks the user to trust project hooks the first time it loads them; review with `/hooks` and choose the appropriate trust option. The adapter translates Codex `apply_patch` events into the shared Edit/Write contract, so the same blocking and warning scripts remain the source of truth.
+For example: `$define Add export support`, `$deliver docs/specs/<spec>/spec.md --auto`,
+`$deliver-solution Fix the export filename`, or `$deliver-validate docs/specs/<spec>/`.
+The generated skills retain their command arguments (`$ARGUMENTS`) and flags,
+including `--review-all`, `--verbose`, `--max-parallel=N`, and `--branch=<name>`.
+Their runtime mapping translates `Agent`, `AskUserQuestion`, file tools, and
+shell tools to Codex equivalents. Delegated custom agents carry the role and
+support docs; main-thread command routing stays in the skill. Always-applied
+rules accompany both forms. Models and runtime permissions inherit from Codex.
+
+**Steering when switching.** Codex-only `init` and `update` seed consumer-owned
+top-level `steering/`, without creating `.claude/`. If `.claude/steering/` already
+exists, they reuse it and preserve its contents. Mixed Claude/Codex installs keep
+that existing layout. `--dry-run` writes neither steering nor runtime files.
+
+**Hooks.** The Codex target registers the same lifecycle policies as the Claude target in project-local `.codex/hooks.json`; Claude wiring remains in `.claude/settings.json`. Codex asks the user to trust project hooks the first time it loads them; review with `/hooks` and choose the appropriate trust option. The adapter translates Codex `apply_patch` events into the shared Edit/Write contract, reconstructing resulting content for updates and checking rename destinations. Shared scripts run from the git root even when the session starts in a subdirectory. Windows requires Git Bash. Hook execution or patch-reconstruction failures produce diagnostics rather than a false clean result.
 
 **Manual removal.** Like every target, there is no uninstall or cleanup command. Dropping `codex` from the `targets` in `.dev-agents-sync.json` stops future writes, but the already-written `.agents/skills/<agent>/SKILL.md`, `.codex/`, and root `AGENTS.md` files are removed manually.
 
@@ -107,7 +121,7 @@ For the `claude` target, `init` and `update` seed consumer-owned steering and au
 
 ### Steering scaffold (consumer-owned)
 
-The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions.md`, `glossary.md`, `architecture.md`, and `delivery-log.md` — on first run. These files are **consumer-owned**: they carry no managed-by marker, are never tracked in the lockfile, and are **never overwritten** once they exist. Agents read all four at session start and append to them; the toolkit only seeds the blank files once. Editing them is expected.
+The CLI seeds a blank steering scaffold under `.claude/steering/` for Claude or an existing shared history, and top-level `steering/` for a fresh Codex-only install — `decisions.md`, `glossary.md`, `architecture.md`, and `delivery-log.md` — on first run. These files are **consumer-owned**: they carry no managed-by marker, are never tracked in the lockfile, and are **never overwritten** once they exist. Agents read all four at session start and append to them; the toolkit only seeds the blank files once. Editing them is expected.
 
 `delivery-log.md` is the feedback channel between the two agent namespaces: `deliver-document` appends one dated retrospective per shipped feature, and `define` reads that history to calibrate future estimates and cycle budgets.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "3.0.10",
+  "version": "3.0.12",
   "type": "module",
   "description": "CLI that syncs managed dev-agent workflows into Claude Code, Cursor, Copilot, and Codex projects.",
   "license": "UNLICENSED",

package/src/commands/init.mjs

@@ -18,6 +18,7 @@ import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
 import { seedSteering, steeringSummary } from '../steering.mjs';
 import {
+  codexHooksSummary,
   collectHookPaths,
   hookScriptsForInstalled,
   hooksSummary,
@@ -133,6 +134,7 @@ export async function runInit(consumerCwd, opts = {}) {
   // We read from the normalised map so the content is available regardless of
   // whether the `skills` dir ends up in the consumer's scoped file set.
   const claudeTargetActive = resolvedTargets.includes('claude');
+  const steeringTarget = claudeTargetActive ? 'claude' : resolvedTargets.includes('codex') ? 'codex' : null;
   const routingContent = claudeTargetActive
     ? (normalized['claude/skills/auto-route.md'] ?? null)
     : null;
@@ -145,9 +147,9 @@ export async function runInit(consumerCwd, opts = {}) {
       ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
       : null;
 
-    // Steering seed plan (claude target only). seed-if-absent; writes nothing in dry-run.
-    const steering = claudeTargetActive
-      ? seedSteering(consumerCwd, { dryRun: true })
+    // Steering seed plan for Claude or Codex. Writes nothing in dry-run.
+    const steering = steeringTarget
+      ? seedSteering(consumerCwd, { dryRun: true, target: steeringTarget })
       : null;
 
     // Compute the planned settings.json merge too, mirroring update's dry-run
@@ -207,12 +209,12 @@ export async function runInit(consumerCwd, opts = {}) {
     injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent);
   }
 
-  // Seed the consumer-owned steering scaffold (claude target only). Seed-if-absent:
+  // Seed the consumer-owned steering scaffold for Claude or Codex. Seed-if-absent:
   // never overwrites edited steering, never recorded in the lockfile (it is unmanaged
   // by design). Fails loud with ESTEER_WRITE on a write error.
   let steering = null;
-  if (claudeTargetActive) {
-    steering = seedSteering(consumerCwd);
+  if (steeringTarget) {
+    steering = seedSteering(consumerCwd, { target: steeringTarget });
     process.stderr.write(`info: dev-agents-sync: ${steeringSummary(steering)}\n`);
   }
 
@@ -220,6 +222,8 @@ export async function runInit(consumerCwd, opts = {}) {
   // only), unless the consumer opted out with --no-hooks-wiring. The merge is
   // additive + idempotent and fails loud (ESETTINGS_PARSE) on a malformed file.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
+  const codexNotice = codexHooksSummary(installedHookKeys);
+  if (codexNotice) process.stderr.write(`info: dev-agents-sync: ${codexNotice}\n`);
   const hookPaths = collectHookPaths(installedHookKeys);
   const hookRegistrations = hookScriptsForInstalled(installedHookKeys);
   // Report the install BEFORE wiring, so the pair reads in the order it happened

package/src/commands/update.mjs

@@ -17,6 +17,7 @@ import { injectClaudeMd } from '../claudeMd.mjs';
 import { seedSteering, steeringSummary } from '../steering.mjs';
 import { DEFAULT_HOOK_SCRIPTS } from '../settings.mjs';
 import {
+  codexHooksSummary,
   collectHookPaths,
   hookScriptsForInstalled,
   hooksSummary,
@@ -130,14 +131,15 @@ export async function runUpdate(consumerCwd, opts = {}) {
 
   const targetVersion = resolveRange(availableTags, lock.range);
 
-  // Seed the consumer-owned steering scaffold (claude target only), seed-if-absent,
+  // Seed the consumer-owned steering scaffold for Claude or Codex, seed-if-absent,
   // BEFORE the up-to-date short-circuit so existing consumers adopt steering on any
   // `update` — not only when a version bump is available. Never overwrites edited
   // steering; never recorded in the lockfile (unmanaged by design); respects --dry-run.
   const claudeTargetActive = lock.targets.includes('claude');
+  const steeringTarget = claudeTargetActive ? 'claude' : lock.targets.includes('codex') ? 'codex' : null;
   let steering = null;
-  if (claudeTargetActive) {
-    steering = seedSteering(consumerCwd, { dryRun });
+  if (steeringTarget) {
+    steering = seedSteering(consumerCwd, { dryRun, target: steeringTarget });
     if (!dryRun) {
       process.stderr.write(`info: dev-agents-sync: ${steeringSummary(steering)}\n`);
     }
@@ -278,6 +280,8 @@ export async function runUpdate(consumerCwd, opts = {}) {
   // unless --no-hooks-wiring. Additive + idempotent; fails loud (ESETTINGS_PARSE)
   // on a malformed settings.json, leaving it byte-identical.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
+  const codexNotice = codexHooksSummary(installedHookKeys);
+  if (codexNotice) process.stderr.write(`info: dev-agents-sync: ${codexNotice}\n`);
   const hookPaths = collectHookPaths(installedHookKeys);
   const hookRegistrations = hookScriptsForInstalled(installedHookKeys);
   // Same pairing as init: install line, then any retired-prune line emitted by

package/src/hooks.mjs

@@ -11,6 +11,13 @@
 
 import { DEFAULT_HOOK_SCRIPTS, mergeHookSettings } from './settings.mjs';
 
+/** Report installed Codex configuration without changing the user's trust. */
+export function codexHooksSummary(relKeys) {
+  return relKeys.includes('codex/.codex/hooks.json')
+    ? 'Codex hooks installed at .codex/hooks.json — review and trust with /hooks in Codex; Windows requires Git Bash'
+    : null;
+}
+
 /**
  * True for a FileMap key that is a managed hook script (claude/hooks/*.sh).
  *

package/src/steering.mjs

@@ -69,14 +69,19 @@ class SteeringWriteError extends Error {
  * each scaffold file only when it is absent.
  *
  * @param {string} consumerCwd
- * @param {{ dryRun?: boolean }} [opts]
+ * @param {{ dryRun?: boolean, target?: 'claude' | 'codex' }} [opts]
  * @returns {{ seeded: string[], present: string[], dryRun: boolean }}
  *   seeded  — relative paths (steering/<name>) that were (or would be) written.
  *   present — relative paths left untouched because they already existed.
  */
 export function seedSteering(consumerCwd, opts = {}) {
-  const { dryRun = false } = opts;
-  const steeringDir = path.join(consumerCwd, '.claude', 'steering');
+  const { dryRun = false, target = 'claude' } = opts;
+  // Reuse Claude history when switching runtimes. A fresh Codex-only install
+  // uses the top-level layout already supported by every workflow and hook.
+  const claudeSteering = path.join(consumerCwd, '.claude', 'steering');
+  const steeringDir = target === 'codex' && !existsSync(claudeSteering)
+    ? path.join(consumerCwd, 'steering')
+    : claudeSteering;
 
   const seeded = [];
   const present = [];
@@ -112,7 +117,7 @@ export function seedSteering(consumerCwd, opts = {}) {
     }
   } catch (err) {
     throw new SteeringWriteError(
-      `ESTEER_WRITE: could not write ${path.join('.claude', 'steering')} — check directory permissions`,
+      `ESTEER_WRITE: could not write ${path.relative(consumerCwd, steeringDir)} — check directory permissions`,
       { cause: err },
     );
   }

package/tests/codex-steering.test.mjs

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runInit } from '../src/commands/init.mjs';
+import { runUpdate } from '../src/commands/update.mjs';
+import { codexHooksSummary } from '../src/hooks.mjs';
+
+const opts = {
+  targets: ['codex'], availableTags: ['v1.0.0'],
+  fetcher: async () => ({ 'codex/AGENTS.md': '<!-- managed-by: dev-agents-sync v1.0.0 -->\n# Agents\n' }),
+};
+async function workspace(run) {
+  const dir = mkdtempSync(path.join(tmpdir(), 'codex-steering-'));
+  try { await run(dir); } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+describe('Codex-only steering adoption', () => {
+  it('reports hook trust only when a Codex hook manifest was installed', () => {
+    assert.match(codexHooksSummary(['codex/.codex/hooks.json']), /review and trust with \/hooks/);
+    assert.equal(codexHooksSummary(['claude/hooks/spec-approval-gate.sh']), null);
+  });
+  it('seeds the shared layout without creating .claude and preserves user history on update', () => workspace(async dir => {
+    await runInit(dir, opts);
+    const file = path.join(dir, 'steering', 'decisions.md');
+    assert.ok(existsSync(file));
+    assert.ok(!existsSync(path.join(dir, '.claude')));
+    writeFileSync(file, '# Decisions\nKeep this decision\n');
+    const result = await runUpdate(dir, opts);
+    assert.equal(result.upToDate, true);
+    assert.equal(readFileSync(file, 'utf8'), '# Decisions\nKeep this decision\n');
+  }));
+
+  it('reuses existing Claude steering without splitting its history', () => workspace(async dir => {
+    mkdirSync(path.join(dir, '.claude', 'steering'), { recursive: true });
+    const file = path.join(dir, '.claude', 'steering', 'decisions.md');
+    writeFileSync(file, '# Decisions\nPrevious Claude decision\n');
+    await runInit(dir, opts);
+    assert.equal(readFileSync(file, 'utf8'), '# Decisions\nPrevious Claude decision\n');
+    assert.ok(existsSync(path.join(dir, '.claude', 'steering', 'delivery-log.md')));
+    assert.ok(!existsSync(path.join(dir, 'steering')));
+  }));
+
+  it('seeds missing Codex steering during an already-current update', () => workspace(async dir => {
+    await runInit(dir, opts);
+    rmSync(path.join(dir, 'steering'), { recursive: true });
+    await runUpdate(dir, opts);
+    assert.ok(existsSync(path.join(dir, 'steering', 'delivery-log.md')));
+  }));
+
+  it('does not write steering or runtime files under dry-run', () => workspace(async dir => {
+    const result = await runInit(dir, { ...opts, dryRun: true });
+    assert.equal(result.steering.seeded.length, 4);
+    assert.ok(!existsSync(path.join(dir, 'steering')));
+    assert.ok(!existsSync(path.join(dir, 'AGENTS.md')));
+    await runInit(dir, opts);
+    rmSync(path.join(dir, 'steering'), { recursive: true });
+    await runUpdate(dir, { ...opts, dryRun: true });
+    assert.ok(!existsSync(path.join(dir, 'steering')));
+  }));
+});