@dalzoubi/dev-agents-sync 2.0.24 → 2.0.26

package/README.md

@@ -51,9 +51,9 @@ npx --yes @dalzoubi/dev-agents-sync@1 init --targets codex
 
 Codex is **opt-in only**. Unlike other targets there is no filesystem signal to detect (there is no `.codex/` directory), so `codex` is never auto-selected — you must pass `--targets codex` explicitly. You can combine it with other targets, e.g. `--targets claude,codex`.
 
-**Output shape.** `init --targets codex` writes six directory-per-skill files — one per agent — at `.agents/skills/<agent>/SKILL.md` (`analyze`, `define`, `implement`, `supervise`, `test`, `validate`), plus a thin root `AGENTS.md` index. Codex discovers these by scanning from the working directory up to the repo root, so each agent lives at its own `.agents/skills/<agent>/SKILL.md` path. Every file carries the managed-by marker, and `update` 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` — covering the full `define`/`deliver` topology listed under [Agents](#agents) — plus a thin root `AGENTS.md` index. Codex discovers these by scanning from the working directory up to the repo root, so each agent lives at its own `.agents/skills/<agent>/SKILL.md` path. Every file carries the managed-by marker, and `update` 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 six agent workflows.
+**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.
 
 **Model-invoked, not slash commands.** Codex Agent Skills are model-invoked: a Codex user triggers an agent through `/skills`, a `$<name>` mention, or implicit selection by the model — *not* by typing a literal `/define`-style slash command the way Claude commands work. This is an accepted approximation of the slash-command UX the other targets provide; the agent content is the same, only the invocation differs.
 
@@ -109,12 +109,11 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 
 ### Hook scripts (managed)
 
-`init` and `update` install four hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files:
+`init` and `update` install three hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files:
 
 | Script | Claude Code event | Purpose |
 |---|---|---|
 | `steering-injector.sh` | `SessionStart` | Surfaces steering context at the start of a session. |
-| `rules-injector.sh` | `SessionStart` | Injects the always-on shared rule bodies (`structured-choices`, `tone`) from `.claude/rules/` into every session; fail-safe (skips absent rules, exits 0). |
 | `managed-file-guard.sh` | `PostToolUse` | Guards managed files against unexpected edits. |
 | `uncommitted-check.sh` | `Stop` | Flags uncommitted work when a session ends. |
 
@@ -122,11 +121,12 @@ Hook scripts use the shell-comment marker form `# managed-by: dev-agents-sync vX
 
 ### settings.json auto-wiring
 
-By default, `init` and `update` also register the four hooks in `.claude/settings.json` so Claude Code runs them. The merge is:
+By default, `init` and `update` also register the three hooks in `.claude/settings.json` so Claude Code runs them. The merge is:
 
 - **Additive** — every existing setting and every consumer-authored hook is preserved untouched.
 - **Idempotent** — running `update` twice produces no duplicate entries.
 - **Tagged** — each injected entry is marked as CLI-managed so it can be identified and removed later without disturbing consumer-authored hooks.
+- **Self-cleaning** — when the toolkit retires a hook, `update` also prunes the CLI-managed registration for it, so no consumer is left with an entry pointing at a script that no longer ships. Only tagged entries are pruned, and only the retired command within them: a consumer-authored entry for the same command is left untouched, and a command you added yourself inside a tagged entry survives alongside. The prune is reported on stderr (`info: dev-agents-sync: pruned N retired hook registration(s)`, counting registrations removed) and is computed — and surfaced in the `--dry-run` result — without writing anything. `rules-injector.sh` is the first retired hook — Claude Code now loads `.claude/rules/*.md` natively, so the hook is redundant.
 
 > **Carve-out.** `settings.json` is a consumer-owned configuration file, **not** a marker-managed file. The CLI never replaces it wholesale; it only merges in its own tagged hook registrations and otherwise leaves the file alone. If `settings.json` contains malformed JSON, `update` fails loud with the stable code `ESETTINGS_PARSE` and leaves the file byte-identical — it will never half-write or clobber an unparseable file.
 
@@ -136,39 +136,49 @@ To install the hook scripts but skip the `settings.json` merge entirely, pass `-
 npx --yes @dalzoubi/dev-agents-sync@1 update --no-hooks-wiring
 ```
 
-With `--no-hooks-wiring`, the hook scripts are still installed under `.claude/hooks/`, but `settings.json` is neither created nor modified — wire the hooks yourself if you want them active.
+With `--no-hooks-wiring`, the hook scripts are still installed under `.claude/hooks/`, but `settings.json` is neither created nor modified — wire the hooks yourself if you want them active. Note that the flag skips the whole merge, **including the self-cleaning de-registration above**: a registration for a retired hook stays in your `settings.json` until you run without the flag or remove it yourself.
 
 ## Agents
 
-Syncing installs six agents that form a spec-driven workflow:
-**Define → Analyze → Implement / Test / Validate**, or **Supervise** to run the
-loop autonomously. Each agent has a matching slash command (for example
-`/define`), and every agent reads the project's `CLAUDE.md` / `AGENTS.md` at the
-start of a session.
+Syncing installs the `define`/`deliver` agent topology: two user-facing
+orchestrators plus their namespaced workers (12 agents in total). Each agent has
+a matching slash command (for example `/define`), and every agent reads the
+project's `CLAUDE.md` / `AGENTS.md` at the start of a session.
+
+**`define` namespace — spec authoring:**
 
 | Agent | Command | Purpose |
 |---|---|---|
-| `define` | `/define` | Planning agent for spec-driven development. Runs a one-question-at-a-time Q&A to turn a vague ask into a spec, then writes it to the project's spec directory. Read-only on source code; produces spec markdown only and auto-runs Analyze when done. |
-| `analyze` | `/analyze` | Pre-implementation spec checker. Scans for unresolved `[NEEDS CLARIFICATION]` markers, checks structure and estimates, and emits a `PASS` or `BLOCKED` verdict. Read-only; reports only. |
-| `implement` | `/implement` | Build-and-refactor agent. Builds features from an approved spec, refactors, debugs, and runs fix-build-test loops. The only agent that changes source files; pauses at checkpoints and won't commit unless asked. |
-| `test` | `/test` | Test and quality agent. Writes unit/integration/regression tests, reproduces bugs with a failing test first, and adds edge cases. Edits **test files only** — never production code. |
-| `validate` | `/validate` | Review and risk agent. Audits the current branch before a PR for security, regressions, accessibility, performance, spec conformance, and coverage gaps. Read-only; outputs a severity-ranked report. |
-| `supervise` | `/supervise <spec-path> [--auto] [--verbose]` | Autonomous TDD orchestrator. Drives test → implement → validate across an approved spec's slices, one at a time, with per-slice cycle budgets and recurrence detection. Delegates to the other agents; pauses on recurring failures, budget exhaustion, or interrupt. |
+| `define` | `/define` | Q&A orchestrator. Runs a one-question-at-a-time Q&A to turn a vague ask into spec/plan/tasks artifacts, then auto-runs `define-analyze`. Read-only on source code. |
+| `define-spec` | `/define-spec` | Writes `spec.md` (requirements). |
+| `define-plan` | `/define-plan` | Writes `plan.md` (technical plan + authoritative working branch). |
+| `define-tasks` | `/define-tasks` | Writes `tasks.md` (slices + estimates). |
+| `define-analyze` | `/define-analyze` | Readiness gate. Scans for unresolved `[NEEDS CLARIFICATION]` markers, checks structure and estimates, and emits a `PASS` or `BLOCKED` verdict. Read-only; reports only. |
+
+**`deliver` namespace — autonomous TDD delivery:**
 
-A bonus command, `/preflight`, runs a pre-review checklist (lint, unit tests,
-and build if relevant) and summarizes what changed. It does not push or open a PR.
+| Agent | Command | Purpose |
+|---|---|---|
+| `deliver` | `/deliver <spec-path> [--auto] [--verbose] [--max-parallel=N]` | Autonomous TDD orchestrator. Drives the four-step cycle `deliver-test → deliver-solution → deliver-refactor → deliver-validate` across an approved spec's slices, with per-slice cycle budgets and recurrence detection; finalizes with `deliver-preflight`. Pauses on recurring failures, budget exhaustion, or interrupt. |
+| `deliver-solution` | `/deliver-solution` | Implementation and debugging worker. Builds features from an approved spec, debugs, and runs fix-build-test loops. Pauses at checkpoints and won't commit unless asked. |
+| `deliver-test` | `/deliver-test` | Test and quality worker. Writes failing-first unit/integration/regression tests and adds edge cases. Edits **test files only** — never production code. |
+| `deliver-refactor` | `/deliver-refactor` | Behavior-preserving refactor worker. Improves production-source structure after tests are green; no new features, never test files. |
+| `deliver-validate` | `/deliver-validate` | Review and risk worker. Audits the current branch before a PR for security, regressions, accessibility, performance, spec conformance, and coverage gaps. Read-only; outputs a severity-ranked report. |
+| `deliver-preflight` | `/deliver-preflight` | Pre-review gate. Runs lint, unit tests, and build if relevant, then summarizes what changed. Does not push or open a PR. |
+| `deliver-document` | `/deliver-document` | End-of-feature docs/CHANGELOG finalization; flips the spec's Status to Shipped. |
 
 ### When to use which
 
 | You want to… | Use |
 |---|---|
 | Scope a new feature or change before writing code | `/define` |
-| Confirm a spec is ready to build from | `/analyze` |
-| Build from an approved spec, refactor, or debug | `/implement` |
-| Add test coverage or pin a bug with a failing test | `/test` |
-| Audit risk right before opening a PR | `/validate` |
-| Build an approved spec largely hands-off, slice by slice | `/supervise` |
-| Run lint/tests/build before review | `/preflight` |
+| Confirm a spec is ready to build from | `/define-analyze` |
+| Build from an approved spec or debug | `/deliver-solution` |
+| Add test coverage or pin a bug with a failing test | `/deliver-test` |
+| Clean up structure once the scoped tests are green | `/deliver-refactor` |
+| Audit risk right before opening a PR | `/deliver-validate` |
+| Build an approved spec largely hands-off, slice by slice | `/deliver` |
+| Run lint/tests/build before review | `/deliver-preflight` |
 
 ## Common Flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.0.24",
+  "version": "2.0.26",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/commands/init.mjs

@@ -17,8 +17,7 @@ import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writ
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
 import { seedSteering, steeringSummary } from '../steering.mjs';
-import { mergeHookSettings } from '../settings.mjs';
-import { collectHookPaths, hookScriptsForInstalled } from '../hooks.mjs';
+import { collectHookPaths, hookScriptsForInstalled, wireHookSettings } from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -134,6 +133,7 @@ export async function runInit(consumerCwd, opts = {}) {
   const claudeMdPath = path.join(consumerCwd, 'CLAUDE.md');
 
   if (dryRun) {
+    const plannedKeys = plannedWrites.map(({ relKey }) => relKey);
     // Run inject in dry-run mode to compute the planned change.
     const claudeMdResult = routingContent
       ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
@@ -144,13 +144,24 @@ export async function runInit(consumerCwd, opts = {}) {
       ? seedSteering(consumerCwd, { dryRun: true })
       : null;
 
+    // Compute the planned settings.json merge too, mirroring update's dry-run
+    // branch: skipping it would under-report a real, intended change to
+    // consumer-owned state — and `init` over an existing .claude/ can meet a
+    // pre-retirement settings.json (same exposure the wiring call below cites).
+    // The merge writes nothing in dry-run, so settings.json stays byte-identical.
+    const plannedPrunedRetired =
+      claudeTargetActive && !noHooksWiring
+        ? wireHookSettings(consumerCwd, hookScriptsForInstalled(plannedKeys), { dryRun: true })
+        : [];
+
     return {
       dryRun: true,
       resolvedVersion,
       targets: resolvedTargets,
       plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
-      files: plannedWrites.map(({ relKey }) => relKey),
+      files: plannedKeys,
       claudeMd: claudeMdResult,
+      prunedRetired: plannedPrunedRetired,
       steering,
     };
   }
@@ -203,11 +214,11 @@ export async function runInit(consumerCwd, opts = {}) {
   // additive + idempotent and fails loud (ESETTINGS_PARSE) on a malformed file.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
   const hookPaths = collectHookPaths(installedHookKeys);
+  let prunedRetired = [];
   if (claudeTargetActive && !noHooksWiring) {
-    const hookSpec = hookScriptsForInstalled(installedHookKeys);
-    if (hookSpec.length > 0) {
-      mergeHookSettings(consumerCwd, hookSpec);
-    }
+    // Unconditional on the spec being non-empty: the prune half needs no spec,
+    // and `init` over an existing .claude/ can meet a pre-retirement settings.json.
+    prunedRetired = wireHookSettings(consumerCwd, hookScriptsForInstalled(installedHookKeys));
   }
 
   writeLockfile(consumerCwd, {
@@ -225,6 +236,7 @@ export async function runInit(consumerCwd, opts = {}) {
     plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
     files: plannedWrites.map(({ relKey }) => relKey),
     hooks: hookPaths,
+    prunedRetired,
     steering,
   };
 }

package/src/commands/update.mjs

@@ -15,8 +15,8 @@ import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writ
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
 import { seedSteering, steeringSummary } from '../steering.mjs';
-import { mergeHookSettings, DEFAULT_HOOK_SCRIPTS } from '../settings.mjs';
-import { collectHookPaths, hookScriptsForInstalled } from '../hooks.mjs';
+import { DEFAULT_HOOK_SCRIPTS } from '../settings.mjs';
+import { collectHookPaths, hookScriptsForInstalled, wireHookSettings } from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -144,19 +144,21 @@ export async function runUpdate(consumerCwd, opts = {}) {
     // here (the short-circuit's whole point is to avoid a fetch); instead we wire
     // only the hook scripts that already exist on disk. The merge is additive +
     // idempotent, so running twice == once. --dry-run still writes nothing.
-    if (claudeTargetActive && !noHooksWiring && !dryRun) {
+    let prunedRetired = [];
+    if (claudeTargetActive && !noHooksWiring) {
       const hookSpec = DEFAULT_HOOK_SCRIPTS.filter((h) =>
         existsSync(path.join(consumerCwd, h.command)),
       );
-      if (hookSpec.length > 0) {
-        mergeHookSettings(consumerCwd, hookSpec);
-      }
+      // Unconditional on hookSpec.length: the prune needs no spec, so a consumer
+      // with no hook scripts on disk still gets retired registrations removed.
+      prunedRetired = wireHookSettings(consumerCwd, hookSpec, { dryRun });
     }
 
     return {
       upToDate: true,
       resolvedVersion: lock.resolvedVersion,
       message: `already up to date at v${lock.resolvedVersion}`,
+      prunedRetired,
       steering,
     };
   }
@@ -185,18 +187,27 @@ export async function runUpdate(consumerCwd, opts = {}) {
   const orphans = computeOrphans(consumerCwd, scopedKeys, lock.targets);
 
   if (dryRun) {
+    const plannedKeys = plannedWrites.map(({ relKey }) => relKey);
     // Compute the planned CLAUDE.md change so callers can inspect it without
     // the result shape silently diverging from the init --dry-run contract.
     const claudeMdResult = routingContent
       ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
       : null;
+    // Compute the planned settings.json merge too — a dry run that skipped it
+    // would under-report a real, intended change to consumer-owned state. The
+    // merge writes nothing in dry-run, so settings.json stays byte-identical.
+    const plannedPrunedRetired =
+      claudeTargetActive && !noHooksWiring
+        ? wireHookSettings(consumerCwd, hookScriptsForInstalled(plannedKeys), { dryRun: true })
+        : [];
     return {
       dryRun: true,
       resolvedVersion: targetVersion,
       previousVersion: lock.resolvedVersion,
-      files: plannedWrites.map(({ relKey }) => relKey),
+      files: plannedKeys,
       claudeMd: claudeMdResult,
       plannedPrune: orphans,
+      prunedRetired: plannedPrunedRetired,
       steering,
     };
   }
@@ -239,11 +250,10 @@ export async function runUpdate(consumerCwd, opts = {}) {
   // on a malformed settings.json, leaving it byte-identical.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
   const hookPaths = collectHookPaths(installedHookKeys);
+  let prunedRetired = [];
   if (claudeTargetActive && !noHooksWiring) {
-    const hookSpec = hookScriptsForInstalled(installedHookKeys);
-    if (hookSpec.length > 0) {
-      mergeHookSettings(consumerCwd, hookSpec);
-    }
+    // Unconditional on the spec being non-empty: the prune half needs no spec.
+    prunedRetired = wireHookSettings(consumerCwd, hookScriptsForInstalled(installedHookKeys));
   }
 
   // Prune orphans: marker-bearing managed files no longer shipped. Delete in
@@ -293,6 +303,7 @@ export async function runUpdate(consumerCwd, opts = {}) {
     hooks: hookPaths,
     pruned,
     prunedCount: pruned.length,
+    prunedRetired,
     summary: pruneSummary,
     steering,
   };

package/src/hooks.mjs

@@ -9,7 +9,7 @@
  * CLI only wires hooks that genuinely shipped in the resolved version.
  */
 
-import { DEFAULT_HOOK_SCRIPTS } from './settings.mjs';
+import { DEFAULT_HOOK_SCRIPTS, mergeHookSettings } from './settings.mjs';
 
 /** True for a FileMap key that is a managed hook script (claude/hooks/*.sh). */
 function isHookKey(relKey) {
@@ -45,3 +45,40 @@ export function hookScriptsForInstalled(relKeys) {
   const installed = new Set(collectHookPaths(relKeys));
   return DEFAULT_HOOK_SCRIPTS.filter((h) => installed.has(h.command));
 }
+
+/**
+ * Merges `hookScripts` into the consumer's .claude/settings.json and reports any
+ * retired registrations the merge de-registered. Shared by init and update so
+ * all three wiring call sites report identically.
+ *
+ * Called even when `hookScripts` is EMPTY: the prune half of the merge needs no
+ * spec, so a consumer with no hook scripts on disk still gets stale
+ * registrations for retired hooks cleaned up. With nothing to add and nothing to
+ * prune the merge is a no-op that writes nothing — it does not create the file.
+ *
+ * De-registration is a real edit to consumer-owned state, so it is never silent
+ * (§6): it emits the same `info: dev-agents-sync: ...` line as update's
+ * orphaned-file prune. Nothing is printed under --dry-run (planning is not
+ * doing) or when nothing was pruned (no spurious line on every run).
+ *
+ * The line reports `prunedRetiredCount` — REGISTRATIONS removed — not
+ * `prunedRetired.length`, which is the same list deduped by command. One retired
+ * command registered under two event buckets is two registrations gone from the
+ * consumer's file; saying "1" there would under-report the edit we just made.
+ *
+ * @returns {string[]} the DISTINCT retired commands de-registered (or, in
+ *   dry-run, that would be de-registered) by this call. Always an array. Callers
+ *   match on it ("was X pruned?"); the user-facing count stays inside this
+ *   function, which is the toolkit's single reporting site for the prune.
+ */
+export function wireHookSettings(consumerCwd, hookScripts, { dryRun = false } = {}) {
+  const { prunedRetired, prunedRetiredCount } = mergeHookSettings(consumerCwd, hookScripts, {
+    dryRun,
+  });
+  if (!dryRun && prunedRetiredCount > 0) {
+    process.stderr.write(
+      `info: dev-agents-sync: pruned ${prunedRetiredCount} retired hook registration(s)\n`,
+    );
+  }
+  return prunedRetired;
+}